open-index/open-npm huggingface dataset:
npm package: @matrixai/async-locks
Description: Asynchronous locking utilities
Author: Roger Qiu
Latest version: 5.0.2

# js-async-locks

Asynchronous lock utilities.

JavaScript exposes the ability to create interleaved execution of asynchronous
operations. When this is done with shared state between asynchronous
overlapping functions that perform partial state transitions, this can lead to
race conditions or data corruption and clobbering, or just invalid pre-condition
or post-condition behaviour.

This library provides multiple synchronization constructs that allow one to
precisely control concurrent operations. These constructs are intended for
pessimistic concurrency control. If you can prefer to use optimistic concurrency
control mechanisms. But that is outside the scope of this library. In many cases
you cannot use optimistic methods, and thus you need this library.

## Installation

```sh
npm install --save @matrixai/async-locks
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-async-locks/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```
npm package: @matrixai/async-monitor
Description: Asynchronous monitor
Author: Roger Qiu
Latest version: 0.0.2

# js-async-monitor

Asynchronous monitor.

Because decorators are experimental, you must enable: `"experimentalDecorators": true` in your `tsconfig.json` to use this library.

## Installation

```sh
npm install --save @matrixai/async-monitor
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run ts-node
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-async-monitor/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```
npm package: @matrixai/contexts
Description: Asynchronous contexts
Author: Roger Qiu
Latest version: 2.0.2

# js-contexts

Asynchronous contexts.

## Installation

```sh
npm install --save @matrixai/contexts
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint code, markdown, scripts
npm run lint
# automatically fix linting errors
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-contexts/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```
npm package: @matrixai/errors
Description: Exception System
Author: Roger Qiu
Latest version: 2.1.3

# js-errors

Exception system with error chaining.

## Installation

```sh
npm install --save @matrixai/errors
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-errors/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```
npm package: @matrixai/exec
Description: EXEC
Author: Matrix AI
Latest version: 1.0.3

# js-exec

This exposes `execvp` to Node.js. This allows running a child process that replaces the parent process image. This is not possible on Windows, if you run this on Windows, expect an exception!

## Installation

```sh
npm install --save @matrixai/exec
```

## Usage

exec can be used in the following way.

```ts
import { exec } from '@matrixai/exec';
// This should output the current enviroment while adding `test_env` to it.
exec.execvp(
  'node',
  [
    '-e',
    'console.log(process.env)',
  ],
  {
    test_env: 'this value'
  },
);
```

Note that only linux and mac platforms are supported.

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the native objects
npm run prebuild
# build the dist and native objects
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Cargo/Rust targets

Cargo is a cross-compiler. The target structure looks like this:

```
<arch><sub>-<vendor>-<sys>-<abi>
```

For example:

```
x86_64-unknown-linux-gnu
x86_64-pc-windows-msvc
aarch64-apple-darwin
x86_64-apple-darwin
```

The available target list is in `rustc --print target-list`.

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-exec/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```
npm package: @matrixai/js-virtualtar
Description: Virtualised bindings for generating a tar file
Author: Matrix AI
Latest version: 2.0.1

# js-virtualtar

VirtualTar is a library used to create tar files using a virtual file system or
a file tree. This library aims to provide a platform-agnostic generator-parser
pair to create tar files without the reliance on a file system.

## Installation

```sh
npm install --save @matrixai/virtualtar
```

## Usage

See the example usage in [tests](tests).

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist objects
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-virtualtar/

### Publishing

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```

## License

`js-virtualtar` is licensed under Apache-2.0, you may read the terms of the
license [here](LICENSE).
npm package: @matrixai/mdns
Description: Multicast DNS Stack
Author: Matrix AI
Latest version: 2.0.7

# js-mdns

Multicast DNS Stack for TypeScript/JavaScript Applications.

## Installation

```sh
npm install --save @matrixai/mdns
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-mdns/

### Publishing

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```

## License

js-mdns is licensed under Apache-2.0, you may read the terms of the license [here](LICENSE).
npm package: @matrixai/pagination
Description: Offset-based and cursor-based pagination utilities
Author: Roger Qiu
Latest version: 1.1.1

# Pagination

## Seek Index or Key

The seek index or key must be totally-ordered and strictly monotonic. If the seek index or key is not strictly monotonic, it's possible to skip items when doing the pagination because the seek in cursor pagination is assumed to be exclusive. If it is not totally ordered, then pagination may not be consistent as certain items may move ahead or behind on depending on non-deterministic factors.

If you are using date or timestamps as the as the seek, you must realise that JavaScript `Date` object only has up to millisecond precision. If you are storing more precise timestamps, during the comparison operation for pagination, you must do the comparison at millisecond precision because when JavaScript is sending timestamps to the server, it would only produce millisecond precise timestamps. Alternatively you can ensure that your backend is only storing only millisecond precise timestamps.

## Offset

Offset pagination relies on a seek and limit number.

Consider the resource we are paginating is:

```
['A', 'B', 'C', 'D']
```

The seek index starts at 0 and it is inclusive.

The limit is the desired length of the returned pagination view.

A seek and limit of `[0, 2]` would return `['A', 'B']`.

Page numbers start from 1. However we refer to them with a page index that starts at 0.

The total represents the total number of items when the pagination was fetched. The true total of items may have changed on the server side since fetching a pagination.

