@vielzeug/flux 1.0.3

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+/** Cleanup / unsubscribe function returned by `subscribe()`. */
+export type Unsubscribe = () => void;
+/**
+ * Minimal time-scheduling abstraction for operators that depend on timers.
+ * Inject a custom implementation in tests to control time without relying on
+ * global fake-timer mechanisms (`vi.useFakeTimers()`).
+ *
+ * @example
+ * const testScheduler: Scheduler = {
+ *   delay(fn, ms) { ... },
+ *   repeat(fn, ms) { ... },
+ * };
+ * debounce(300, testScheduler);
+ */
+export type Scheduler = {
+    /** Schedule `fn` to run once after `ms` milliseconds. Returns a cancel function. */
+    delay(fn: () => void, ms: number): () => void;
+    /** Schedule `fn` to run repeatedly every `ms` milliseconds. Returns a cancel function. */
+    repeat(fn: () => void, ms: number): () => void;
+};
+/**
+ * Observer passed to a producer or `subscribe()`.
+ * `error` and `complete` are optional — omit them to ignore those signals.
+ */
+export type Observer<T> = {
+    complete?: () => void;
+    error?: (err: unknown) => void;
+    next: (value: T) => void;
+};
+/**
+ * Producer function passed to `flux()`.
+ * Called once per `subscribe()` invocation (cold by default).
+ * Return a cleanup function (or nothing) — it is called on unsubscribe.
+ */
+export type Producer<T> = (observer: Observer<T>) => Unsubscribe | void;
+/**
+ * A pipeable operator: a function that takes a source `Flux<A>` and returns a new `Flux<B>`.
+ *
+ * @example
+ * const double: Operator<number, number> = (source) =>
+ *   source.pipe(map((n) => n * 2));
+ */
+export type Operator<A = unknown, B = unknown> = (source: Flux<A>) => Flux<B>;
+/**
+ * The core stream primitive. Lazy (cold) by default — each `subscribe()` invocation
+ * starts its own producer. Use `.pipe(share())` to multicast to many subscribers.
+ */
+export interface Flux<T> {
+    /** `true` after `dispose()` is called. New subscriptions receive an immediate `complete` notification. */
+    readonly disposed: boolean;
+    /** AbortSignal that aborts when `dispose()` is called. */
+    readonly disposalSignal: AbortSignal;
+    /** Permanently terminates this stream. All active subscribers receive a `complete` notification. */
+    dispose(): void;
+    /**
+     * Apply one or more operators in sequence. Each operator receives the output
+     * of the previous one as its input, forming a pipeline.
+     */
+    pipe<B>(op1: Operator<T, B>): Flux<B>;
+    pipe<B, C>(op1: Operator<T, B>, op2: Operator<B, C>): Flux<C>;
+    pipe<B, C, D>(op1: Operator<T, B>, op2: Operator<B, C>, op3: Operator<C, D>): Flux<D>;
+    pipe<B, C, D, E>(op1: Operator<T, B>, op2: Operator<B, C>, op3: Operator<C, D>, op4: Operator<D, E>): Flux<E>;
+    pipe(...operators: Operator[]): Flux<unknown>;
+    /**
+     * Subscribe to values emitted by this stream.
+     * Accepts either a full `Observer<T>` object or a plain `next` function.
+     * Returns an unsubscribe function — call it to stop receiving values.
+     * Pass an optional `AbortSignal` to unsubscribe automatically when the signal aborts.
+     * If the stream is already disposed, the observer receives an immediate `complete` notification.
+     */
+    subscribe(observerOrNext: Observer<T> | ((value: T) => void), signal?: AbortSignal): Unsubscribe;
+    /**
+     * Consume the stream as an async iterator.
+     * Buffers incoming values until consumed.
+     * Calling `return()` on the iterator (or exiting a `for await` loop early) unsubscribes from the source.
+     *
+     * @example
+     * for await (const value of source$) {
+     *   console.log(value);
+     * }
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    /** ES2026 `using` compatible disposal. Delegates to `dispose()`. */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@vielzeug/flux",
+  "version": "1.0.3",
+  "description": "Composable stream primitive with hot/cold semantics, backpressure, and ecosystem adapters",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build:bundle": "vite build --config vite.bundle.config.ts",
+    "build:types": "tsc -p tsconfig.declarations.json",
+    "fix": "eslint --fix src",
+    "lint": "eslint src",
+    "prepublishOnly": "pnpm run build",
+    "test": "vitest"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@vielzeug/ripple": "workspace:*"
+  },
+  "peerDependencies": {
+    "@vielzeug/courier": "workspace:*",
+    "@vielzeug/herald": "workspace:*",
+    "@vielzeug/pulse": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@vielzeug/courier": {
+      "optional": true
+    },
+    "@vielzeug/herald": {
+      "optional": true
+    },
+    "@vielzeug/pulse": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "@vielzeug/courier": "workspace:*",
+    "@vielzeug/herald": "workspace:*",
+    "@vielzeug/pulse": "workspace:*",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  }
+}