dsp

Small & fast disposables.

Example

import { Dsp } from "@monstermann/dsp";

const dspA = Dsp.create();
const dspB = Dsp.create();

Dsp.add(dspA, () => console.log(1));
Dsp.add(dspA, () => console.log(2));
Dsp.add(dspB, () => console.log(3));
Dsp.add(dspB, () => console.log(4));
Dsp.add(dspA, dspB);

Dsp.dispose(dspA); // Prints: 4, 3, 2, 1

Installation

npm install @monstermann/dsp

pnpm add @monstermann/dsp

yarn add @monstermann/dsp

bun add @monstermann/dsp

Benchmarks

Apple M1 Max, Node v24.0.1

bench-dispose-cbs

Setup: Create a disposable with N callbacks attached
Bench: Dispose above

name	ops/sec	time/op	margin	samples
Dsp.dispose(dsp) x 1	33M	23ns	±0.07%	43M
Dsp.dispose(dsp) x 10	24M	40ns	±0.11%	25M
Dsp.dispose(dsp) x 100	4M	237ns	±0.07%	4M
DisposableStack.dispose() x 1	22M	51ns	±0.07%	20M
DisposableStack.dispose() x 10	4M	245ns	±0.07%	4M
DisposableStack.dispose() x 100	468K	2µs	±0.10%	463K

bench-dispose-dsps-wide

Setup: Create a disposable with N other disposables attached
Bench: Dispose above

name	ops/sec	time/op	margin	samples
Dsp.dispose(dsp) x 1	27M	30ns	±0.07%	34M
Dsp.dispose(dsp) x 10	9M	118ns	±0.11%	8M
Dsp.dispose(dsp) x 100	986K	1µs	±4.23%	877K
DisposableStack.dispose() x 1	12M	83ns	±0.07%	12M
DisposableStack.dispose() x 10	2M	569ns	±0.08%	2M
DisposableStack.dispose() x 100	188K	5µs	±0.09%	186K

bench-dispose-dsps-deep

Setup: Create a disposable with N other disposables attached, arranged as a chain
Bench: Dispose above

name	ops/sec	time/op	margin	samples
Dsp.dispose(dsp) x 1	29M	26ns	±0.08%	38M
Dsp.dispose(dsp) x 10	7M	156ns	±0.24%	6M
Dsp.dispose(dsp) x 100	682K	2µs	±3.65%	634K
DisposableStack.dispose() x 1	13M	83ns	±0.07%	12M
DisposableStack.dispose() x 10	1M	783ns	±0.07%	1M
DisposableStack.dispose() x 100	110K	9µs	±0.09%	109K

bench-dispose-dsps-wide-reverse

Setup: Create a disposable with N other disposables attached
Bench: Dispose above in reverse order, one by one

name	ops/sec	time/op	margin	samples
Dsp.dispose(dsp) x 1	29M	26ns	±0.08%	38M
Dsp.dispose(dsp) x 10	7M	155ns	±1.19%	6M
Dsp.dispose(dsp) x 100	767K	1µs	±0.10%	756K
DisposableStack.dispose() x 1	20M	55ns	±0.08%	18M
DisposableStack.dispose() x 10	3M	370ns	±0.05%	3M
DisposableStack.dispose() x 100	294K	3µs	±0.05%	293K

bench-dispose-dsps-deep-reverse

Setup: Create a disposable with N other disposables attached, arranged as a chain
Bench: Dispose above in reverse order, one by one

name	ops/sec	time/op	margin	samples
Dsp.dispose(dsp) x 1	24M	40ns	±0.04%	25M
Dsp.dispose(dsp) x 10	5M	223ns	±0.06%	4M
Dsp.dispose(dsp) x 100	471K	2µs	±2.48%	462K
DisposableStack.dispose() x 1	11M	93ns	±0.31%	11M
DisposableStack.dispose() x 10	1M	841ns	±0.05%	1M
DisposableStack.dispose() x 100	103K	10µs	±0.06%	103K

bench-link-cbs

Setup: Create a disposable
Bench: Attach N callbacks to it

name	ops/sec	time/op	margin	samples
Dsp.add(dsp, callback) x 1	34M	22ns	±0.06%	45M
Dsp.add(dsp, callback) x 100	2M	768ns	±6.35%	1M
Dsp.add(dsp, callback) x 1000	158K	7µs	±1.56%	137K
DisposableStack.adopt(undefined, callback) x 1	24M	43ns	±0.28%	23M
DisposableStack.adopt(undefined, callback) x 100	496K	2µs	±6.78%	451K
DisposableStack.adopt(undefined, callback) x 1000	46K	23µs	±0.75%	44K

bench-link-dsps

Setup: Create a disposable
Bench: Attach N other disposables to it