## Cursor

Cursor pagination relies on unique orderable seek key.

Consider the resource we are paginating is:

```
['A', 'B', 'C', 'D', 'E']
```

Assume that the seek key is `[0, 1, 2, 3, 4]`:

* Using `direction = true`, `seek = 0` and `limit = 2`, you would get `['B', 'C']`.
* Using `direction = false`, `seek = 3` and `limit = 2`, you would get `['B', 'C']`.
* Using `direction = null`, `seekAfter = 1`, `seekBefore = 3`, you would get `['C']`.

Notice that the `seek`, `seekStart` and `seekEnd` are all exclusive. This is required so that paging doesn't show results that overlap with existing results. This is because the next or previous page is fetched by using the seek key of the first or last item.

Therefore to get the `['A']`, you would need to seek with `0 - 1`. Or at least some way of subtracting the seek key.

Valid seek keys include integers and dates.

There can be an extra parameter called `sort` that would sort the results according the seek key in descending or ascending manner. Here we assume ascending sort. This is however not a concern of pagination, but a concern of how results should be displayed. Therefore the `direction` parameter controls the direction of the seek, but not the order of the results.

Cursor pagination does not allow random access of the pages. You can however randomly access if you know the seek key you want.

## Publishing

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```
npm package: @matrixai/resources
Description: Resource context management
Author: Roger Qiu
Latest version: 2.0.1

# js-resources

Resource context management inspired by Python's `with` context manager and Haskell's bracket pattern.

## Installation

```sh
npm install --save @matrixai/resources
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-resources/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
npm package: @matrixai/table
Description: Table data structure
Author: Roger Qiu
Latest version: 2.0.0

# js-table

Table data structure.

## Installation

```sh
npm install --save @matrixai/table
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-table/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```
npm package: @matrixai/timer
Description: Stopwatch timer object
Author: Roger Qiu
Latest version: 2.1.1

# js-timer

This library provides a reified `Timer` replacing the imperative `setTimeout` in JS. This is useful for keeping track of elapsed time and calculating how time is left. Think of this as a "Stopwatch".

This does not use `Date.now()`, it uses `Performance` API.

## Installation

```sh
npm install --save @matrixai/timer
```

## Usage

```ts
import { Timer } from '@matrixai/timer';

const t1 = new Timer(() => 2, 10);
const result = await t1;
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-timer/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```
npm package: @matrixai/workers
Description: Multithreaded Workers
Author: Roger Qiu
Latest version: 2.0.1

# js-workers

Workers is the library for multi-threading in MatrixAI's JavaScript/TypeScript applications. It is based on top of threads.js.

Currently no support for Mobile OSes.

Note that only `ArrayBuffer` can be zero-copy transferred to the worker threads. This means if you are wroking with Node `Buffer` you must first slice and copy the `ArrayBuffer` out of the Node `Buffer`.

```ts
const b = Buffer.from('hello world');
const ab = b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
```

The following diagram is an example architecture of using `ArrayBuffer`:

```
┌───────────────────────┐
│      Main Thread      │
│                       │
│     ┌───────────┐     │
│     │Node Buffer│     │
│     └─────┬─────┘     │          ┌────────────────────────┐
│           │           │          │                        │
│     Slice │ Copy      │          │      Worker Thread     │
│           │           │          │                        │
│  ┌────────▼────────┐  │ Transfer │  ┌──────────────────┐  │
│  │Input ArrayBuffer├──┼──────────┼──►                  │  │
│  └─────────────────┘  │          │  └─────────┬────────┘  │
│                       │          │            │           │
│                       │          │    Compute │           │
│                       │          │            │           │
│  ┌─────────────────┐  │          │  ┌─────────▼────────┐  │
│  │                 ◄──┼──────────┼──┤Output ArrayBuffer│  │
│  └─────────────────┘  │ Transfer │  └──────────────────┘  │
│                       │          │                        │
│                       │          │                        │
└───────────────────────┘          └────────────────────────┘
```

See the benchmarks and tests for examples of using this library.

## Installation

```sh
npm install --save @matrixai/workers
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

## Benchmarks

```sh
npm run bench
```

View benchmarks here: https://github.com/MatrixAI/js-workers/blob/master/benches/results/WorkerManager.chart.html with https://raw.githack.com/

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-workers/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```
npm package: @matrixai/ws
Description: WebSocket Streaming Wrapper
Author: Matrix AI
Latest version: 2.0.5

# js-ws

WebSocket library for TypeScript/JavaScript applications.

This is built on top of the [ws](https://github.com/websockets/ws) library, providing a multiplexed WebStreams API on top of WebSocket.

## Installation

```sh
npm install --save @matrixai/ws
```

### Browser Usage

To use `WebSocketClient` in a browser environment, you will need to polyfill:

* [`buffer`](https://nodejs.org/api/buffer.html)
* [`perf_hooks`](https://nodejs.org/api/perf_hooks.html)

A good choice for a `buffer` polyfill is [`feross/buffer`](https://github.com/feross/buffer)

To polyfill `perf_hooks`, you can alias the `perf_hooks` using your bundler of choice with a file containing the following code:

```ts
const { performance } = globalThis;
export { performance };
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-ws/

### Publishing

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```

## License

js-ws is licensed under Apache-2.0, you may read the terms of the license [here](LICENSE).