@qorejs/qore 0.7.1 → 0.7.3

package/dist/src/core/signal-context.js

@@ -0,0 +1,69 @@
+// Use a sentinel so signals can still store undefined as a real value.
+export const READ = Symbol('qore.signal.read');
+let activeObserver = null;
+let batchDepth = 0;
+const pendingObservers = new Set();
+export function getActiveObserver() {
+    return activeObserver;
+}
+export function setActiveObserver(observer) {
+    activeObserver = observer;
+}
+export function withActiveObserver(observer, fn) {
+    const previousObserver = activeObserver;
+    activeObserver = observer;
+    try {
+        return fn();
+    }
+    finally {
+        activeObserver = previousObserver;
+    }
+}
+// Remove this observer from every dependency it tracked during the last run.
+export function cleanupObserver(observer) {
+    for (const dep of observer.deps) {
+        dep.subscribers.delete(observer);
+    }
+    observer.deps.clear();
+}
+// Queue observer work during batching, otherwise notify immediately.
+export function scheduleObserver(observer) {
+    if (!observer.active) {
+        return;
+    }
+    if (batchDepth > 0) {
+        pendingObservers.add(observer);
+        return;
+    }
+    observer.schedule();
+}
+export function removePendingObserver(observer) {
+    pendingObservers.delete(observer);
+}
+// Flush batched observer work in FIFO-like waves until the queue is empty.
+function flushObservers() {
+    while (pendingObservers.size > 0) {
+        const queue = Array.from(pendingObservers);
+        pendingObservers.clear();
+        for (const observer of queue) {
+            observer.schedule();
+        }
+    }
+}
+// Batch synchronous updates so dependent observers only re-run once afterward.
+export function batch(fn) {
+    batchDepth += 1;
+    try {
+        return fn();
+    }
+    finally {
+        batchDepth -= 1;
+        if (batchDepth === 0) {
+            flushObservers();
+        }
+    }
+}
+// Read signals without subscribing the current observer to them.
+export function untrack(fn) {
+    return withActiveObserver(null, fn);
+}

package/dist/src/core/signal-nodes.d.ts

@@ -0,0 +1,45 @@
+import type { Cleanup, EffectCallback, EffectOptions, ObserverDependency, ReactiveObserver, SignalListener, SubscribeOptions } from './signal-types.js';
+export declare class SignalNode<T> implements ObserverDependency {
+    value: T;
+    subscribers: Set<ReactiveObserver>;
+    listeners: Set<SignalListener<T>>;
+    constructor(initialValue: T);
+    get(): T;
+    peek(): T;
+    set(nextValue: T): T;
+    update(updater: (currentValue: T) => T): T;
+    subscribe(listener: SignalListener<T>, options?: SubscribeOptions): Cleanup;
+    emit(): void;
+}
+export declare class ComputedNode<T> implements ObserverDependency, ReactiveObserver {
+    getter: () => T;
+    subscribers: Set<ReactiveObserver>;
+    listeners: Set<SignalListener<T>>;
+    deps: Set<ObserverDependency>;
+    active: boolean;
+    initialized: boolean;
+    value: T;
+    constructor(getter: () => T);
+    get(): T;
+    peek(): T;
+    schedule(): void;
+    notify(): void;
+    subscribe(listener: SignalListener<T>, options?: SubscribeOptions): Cleanup;
+    recompute(): void;
+    stop(): void;
+}
+export declare class EffectNode implements ReactiveObserver {
+    fn: EffectCallback;
+    scheduler: EffectOptions['scheduler'];
+    deps: Set<ObserverDependency>;
+    active: boolean;
+    scheduled: boolean;
+    running: boolean;
+    needsRun: boolean;
+    cleanup: Cleanup | null;
+    constructor(fn: EffectCallback, options?: EffectOptions);
+    schedule(): void;
+    notify(): void;
+    run(): void;
+    stop(): void;
+}