name	ops/sec	time/op	margin	samples
Dsp.add(dsp, Dsp.create()) x 1	34M	22ns	±0.07%	45M
Dsp.add(dsp, Dsp.create()) x 100	2M	762ns	±7.31%	1M
Dsp.add(dsp, Dsp.create()) x 1000	162K	7µs	±2.75%	137K
DisposableStack.use(new DisposableStack()) x 1	11M	91ns	±0.06%	11M
DisposableStack.use(new DisposableStack()) x 100	151K	7µs	±6.90%	142K
DisposableStack.use(new DisposableStack()) x 1000	15K	68µs	±0.61%	15K

bench-create

Bench: Creates N empty disposables

name	ops/sec	time/op	margin	samples
Dsp.create() x 1	36M	21ns	±0.08%	48M
Dsp.create() x 100	24M	41ns	±0.85%	24M
Dsp.create() x 1000	3M	340ns	±0.07%	3M
new DisposableStack() x 1	22M	51ns	±5.95%	20M
new DisposableStack() x 100	359K	3µs	±8.03%	332K
new DisposableStack() x 1000	36K	28µs	±0.40%	36K

memory

Heapsize for 1M instances:

Dsp.create(): 247.57 MB
new DisposableStack(): 299.39 MB

Tree-shaking

Installation

npm install -D @monstermann/unplugin-dsp

pnpm -D add @monstermann/unplugin-dsp

yarn -D add @monstermann/unplugin-dsp

bun -D add @monstermann/unplugin-dsp

Usage

// vite.config.ts
import dsp from "@monstermann/unplugin-dsp/vite";

export default defineConfig({
    plugins: [dsp()],
});

// rollup.config.js
import dsp from "@monstermann/unplugin-dsp/rollup";

export default {
    plugins: [dsp()],
};

// rolldown.config.js
import dsp from "@monstermann/unplugin-dsp/rolldown";

export default {
    plugins: [dsp()],
};

// webpack.config.js
const dsp = require("@monstermann/unplugin-dsp/webpack");

module.exports = {
    plugins: [dsp()],
};

// rspack.config.js
const dsp = require("@monstermann/unplugin-dsp/rspack");

module.exports = {
    plugins: [dsp()],
};

// esbuild.config.js
import { build } from "esbuild";
import dsp from "@monstermann/unplugin-dsp/esbuild";

build({
    plugins: [dsp()],
});

Dsp

add

function Dsp.add(disposer: Dsp, value: (() => void) | Dsp): DspLink | undefined;

Takes a Dsp instance and attaches a callback or another Dsp.

Returns a data-structure that can be passed to unlink for fast O(1) removals.

Returns undefined if:

The target Dsp has already been disposed
The provided Dsp has already been disposed
The target Dsp is equal to the provided Dsp

If the target Dsp is already disposed, the provided value will be immediately disposed if possible.

Example

import { Dsp } from "@monstermann/dsp";

const dspA = Dsp.create();
const dspB = Dsp.create();

Dsp.add(dspA, () => console.log(1));
Dsp.add(dspB, () => console.log(2));
Dsp.add(dspA, dspB);

Dsp.dispose(dspA); // Prints: 2, 1

Dsp.add(dspA, () => console.log(3)); // Prints: 3
Dsp.add(dspB, () => console.log(4)); // Prints: 4

create

function Dsp.create(): Dsp;

Creates a new Dsp instance.

Example

import { Dsp } from "@monstermann/dsp";

const dsp = Dsp.create();

Dispose

function Dsp.dispose(disposer: Dsp): void;

Takes a Dsp instance and disposes it, walking through all added values in reverse order (LIFO).

Disposed Dsps will dereference themselves from other Dsps.

Every added value is wrapped with a try/catch and errors are accumulated in an AggregateError.

Example

import { Dsp } from "@monstermann/dsp";

const dspA = Dsp.create();
Dsp.add(dspA, () => console.log(1));
Dsp.add(dspA, () => console.log(2));

Dsp.dispose(dspA); // Prints: 2, 1

import { Dsp } from "@monstermann/dsp";

const dspA = Dsp.create();
const dspB = Dsp.create();

Dsp.add(dspA, () => console.log(1));
Dsp.add(dspA, () => console.log(2));
Dsp.add(dspB, () => console.log(3));
Dsp.add(dspB, () => console.log(4));
Dsp.add(dspA, dspB);

Dsp.dispose(dspA); // Prints: 4, 3, 2, 1

import { Dsp } from "@monstermann/dsp";

const dspA = Dsp.create();
const dspB = Dsp.create();

Dsp.add(dspA, () => console.log(1));
Dsp.add(dspA, () => console.log(2));
Dsp.add(dspB, () => console.log(3));
Dsp.add(dspB, () => console.log(4));
Dsp.add(dspA, dspB);

