@qorejs/qore 0.7.0 → 0.7.2

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

@@ -0,0 +1,73 @@
+import type { ComputedSignal, Signal } from './signal.js';
+export type MaybePromise<T> = T | Promise<T>;
+export type ResponseStatus = 'idle' | 'pending' | 'streaming' | 'completed' | 'error' | 'aborted';
+export type GlobalAbortSignal = typeof globalThis extends {
+    AbortSignal: infer T;
+} ? T extends {
+    prototype: infer P;
+} ? P : unknown : {
+    aborted: boolean;
+    reason?: unknown;
+};
+export interface ResponseSnapshot<TChunk = unknown, TValue = unknown> {
+    status: ResponseStatus;
+    value: TValue;
+    error: Error | null;
+    chunks: TChunk[];
+    startedAt: number | null;
+    finishedAt: number | null;
+    chunkCount: number;
+}
+export interface ResponseRunOptions<TValue> {
+    resetValue?: boolean;
+    nextSeed?: TValue;
+}
+export type SourceLike<T> = T | Iterable<T> | AsyncIterable<T> | null | undefined;
+export interface ResponseReactiveState<TChunk, TValue> {
+    status: Signal<ResponseStatus>;
+    value: Signal<TValue>;
+    error: Signal<Error | null>;
+    chunks: Signal<TChunk[]>;
+    startedAt: Signal<number | null>;
+    finishedAt: Signal<number | null>;
+    pending: ComputedSignal<boolean>;
+    streaming: ComputedSignal<boolean>;
+    completed: ComputedSignal<boolean>;
+    failed: ComputedSignal<boolean>;
+    aborted: ComputedSignal<boolean>;
+    chunkCount: ComputedSignal<number>;
+}
+export interface ResponseConsumeContext<TChunk, TValue> {
+    signal: GlobalAbortSignal;
+    response: ResponseState<TChunk, TValue>;
+}
+export interface ResponseExecutorContext<TChunk, TValue> {
+    readonly signal: GlobalAbortSignal;
+    response: ResponseState<TChunk, TValue>;
+    push(chunk: TChunk): TValue;
+    complete(): TValue;
+    fail(reason?: unknown): Error | TValue;
+    abort(reason?: unknown): TValue;
+}
+export type ResponseSourceFactory<TChunk, TValue> = (context: ResponseConsumeContext<TChunk, TValue>) => MaybePromise<SourceLike<TChunk>>;
+export type ResponseSource<TChunk, TValue> = SourceLike<TChunk> | ResponseSourceFactory<TChunk, TValue>;
+export interface CreateResponseOptions<TChunk, TValue> {
+    seed: TValue;
+    reduce: (currentValue: TValue, chunk: TChunk, index: number) => TValue;
+}
+export interface ResponseState<TChunk = unknown, TValue = unknown> extends ResponseReactiveState<TChunk, TValue> {
+    reset(nextSeed?: TValue): TValue;
+    push(chunk: TChunk): TValue;
+    complete(): TValue;
+    fail(reason?: unknown): Error | TValue;
+    abort(reason?: unknown): TValue;
+    run(executor: (context: ResponseExecutorContext<TChunk, TValue>) => MaybePromise<unknown>, options?: ResponseRunOptions<TValue>): Promise<TValue>;
+    consume(source: ResponseSource<TChunk, TValue>, options?: ResponseRunOptions<TValue>): Promise<TValue>;
+    snapshot(): ResponseSnapshot<TChunk, TValue>;
+}
+export interface ResponseFactory {
+    create<TChunk, TValue>(options: CreateResponseOptions<TChunk, TValue>): ResponseState<TChunk, TValue>;
+    text<TChunk = string>(seed?: string): ResponseState<TChunk, string>;
+    list<TChunk>(seed?: TChunk[]): ResponseState<TChunk, TChunk[]>;
+    latest<TChunk>(seed?: TChunk | null): ResponseState<TChunk, TChunk | null>;
+}

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

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

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

@@ -0,0 +1,4 @@
+import type { ResponseFactory } from './response-types.js';
+export { createResponse } from './response-runtime.js';
+export type { CreateResponseOptions, GlobalAbortSignal, MaybePromise, ResponseConsumeContext, ResponseExecutorContext, ResponseFactory, ResponseReactiveState, ResponseRunOptions, ResponseSnapshot, ResponseSource, ResponseSourceFactory, ResponseState, ResponseStatus, SourceLike } from './response-types.js';
+export declare const response: ResponseFactory;

package/dist/src/core/response.js

@@ -0,0 +1,26 @@
+import { createResponse } from './response-runtime.js';
+// Ship a few common reducers as convenience constructors on top of createResponse.
+export { createResponse } from './response-runtime.js';
+export const response = {
+    create(options) {
+        return createResponse(options);
+    },
+    text(seed = '') {
+        return createResponse({
+            seed,
+            reduce: (currentValue, chunk) => currentValue + String(chunk)
+        });
+    },
+    list(seed = []) {
+        return createResponse({
+            seed,
+            reduce: (currentValue, chunk) => [...currentValue, chunk]
+        });
+    },
+    latest(seed = null) {
+        return createResponse({
+            seed,
+            reduce: (_, chunk) => chunk
+        });
+    }
+};

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

@@ -0,0 +1,10 @@
+import type { ReactiveObserver } from './signal-types.js';
+export declare const READ: unique symbol;
+export declare function getActiveObserver(): ReactiveObserver | null;
+export declare function setActiveObserver(observer: ReactiveObserver | null): void;
+export declare function withActiveObserver<T>(observer: ReactiveObserver | null, fn: () => T): T;
+export declare function cleanupObserver(observer: ReactiveObserver): void;
+export declare function scheduleObserver(observer: ReactiveObserver): void;
+export declare function removePendingObserver(observer: ReactiveObserver): void;
+export declare function batch<T>(fn: () => T): T;
+export declare function untrack<T>(fn: () => T): T;

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>;