package/dist/src/core/signal-nodes.js

@@ -0,0 +1,197 @@
+import { cleanupObserver, getActiveObserver, removePendingObserver, scheduleObserver, withActiveObserver } from './signal-context.js';
+import { scheduleEffectRun } from './signal-scheduler.js';
+// A mutable signal node stores a value and fan-outs updates to listeners and observers.
+export class SignalNode {
+    value;
+    subscribers = new Set();
+    listeners = new Set();
+    constructor(initialValue) {
+        this.value = initialValue;
+    }
+    get() {
+        const activeObserver = getActiveObserver();
+        if (activeObserver) {
+            this.subscribers.add(activeObserver);
+            activeObserver.deps.add(this);
+        }
+        return this.value;
+    }
+    peek() {
+        return this.value;
+    }
+    set(nextValue) {
+        if (Object.is(this.value, nextValue)) {
+            return this.value;
+        }
+        this.value = nextValue;
+        this.emit();
+        return this.value;
+    }
+    update(updater) {
+        return this.set(updater(this.value));
+    }
+    subscribe(listener, options = {}) {
+        const { immediate = true } = options;
+        this.listeners.add(listener);
+        if (immediate) {
+            listener(this.value);
+        }
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    // Snapshot listeners first so resubscription during notification cannot loop forever.
+    emit() {
+        for (const listener of Array.from(this.listeners)) {
+            listener(this.value);
+        }
+        for (const observer of Array.from(this.subscribers)) {
+            scheduleObserver(observer);
+        }
+    }
+}
+// A computed node re-runs its getter whenever one of its dependencies changes.
+export class ComputedNode {
+    getter;
+    subscribers = new Set();
+    listeners = new Set();
+    deps = new Set();
+    active = true;
+    initialized = false;
+    value;
+    constructor(getter) {
+        this.getter = getter;
+        this.recompute();
+    }
+    get() {
+        const activeObserver = getActiveObserver();
+        if (activeObserver) {
+            this.subscribers.add(activeObserver);
+            activeObserver.deps.add(this);
+        }
+        return this.value;
+    }
+    peek() {
+        return this.value;
+    }
+    schedule() {
+        this.notify();
+    }
+    notify() {
+        this.recompute();
+    }
+    subscribe(listener, options = {}) {
+        const { immediate = true } = options;
+        this.listeners.add(listener);
+        if (immediate) {
+            listener(this.value);
+        }
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    // Recompute under dependency tracking and notify downstream observers only on change.
+    recompute() {
+        if (!this.active) {
+            return;
+        }
+        const previousValue = this.value;
+        cleanupObserver(this);
+        withActiveObserver(this, () => {
+            const nextValue = this.getter();
+            const changed = !this.initialized || !Object.is(previousValue, nextValue);
+            this.value = nextValue;
+            this.initialized = true;
+            if (!changed) {
+                return;
+            }
+            for (const listener of Array.from(this.listeners)) {
+                listener(this.value);
+            }
+            for (const observer of Array.from(this.subscribers)) {
+                scheduleObserver(observer);
+            }
+        });
+    }
+    stop() {
+        if (!this.active) {
+            return;
+        }
+        this.active = false;
+        cleanupObserver(this);
+        removePendingObserver(this);
+        this.subscribers.clear();
+        this.listeners.clear();
+    }
+}
+// Effects are observers with optional cleanup that re-run when dependencies change.
+export class EffectNode {
+    fn;
+    scheduler;
+    deps = new Set();
+    active = true;
+    scheduled = false;
+    running = false;
+    needsRun = false;
+    cleanup = null;
+    constructor(fn, options = {}) {
+        this.fn = fn;
+        this.scheduler = options.scheduler ?? 'sync';
+        this.run();
+    }
+    schedule() {
+        if (!this.active) {
+            return;
+        }
+        if (this.running) {
+            this.needsRun = true;
+            return;
+        }
+        if (this.scheduled) {
+            return;
+        }
+        this.scheduled = true;
+        scheduleEffectRun(this.scheduler, () => {
+            this.scheduled = false;
+            this.run();
+        });
+    }
+    notify() {
+        this.run();
+    }
+    // Execute the effect under tracking and remember any returned cleanup callback.
+    run() {
+        if (!this.active) {
+            return;
+        }
+        this.running = true;
+        this.needsRun = false;
+        cleanupObserver(this);
+        if (typeof this.cleanup === 'function') {
+            this.cleanup();
+            this.cleanup = null;
+        }
+        withActiveObserver(this, () => {
+            const maybeCleanup = this.fn();
+            this.cleanup = typeof maybeCleanup === 'function' ? maybeCleanup : null;
+        });
+        this.running = false;
+        if (this.needsRun && this.active) {
+            this.schedule();
+        }
+    }
+    stop() {
+        if (!this.active) {
+            return;
+        }
+        this.active = false;
+        this.scheduled = false;
+        this.needsRun = false;
+        cleanupObserver(this);
+        removePendingObserver(this);
+        if (typeof this.cleanup === 'function') {
+            this.cleanup();
+            this.cleanup = null;
+        }
+    }
+}

package/dist/src/core/signal-scheduler.d.ts

@@ -0,0 +1,2 @@
+import type { EffectScheduler } from './signal-types.js';
+export declare function scheduleEffectRun(scheduler: EffectScheduler | undefined, run: () => void): void;

package/dist/src/core/signal-scheduler.js

@@ -0,0 +1,19 @@
+export function scheduleEffectRun(scheduler, run) {
+    if (typeof scheduler === 'function') {
+        scheduler(run);
+        return;
+    }
+    if (scheduler === 'microtask') {
+        queueMicrotask(run);
+        return;
+    }
+    if (scheduler === 'raf') {
+        if (typeof requestAnimationFrame === 'function') {
+            requestAnimationFrame(() => run());
+            return;
+        }
+        queueMicrotask(run);
+        return;
+    }
+    run();
+}

package/dist/src/core/signal-types.d.ts

@@ -0,0 +1,19 @@
+export interface SubscribeOptions {
+    immediate?: boolean;
+}
+export type SignalListener<T> = (value: T) => void;
+export type Cleanup = () => void;
+export type EffectCallback = () => void | Cleanup;
+export type EffectScheduler = 'sync' | 'microtask' | 'raf' | ((run: () => void) => void);
+export interface EffectOptions {
+    scheduler?: EffectScheduler;
+}
+export interface ObserverDependency {
+    subscribers: Set<ReactiveObserver>;
+}
+export interface ReactiveObserver {
+    deps: Set<ObserverDependency>;
+    active: boolean;
+    schedule(): void;
+    notify(): void;
+}

package/dist/src/core/signal-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/signal.d.ts

@@ -0,0 +1,19 @@
+import type { Cleanup, EffectCallback, EffectOptions, SubscribeOptions } from './signal-types.js';
+export interface ReadonlySignal<T> {
+    (): T;
+    peek(): T;
+    subscribe(listener: (value: T) => void, options?: SubscribeOptions): Cleanup;
+}
+export interface Signal<T> extends ReadonlySignal<T> {
+    (nextValue: T): T;
+    set(nextValue: T): T;
+    update(updater: (currentValue: T) => T): T;
+}
+export interface ComputedSignal<T> extends ReadonlySignal<T> {
+    stop(): void;
+}
+export declare function signal<T>(initialValue: T): Signal<T>;
+export declare function computed<T>(getter: () => T): ComputedSignal<T>;
+export declare function effect(fn: EffectCallback, options?: EffectOptions): Cleanup;
+export { batch, untrack } from './signal-context.js';
+export declare function isSignal<T = unknown>(value: unknown): value is ReadonlySignal<T>;

package/dist/src/core/signal.js

@@ -0,0 +1,41 @@
+import { batch, READ, untrack } from './signal-context.js';
+import { ComputedNode, EffectNode, SignalNode } from './signal-nodes.js';
+// Create a mutable signal function with helper methods attached to it.
+export function signal(initialValue) {
+    const node = new SignalNode(initialValue);
+    const readWriteSignal = ((nextValue = READ) => {
+        if (nextValue === READ) {
+            return node.get();
+        }
+        return node.set(nextValue);
+    });
+    readWriteSignal.set = (nextValue) => node.set(nextValue);
+    readWriteSignal.update = (updater) => node.update(updater);
+    readWriteSignal.peek = () => node.peek();
+    readWriteSignal.subscribe = (listener, options) => node.subscribe(listener, options);
+    return readWriteSignal;
+}
+// Create a read-only computed signal backed by dependency tracking.
+export function computed(getter) {
+    const node = new ComputedNode(getter);
+    const readOnlySignal = ((nextValue = READ) => {
+        if (nextValue !== READ) {
+            throw new Error('Computed signals are read-only');
+        }
+        return node.get();
+    });
+    readOnlySignal.peek = () => node.peek();
+    readOnlySignal.subscribe = (listener, options) => node.subscribe(listener, options);
+    readOnlySignal.stop = () => node.stop();
+    return readOnlySignal;
+}
+// Run a reactive effect and return a disposer for it.
+export function effect(fn, options = {}) {
+    const node = new EffectNode(fn, options);
+    return () => node.stop();
+}
+export { batch, untrack } from './signal-context.js';
+// Detect Qore signal-like values by their callable shape plus peek helper.
+export function isSignal(value) {
+    return typeof value === 'function' && typeof value.peek === 'function';
+}

package/dist/src/core/stream-backpressure.d.ts

@@ -0,0 +1,3 @@
+import type { BackpressureOptions, Deferred, NormalizedBackpressure } from './stream-types.js';
+export declare function normalizeBackpressure(backpressure: number | BackpressureOptions | null | undefined): NormalizedBackpressure;
+export declare function createDeferred<T>(): Deferred<T>;

package/dist/src/core/stream-backpressure.js

@@ -0,0 +1,36 @@
+// Normalize backpressure into one consistent shape the runtime can enforce.
+export function normalizeBackpressure(backpressure) {
+    if (backpressure == null) {
+        return {
+            interval: 0,
+            buffer: Infinity,
+            overflow: 'wait'
+        };
+    }
+    const options = typeof backpressure === 'number'
+        ? { interval: backpressure }
+        : backpressure;
+    const interval = options.interval ?? 0;
+    const buffer = options.buffer ?? Infinity;
+    const overflow = options.overflow ?? 'wait';
+    if (!Number.isFinite(interval) || interval < 0) {
+        throw new TypeError('Qore stream backpressure.interval must be a non-negative finite number');
+    }
+    if (buffer !== Infinity && (!Number.isInteger(buffer) || buffer < 1)) {
+        throw new TypeError('Qore stream backpressure.buffer must be a positive integer or Infinity');
+    }
+    if (!['wait', 'drop-oldest', 'drop-newest', 'error'].includes(overflow)) {
+        throw new TypeError('Qore stream backpressure.overflow must be one of "wait", "drop-oldest", "drop-newest", or "error"');
+    }
+    return { interval, buffer, overflow };
+}
+// Build a deferred promise so queue operations can wait for capacity or completion.
+export function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((nextResolve, nextReject) => {
+        resolve = nextResolve;
+        reject = nextReject;
+    });
+    return { promise, resolve, reject };
+}

package/dist/src/core/stream-buffer.d.ts

@@ -0,0 +1,17 @@
+import type { NormalizedBackpressure } from './stream-types.js';
+export interface StreamBuffer<TChunk, TValue> {
+    push(chunk: TChunk): Promise<TValue>;
+    flush(result?: TValue): TValue;
+    flushScheduled(): Promise<void>;
+}
+export declare function createStreamBuffer<TChunk, TValue>({ enqueueChunk, fail, isTerminated, pressure, readCurrent, recordDrop, signal, updateBuffered, writeChunk }: {
+    enqueueChunk(chunk: TChunk): void;
+    fail(error: unknown): Error | TValue;
+    isTerminated(): boolean;
+    pressure: NormalizedBackpressure;
+    readCurrent(): TValue;
+    recordDrop(): void;
+    signal: AbortSignal;
+    updateBuffered(count: number): void;
+    writeChunk(chunk: TChunk): TValue;
+}): StreamBuffer<TChunk, TValue>;

package/dist/src/core/stream-buffer.js

@@ -0,0 +1,162 @@
+import { createDeferred } from './stream-backpressure.js';
+import { sleep } from '../shared/utils.js';
+export function createStreamBuffer({ enqueueChunk, fail, isTerminated, pressure, readCurrent, recordDrop, signal, updateBuffered, writeChunk }) {
+    const pendingWrites = [];
+    const spaceWaiters = [];
+    const scheduledPushes = new Set();
+    let scheduledPushError = null;
+    let drainPromise = null;
+    let lastPushAt = 0;
+    function releaseSpaceWaiters() {
+        if (pressure.buffer === Infinity) {
+            while (spaceWaiters.length > 0) {
+                spaceWaiters.shift()?.resolve(undefined);
+            }
+            return;
+        }
+        while (spaceWaiters.length > 0 && pendingWrites.length < pressure.buffer) {
+            spaceWaiters.shift()?.resolve(undefined);
+        }
+    }
+    function flush(result = readCurrent()) {
+        while (pendingWrites.length > 0) {
+            pendingWrites.shift()?.resolve(result);
+        }
+        updateBuffered(0);
+        releaseSpaceWaiters();
+        return result;
+    }
+    async function flushScheduled() {
+        while (scheduledPushes.size > 0) {
+            await Promise.allSettled(Array.from(scheduledPushes));
+        }
+        if (scheduledPushError !== null) {
+            throw scheduledPushError;
+        }
+        while (drainPromise) {
+            await drainPromise;
+        }
+        if (scheduledPushError !== null) {
+            throw scheduledPushError;
+        }
+    }
+    async function waitForNextWindow() {
+        if (pressure.interval <= 0 || lastPushAt === 0) {
+            return;
+        }
+        const remaining = pressure.interval - (Date.now() - lastPushAt);
+        if (remaining > 0) {
+            try {
+                await sleep(remaining, signal);
+            }
+            catch (error) {
+                if (!signal.aborted) {
+                    throw error;
+                }
+            }
+        }
+    }
+    function scheduleDrain() {
+        if (drainPromise || isTerminated()) {
+            return drainPromise;
+        }
+        drainPromise = (async () => {
+            try {
+                while (pendingWrites.length > 0 && !isTerminated() && !signal.aborted) {
+                    const entry = pendingWrites.shift();
+                    updateBuffered(pendingWrites.length);
+                    releaseSpaceWaiters();
+                    await waitForNextWindow();
+                    if (isTerminated() || signal.aborted) {
+                        entry.resolve(readCurrent());
+                        continue;
+                    }
+                    enqueueChunk(entry.chunk);
+                    const nextValue = writeChunk(entry.chunk);
+                    lastPushAt = Date.now();
+                    entry.resolve(nextValue);
+                }
+            }
+            finally {
+                drainPromise = null;
+                if (pendingWrites.length > 0 && !isTerminated() && !signal.aborted) {
+                    scheduleDrain();
+                }
+            }
+        })();
+        return drainPromise;
+    }
+    async function waitForBufferSpace() {
+        if (pressure.buffer === Infinity) {
+            return true;
+        }
+        while (!isTerminated() && !signal.aborted && pendingWrites.length >= pressure.buffer) {
+            const gate = createDeferred();
+            spaceWaiters.push(gate);
+            await gate.promise;
+        }
+        return !isTerminated() && !signal.aborted;
+    }
+    async function push(chunk) {
+        if (isTerminated() || signal.aborted) {
+            return readCurrent();
+        }
+        const writeTask = (async () => {
+            if (pressure.overflow === 'wait') {
+                const hasSpace = await waitForBufferSpace();
+                if (!hasSpace) {
+                    return readCurrent();
+                }
+            }
+            else if (pressure.buffer !== Infinity && pendingWrites.length >= pressure.buffer) {
+                if (pressure.overflow === 'drop-oldest' && pendingWrites.length > 0) {
+                    const droppedWrite = pendingWrites.shift();
+                    recordDrop();
+                    droppedWrite.resolve(readCurrent());
+                }
+                else if (pressure.overflow === 'drop-newest' || pressure.overflow === 'drop-oldest') {
+                    recordDrop();
+                    return readCurrent();
+                }
+                else if (pressure.overflow === 'error') {
+                    const overflowError = new Error('Qore stream backpressure buffer overflow');
+                    if (scheduledPushError === null) {
+                        scheduledPushError = overflowError;
+                    }
+                    fail(overflowError);
+                    return readCurrent();
+                }
+            }
+            if (isTerminated() || signal.aborted) {
+                return readCurrent();
+            }
+            const entry = createDeferred();
+            entry.chunk = chunk;
+            pendingWrites.push(entry);
+            updateBuffered(pendingWrites.length);
+            scheduleDrain();
+            return entry.promise;
+        })();
+        scheduledPushes.add(writeTask);
+        try {
+            return await writeTask;
+        }
+        catch (error) {
+            if (scheduledPushError === null) {
+                scheduledPushError = error;
+            }
+            if (!isTerminated() && !signal.aborted) {
+                fail(error);
+            }
+            return readCurrent();
+        }
+        finally {
+            scheduledPushes.delete(writeTask);
+        }
+    }
+    return {
+        flush,
+        flushScheduled,
+        push
+    };
+}

package/dist/src/core/stream-iterator.d.ts

@@ -0,0 +1,6 @@
+import type { AsyncQueue } from './stream-queue.js';
+import type { QoreStream } from './stream-types.js';
+export type IterableStream<TChunk, TValue> = QoreStream<TChunk, TValue> & {
+    [Symbol.asyncIterator](): AsyncIterableIterator<TChunk>;
+};
+export declare function attachStreamIterator<TChunk, TValue>(readable: IterableStream<TChunk, TValue>, queue: AsyncQueue<TChunk>, shouldAbortOnReturn: () => boolean, abort: (reason?: unknown) => TValue): void;

package/dist/src/core/stream-iterator.js

@@ -0,0 +1,14 @@
+export function attachStreamIterator(readable, queue, shouldAbortOnReturn, abort) {
+    readable[Symbol.asyncIterator] = async function* () {
+        try {
+            for await (const chunk of queue) {
+                yield chunk;
+            }
+        }
+        finally {
+            if (shouldAbortOnReturn()) {
+                abort('Stream consumer disposed');
+            }
+        }
+    };
+}

package/dist/src/core/stream-lifecycle.d.ts

@@ -0,0 +1,10 @@
+export interface StreamLifecycle<TValue> {
+    isTerminated(): boolean;
+    markTerminated(): boolean;
+    setCleanup(cleanup: () => TValue | void): void;
+    stop(finalizer: () => TValue, cleanup?: () => TValue | void): TValue;
+}
+export declare function createStreamLifecycle<TValue>({ closeQueue, readCurrent }: {
+    closeQueue(): void;
+    readCurrent(): TValue;
+}): StreamLifecycle<TValue>;