Dsp.dispose(dspB); // Prints: 4, 3
Dsp.dispose(dspA); // Prints: 2, 1

import { Dsp } from "@monstermann/dsp";

const dspA = Dsp.create();

Dsp.add(dspA, () => console.log(1));
Dsp.add(dspA, () => console.log(2));
Dsp.add(dspA, () => {
    throw new Error();
});

Dsp.dispose(dspA); // Prints: 2, 1, then rethrows above error

import { Dsp } from "@monstermann/dsp";

const dspA = Dsp.create();

Dsp.add(dspA, () => console.log(1));
Dsp.add(dspA, () => console.log(2));
Dsp.add(dspA, () => {
    throw new Error();
});
Dsp.add(dspA, () => {
    throw new Error();
});

Dsp.dispose(dspA); // Prints: 2, 1, then throws AggregateError

find

function Dsp.find(disposer: Dsp, value: (() => void) | Dsp): DspLink | undefined;

O(n)

Takes a Dsp instance and finds the last occurrence of value, the result can be passed to unlink to remove it.

Example

import { Dsp } from "@monstermann/dsp";

const dsp = Dsp.create();

const cb1 = () => {};
const cb2 = () => {};

Dsp.add(dsp, cb1);

Dsp.includes(dsp, cb1); // true
Dsp.includes(dsp, cb2); // false

const l1 = Dsp.find(dsp, cb1); // link
const l2 = Dsp.find(dsp, cb2); // undefined

Dsp.unlink(l1);
Dsp.unlink(l2);

Dsp.includes(dsp, cb1); // false
Dsp.includes(dsp, cb2); // false

dspIncludes

function Dsp.includes(disposer: Dsp, value: (() => void) | Dsp): boolean;

O(n)

Returns a boolean indicating whether the provided Dsp instance includes value.

By default add does not check for duplicates, you can use this or find if you need to make sure there are none.

Example

import { Dsp } from "@monstermann/dsp";

const dsp = Dsp.create();
const cb = () => {};

Dsp.includes(dsp, cb); // false
const link = Dsp.add(dsp, cb);
Dsp.includes(dsp, cb); // true
Dsp.unlink(dsp, link);
Dsp.includes(dsp, cb); // false

isDisposed

function Dsp.isDisposed(disposer: Dsp): boolean;

Returns a boolean indicating whether the provided Dsp instance has been disposed.

Example

import { Dsp } from "@monstermann/dsp";

const dsp = Dsp.create();
Dsp.isDisposed(dsp); // false
Dsp.dispose(dsp);
Dsp.isDisposed(dsp); // true

isDsp

function Dsp.isDsp(value: unknown): value is Dsp;

Checks whether the provided value is a Dsp instance.

Example

import { Dsp } from "@monstermann/dsp";

const dsp = Dsp.create();
Dsp.isDsp(dsp); // true

remove

function Dsp.remove(disposer: Dsp, value: (() => void) | Dsp): void;

O(n)

Takes a Dsp instance and removes the last occurrence of value from it.

If you can, use unlink as it is O(1).

Example

import { Dsp } from "@monstermann/dsp";

const dsp = Dsp.create();
const cb = () => {};
const link = Dsp.add(dsp, cb);
Dsp.includes(dsp, cb); // true
Dsp.remove(dsp, cb);
Dsp.includes(dsp, cb); // false

unlink

function Dsp.unlink(link: DspLink | undefined): void;

O(1)

Takes a value constructed by add and destroys all references.

Example

import { Dsp } from "@monstermann/dsp";

const cb = () => {};

const dsp = Dsp.create();
const link = Dsp.add(dsp, cb);

Dsp.includes(dsp, cb); // true
Dsp.unlink(link);
Dsp.includes(dsp, cb); // false

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.github/workflows		.github/workflows
benchmarks		benchmarks
docs		docs
packages		packages
playground		playground
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
barrels.config.ts		barrels.config.ts
bun.lock		bun.lock
eslint.config.js		eslint.config.js
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

MichaelOstermann/dsp

Folders and files

Latest commit

History

Repository files navigation

dsp

Example

Installation

Benchmarks

bench-dispose-cbs

bench-dispose-dsps-wide

bench-dispose-dsps-deep

bench-dispose-dsps-wide-reverse

bench-dispose-dsps-deep-reverse

bench-link-cbs

bench-link-dsps

bench-create

memory

Tree-shaking

Installation

Usage

Dsp

add

Example

create

Example

Dispose

Example

find

Example

dspIncludes

Example

isDisposed

Example

isDsp

Example

remove

Example

unlink

Example

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Contributors 2

Uh oh!

Languages

Packages