@qorejs/qore 0.7.3 → 1.0.0-rc.1

package/README.md

@@ -19,6 +19,7 @@ Quick links:
 - [npm package](https://www.npmjs.com/package/@qorejs/qore)
 - [latest release](https://github.com/qorejs/qore/releases/latest)
 - [GitHub Packages](https://github.com/qorejs/qore/packages)
+- [migration notes](./MIGRATION.md)
 - [landing page source](https://github.com/qorejs/qore/blob/main/index.html)
 - [streaming demo source](https://github.com/qorejs/qore/blob/main/examples/streaming-response.html)
 - [benchmark page](https://github.com/qorejs/qore/blob/main/examples/benchmark.html)
@@ -44,6 +45,15 @@ npm i @qorejs/qore
 
 GitHub Packages installs require an authenticated session against `https://npm.pkg.github.com`.
 
+For maintainers, the local npm release path now includes a fast preflight:
+
+```bash
+npm run publish:preflight
+npm run publish:npm
+```
+
+The preflight checks npm auth, confirms the changelog matches `package.json`, and fails early if that exact version is already published.
+
 - Package name: `@qorejs/qore`
 - Module format: `ESM`
 - Supported runtime: `Node >= 18`
@@ -53,6 +63,19 @@ GitHub Packages installs require an authenticated session against `https://npm.p
   - npm: [npmjs.com/package/@qorejs/qore](https://www.npmjs.com/package/@qorejs/qore)
   - GitHub Packages: [github.com/qorejs/qore/packages](https://github.com/qorejs/qore/packages)
 
+## Compatibility Matrix
+
+| Surface | Status | Notes |
+| --- | --- | --- |
+| Node runtime | Supported | `Node >= 18` |
+| Browser runtime | Supported | browser DOM entrypoints require `document` |
+| Reactive core | Supported | `signal`, `computed`, `effect`, `batch`, `createRoot`, `onCleanup` |
+| Stream runtime | Supported | includes backpressure, retry, orchestration, async iteration, and abort |
+| Provider adapters | Supported | OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, generic SSE, generic line-stream |
+| Browser DOM layer | Supported | `h`, `text`, `dynamic`, `list`, `mount`, `createApp(...).mount(...)` |
+| SSR | Not supported | explicit browser-only DOM boundary in `1.0.x` |
+| Hydration | Not supported | deferred until a fully proven implementation exists |
+
 ## Core Idea
 
 `stream` is how data flows.
@@ -137,6 +160,57 @@ const anthropic = createAnthropic({
 const answer = stream(anthropic.chat('Why should stream be signal?'));
 ```
 
+### `createOpenRouter(options?)`
+
+```js
+import { createOpenRouter, stream } from '@qorejs/qore';
+
+const openrouter = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+  model: 'openai/gpt-4.1-mini'
+});
+
+const answer = stream(openrouter.chat('Why should stream be signal?'));
+```
+
+### `createDeepSeek(options?)`
+
+```js
+import { createDeepSeek, stream } from '@qorejs/qore';
+
+const deepseek = createDeepSeek({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  model: 'deepseek-chat'
+});
+
+const answer = stream(deepseek.chat('Why should stream be signal?'));
+```
+
+Provider adapters also accept a request `signal` so you can cancel in-flight streams explicitly:
+
+```js
+const controller = new AbortController();
+const answer = stream(openrouter.chat('Keep streaming', {
+  signal: controller.signal
+}));
+
+controller.abort('user navigated away');
+```
+
+### `createOllama(options?)`
+
+If you want a local-first provider path, Qore can stream directly from Ollama:
+
+```js
+import { createOllama, stream } from '@qorejs/qore';
+
+const ollama = createOllama({
+  model: 'llama3.2'
+});
+
+const answer = stream(ollama.chat('Why should stream be signal?'));
+```
+
 ### `createSSEAdapter(options?)`
 
 If your backend already streams `text/event-stream`, Qore can adopt it directly:
@@ -166,6 +240,63 @@ const answer = stream(provider.chat('hello'));
 
 That makes `stream(provider.chat(...))` a general entry point instead of something tied to a single SDK.
 
+### `createLineAdapter(options?)`
+
+If your backend streams newline-delimited JSON instead of `text/event-stream`, Qore can adopt that too:
+
+```js
+import { createLineAdapter, stream } from '@qorejs/qore';
+
+const provider = createLineAdapter({
+  name: 'Local NDJSON Chat',
+  url: 'http://localhost:11434/api/chat',
+  buildRequest(request) {
+    return {
+      method: 'POST',
+      body: JSON.stringify(request)
+    };
+  },
+  buildChatRequest(input) {
+    return {
+      model: 'llama3.2',
+      messages: [{ role: 'user', content: input }]
+    };
+  },
+  lineToText(event) {
+    return typeof event.data?.message?.content === 'string'
+      ? event.data.message.content
+      : undefined;
+  }
+});
+
+const answer = stream(provider.chat('hello'));
+```
+
+## Provider Support Matrix
+
+| Adapter | Transport | Status | Notes |
+| --- | --- | --- | --- |
+| `createOpenAI(...)` | SSE | Supported | OpenAI Responses streaming |
+| `createAnthropic(...)` | SSE | Supported | Anthropic Messages streaming |
+| `createOpenRouter(...)` | SSE | Supported | chat-completions style SSE |
+| `createDeepSeek(...)` | SSE | Supported | chat-completions style SSE |
+| `createOllama(...)` | line-stream / NDJSON | Supported | local-first model path |
+| `createSSEAdapter(...)` | SSE | Supported | generic hosted or self-managed SSE |
+| `createLineAdapter(...)` | line-stream / NDJSON | Supported | generic line-delimited transport |
+
+Common guarantees across supported adapters:
+
+- async iterable text streaming
+- request `signal` support for cancellation
+- typed event streaming on provider-specific surfaces
+- package smoke coverage
+
+Additional hosted SSE guarantees:
+
+- retry contract support
+- `Last-Event-ID` resume support
+- normalized metadata helpers for usage, finish reason, response id, and model identity
+
 ## API Shape
 
 ### `stream(source, options?)`
@@ -189,6 +320,80 @@ const events = stream.list(eventSource);
 const latest = stream.latest(modelEvents);
 ```
 
+For append-heavy DOM lists such as chat transcripts, pass a stable key:
+
+```js
+list(messages, (message) => h('article', {}, message.body), {
+  key: (message) => message.id
+});
+```
+
+## Server-Side SSE
+
+If you want Qore to produce the server stream as well:
+
+```js
+import { createSSEResponse } from '@qorejs/qore';
+
+export function handler() {
+  return createSSEResponse(['hello', ' world']);
+}
+```
+
+If you need orchestration:
+
+```js
+const merged = stream.merge([openai.chat('a'), anthropic.chat('b')]);
+const scripted = stream.concat([retrieve.chat('a'), summarize.chat('a')]);
+const pipeline = stream.pipe(openai.chat('hello'), [
+  (draft) => review.chat(draft),
+  (reviewed) => format.chat(reviewed)
+]);
+const fastest = stream.race([openai.chat('hello'), openrouter.chat('hello')]);
+const resilient = stream.retryable(() => openai.chat('retry me'), {
+  maxRetries: 2,
+  backoff: 'exponential'
+});
+const liveAnswer = stream.switchMap(promptChanges, (prompt) => openai.chat(prompt));
+```
+
+Provider adapters can also retry dropped SSE connections and resume from the last event id:
+
+```js
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  retry: {
+    maxAttempts: 3,
+    backoff: 'exponential'
+  }
+});
+```
+
+Provider metadata can be normalized into one shared shape:
+
+```js
+import {
+  collectProviderMetadata,
+  extractAnthropicMetadata,
+  extractOpenAIMetadata
+} from '@qorejs/qore';
+
+const openaiMetadata = await collectProviderMetadata(
+  'OpenAI',
+  openai.responses.stream({ input: 'hello' }),
+  extractOpenAIMetadata
+);
+
+const anthropicMetadata = await collectProviderMetadata(
+  'Anthropic',
+  anthropic.messages.stream({ messages: [{ role: 'user', content: 'hello' }] }),
+  extractAnthropicMetadata
+);
+
+openaiMetadata.usage?.totalTokens;
+anthropicMetadata.finishReason;
+```
+
 ### Backpressure
 
 ```js
@@ -212,13 +417,24 @@ answer.buffered(); // how many chunks are queued right now
 answer.dropped();  // how many chunks were dropped by the overflow policy
 ```
 
-### `signal`, `computed`, `effect`
+### `signal`, `computed`, `effect`, `createRoot`, `onCleanup`
 
 ```js
-import { computed, signal, stream } from '@qorejs/qore';
+import { computed, createRoot, effect, onCleanup, signal, stream } from '@qorejs/qore';
 
 const answer = stream(openai.chat('hello'));
 const length = computed(() => answer().length);
+
+const dispose = createRoot((dispose) => {
+  effect(() => {
+    console.log(length());
+    onCleanup(() => console.log('effect disposed'));
+  });
+
+  return dispose;
+});
+
+dispose();
 ```
 
 ### `response`
@@ -247,7 +463,7 @@ The repository includes a landing page and a focused streaming demo:
 src/
   core/       stream, signal, response, iterable
   dom/        app mounting and DOM bindings
-  providers/  OpenAI, Anthropic, generic SSE adapters
+  providers/  OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, SSE, and line-stream adapters
   shared/     runtime utilities
   index.ts    public entrypoint
 
@@ -269,6 +485,43 @@ python3 -m http.server 4173
 
 Then open [http://127.0.0.1:4173/](http://127.0.0.1:4173/).
 
+## Server And SSR
+
+Qore's reactive core and stream runtime work in Node and browser environments today.
+
+The DOM layer is intentionally browser-only right now:
+
+- `signal`, `computed`, `effect`, `stream`, and provider adapters work in Node and the browser
+- `h`, `text`, `mount`, and `createApp(...).mount(...)` require a browser-like `document`
+- `canUseDOM()` is exported so integrations can branch cleanly before touching DOM APIs
+- `assertCanUseDOM(name?)` is exported if you want to fail fast with the same browser-boundary error shape Qore uses internally
+- the published entrypoint is checked against a frozen public API snapshot before release so accidental export drift fails CI early
+
+If you call DOM helpers without a browser-like runtime, Qore throws an entrypoint-specific error instead of failing later with a generic reference error. For example:
+
+- `h() requires a browser-like environment`
+- `mount() requires a browser-like environment`
+- `createApp(...).mount(...) requires a browser-like environment`
+
+Example:
+
+```js
+import { assertCanUseDOM, canUseDOM } from '@qorejs/qore';
+
+if (canUseDOM()) {
+  // Safe to call mount(), h(), text(), and other DOM entrypoints.
+}
+
+assertCanUseDOM('chat shell hydration');
+```
+
+That means the current `1.0.0` path is:
+
+- stable reactive runtime
+- stable streaming runtime
+- explicit browser DOM boundary
+- streaming SSR and hydration as a post-`1.0.0` expansion area unless the implementation is fully proven first
+
 ## Browser Regression
 
 Install the browser binary once:
@@ -291,7 +544,7 @@ It validates:
 
 The suite checks desktop and mobile layouts, watches for runtime console errors, exercises the primary interactions, and runs inside `release:check`.
 
-CI also uploads the browser regression evidence as workflow artifacts. The bundle includes viewport screenshots, focused page-surface screenshots, the Playwright HTML report, and a `benchmark-suite.json` attachment from the dedicated benchmark page.
+CI also uploads the browser regression evidence as workflow artifacts. The bundle includes viewport screenshots, focused page-surface screenshots, the Playwright HTML report, a `benchmark-suite.json` attachment from the dedicated benchmark page, and a human-readable benchmark summary markdown file from the benchmark gate.
 
 If a locked-down local shell cannot launch a supported headless browser, the script will defer to CI unless you force a hard local failure with `QORE_BROWSER_SMOKE_REQUIRED=1`.
 
@@ -324,6 +577,23 @@ The repository includes GitHub Actions workflows for both release validation and
 
 Because the package already includes the correct `repository` field in `package.json`, GitHub Packages can link the package back to `qorejs/qore` when the workflow publishes it.
 
+## Release Checklist
+
+The canonical release checklist lives in [`RELEASE.md`](./RELEASE.md). You can generate the current version's GitHub release body with `npm run release:notes`.
+
+For every release candidate or stable release, the minimum local gate is:
+
+```bash
+npm ci
+npm run release:check
+```
+
+For npm publishing from a local shell, run:
+
+```bash
+npm run publish:preflight
+```
+
 ## Project Hygiene
 
 The repository also includes:
@@ -357,7 +627,7 @@ The current test suite covers:
 - `signal`, `computed`, and `effect`
 - The core `stream = signal` behavior
 - `response` interoperability with async iterables
-- OpenAI, Anthropic, and generic SSE adapters
+- OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, and generic streaming adapters
 
 ## Roadmap
 

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

@@ -0,0 +1,14 @@
+import type { Cleanup } from './signal-types.js';
+interface OwnerNode {
+    parent: OwnerNode | null;
+    children: Set<OwnerNode>;
+    cleanups: Cleanup[];
+    active: boolean;
+}
+export declare function withOwner<T>(owner: OwnerNode | null, fn: () => T): T;
+export declare function createOwnedScope(): OwnerNode;
+export declare function resetOwner(owner: OwnerNode): void;
+export declare function disposeOwner(owner: OwnerNode | null | undefined): void;
+export declare function createRoot<T>(fn: (dispose: Cleanup) => T): T;
+export declare function onCleanup(cleanup: Cleanup): void;
+export {};

package/dist/src/core/owner.js

@@ -0,0 +1,66 @@
+let activeOwner = null;
+function createOwner(parent) {
+    const owner = {
+        parent,
+        children: new Set(),
+        cleanups: [],
+        active: true
+    };
+    parent?.children.add(owner);
+    return owner;
+}
+function disposeOwnerContents(owner) {
+    const children = Array.from(owner.children);
+    owner.children.clear();
+    for (let index = children.length - 1; index >= 0; index -= 1) {
+        disposeOwner(children[index]);
+    }
+    for (let index = owner.cleanups.length - 1; index >= 0; index -= 1) {
+        try {
+            const cleanup = owner.cleanups[index];
+            if (cleanup) {
+                cleanup();
+            }
+        }
+        catch {
+            // Keep unwinding the owner tree even if one cleanup throws.
+        }
+    }
+    owner.cleanups.length = 0;
+}
+export function withOwner(owner, fn) {
+    const previousOwner = activeOwner;
+    activeOwner = owner;
+    try {
+        return fn();
+    }
+    finally {
+        activeOwner = previousOwner;
+    }
+}
+export function createOwnedScope() {
+    return createOwner(activeOwner);
+}
+export function resetOwner(owner) {
+    if (!owner.active) {
+        return;
+    }
+    disposeOwnerContents(owner);
+}
+export function disposeOwner(owner) {
+    if (!owner || !owner.active) {
+        return;
+    }
+    owner.active = false;
+    disposeOwnerContents(owner);
+    owner.parent?.children.delete(owner);
+    owner.parent = null;
+}
+export function createRoot(fn) {
+    const owner = createOwner(activeOwner);
+    const dispose = () => disposeOwner(owner);
+    return withOwner(owner, () => fn(dispose));
+}
+export function onCleanup(cleanup) {
+    activeOwner?.cleanups.push(cleanup);
+}

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

@@ -3,6 +3,7 @@ export const READ = Symbol('qore.signal.read');
 let activeObserver = null;
 let batchDepth = 0;
 const pendingObservers = new Set();
+let flushingObservers = false;
 export function getActiveObserver() {
     return activeObserver;
 }
@@ -31,24 +32,33 @@ export function scheduleObserver(observer) {
     if (!observer.active) {
         return;
     }
-    if (batchDepth > 0) {
-        pendingObservers.add(observer);
+    pendingObservers.add(observer);
+    if (batchDepth > 0 || flushingObservers) {
         return;
     }
-    observer.schedule();
+    flushObservers();
 }
 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();
+    flushingObservers = true;
+    try {
+        while (pendingObservers.size > 0) {
+            const queue = Array.from(pendingObservers);
+            pendingObservers.clear();
+            queue.sort((left, right) => left.level - right.level);
+            for (const observer of queue) {
+                if (observer.active) {
+                    observer.schedule();
+                }
+            }
         }
     }
+    finally {
+        flushingObservers = false;
+    }
 }
 // Batch synchronous updates so dependent observers only re-run once afterward.
 export function batch(fn) {
@@ -58,7 +68,7 @@ export function batch(fn) {
     }
     finally {
         batchDepth -= 1;
-        if (batchDepth === 0) {
+        if (batchDepth === 0 && !flushingObservers) {
             flushObservers();
         }
     }

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

@@ -1,6 +1,7 @@
 import type { Cleanup, EffectCallback, EffectOptions, ObserverDependency, ReactiveObserver, SignalListener, SubscribeOptions } from './signal-types.js';
 export declare class SignalNode<T> implements ObserverDependency {
     value: T;
+    level: number;
     subscribers: Set<ReactiveObserver>;
     listeners: Set<SignalListener<T>>;
     constructor(initialValue: T);
@@ -13,6 +14,8 @@ export declare class SignalNode<T> implements ObserverDependency {
 }
 export declare class ComputedNode<T> implements ObserverDependency, ReactiveObserver {
     getter: () => T;
+    private owner;
+    level: number;
     subscribers: Set<ReactiveObserver>;
     listeners: Set<SignalListener<T>>;
     deps: Set<ObserverDependency>;
@@ -31,6 +34,8 @@ export declare class ComputedNode<T> implements ObserverDependency, ReactiveObse
 export declare class EffectNode implements ReactiveObserver {
     fn: EffectCallback;
     scheduler: EffectOptions['scheduler'];
+    private owner;
+    level: number;
     deps: Set<ObserverDependency>;
     active: boolean;
     scheduled: boolean;

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

@@ -1,8 +1,10 @@
-import { cleanupObserver, getActiveObserver, removePendingObserver, scheduleObserver, withActiveObserver } from './signal-context.js';
+import { batch, cleanupObserver, getActiveObserver, removePendingObserver, scheduleObserver, withActiveObserver } from './signal-context.js';
+import { createOwnedScope, disposeOwner, onCleanup, resetOwner, withOwner } from './owner.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;
+    level = 0;
     subscribers = new Set();
     listeners = new Set();
     constructor(initialValue) {
@@ -45,14 +47,18 @@ export class SignalNode {
         for (const listener of Array.from(this.listeners)) {
             listener(this.value);
         }
-        for (const observer of Array.from(this.subscribers)) {
-            scheduleObserver(observer);
-        }
+        batch(() => {
+            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;
+    owner = createOwnedScope();
+    level = 1;
     subscribers = new Set();
     listeners = new Set();
     deps = new Set();
@@ -61,6 +67,7 @@ export class ComputedNode {
     value;
     constructor(getter) {
         this.getter = getter;
+        onCleanup(() => this.stop());
         this.recompute();
     }
     get() {
@@ -96,11 +103,16 @@ export class ComputedNode {
             return;
         }
         const previousValue = this.value;
+        resetOwner(this.owner);
         cleanupObserver(this);
-        withActiveObserver(this, () => {
+        withOwner(this.owner, () => withActiveObserver(this, () => {
             const nextValue = this.getter();
             const changed = !this.initialized || !Object.is(previousValue, nextValue);
+            const nextLevel = this.deps.size > 0
+                ? Math.max(...Array.from(this.deps, (dependency) => dependency.level)) + 1
+                : 1;
             this.value = nextValue;
+            this.level = nextLevel;
             this.initialized = true;
             if (!changed) {
                 return;
@@ -108,10 +120,12 @@ export class ComputedNode {
             for (const listener of Array.from(this.listeners)) {
                 listener(this.value);
             }
-            for (const observer of Array.from(this.subscribers)) {
-                scheduleObserver(observer);
-            }
-        });
+            batch(() => {
+                for (const observer of Array.from(this.subscribers)) {
+                    scheduleObserver(observer);
+                }
+            });
+        }));
     }
     stop() {
         if (!this.active) {
@@ -120,6 +134,7 @@ export class ComputedNode {
         this.active = false;
         cleanupObserver(this);
         removePendingObserver(this);
+        disposeOwner(this.owner);
         this.subscribers.clear();
         this.listeners.clear();
     }
@@ -128,6 +143,8 @@ export class ComputedNode {
 export class EffectNode {
     fn;
     scheduler;
+    owner = createOwnedScope();
+    level = 1;
     deps = new Set();
     active = true;
     scheduled = false;
@@ -137,6 +154,7 @@ export class EffectNode {
     constructor(fn, options = {}) {
         this.fn = fn;
         this.scheduler = options.scheduler ?? 'sync';
+        onCleanup(() => this.stop());
         this.run();
     }
     schedule() {
@@ -166,18 +184,29 @@ export class EffectNode {
         }
         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();
+        const previousCleanup = this.cleanup;
+        this.cleanup = null;
+        try {
+            // Run the previous cleanup before dropping old dependencies so a thrown cleanup
+            // does not silently unsubscribe the effect from future source updates.
+            if (typeof previousCleanup === 'function') {
+                previousCleanup();
+            }
+            resetOwner(this.owner);
+            cleanupObserver(this);
+            withOwner(this.owner, () => withActiveObserver(this, () => {
+                const maybeCleanup = this.fn();
+                this.cleanup = typeof maybeCleanup === 'function' ? maybeCleanup : null;
+            }));
+            this.level = this.deps.size > 0
+                ? Math.max(...Array.from(this.deps, (dependency) => dependency.level)) + 1
+                : 1;
+        }
+        finally {
+            this.running = false;
+            if (this.needsRun && this.active) {
+                this.schedule();
+            }
         }
     }
     stop() {
@@ -189,6 +218,7 @@ export class EffectNode {
         this.needsRun = false;
         cleanupObserver(this);
         removePendingObserver(this);
+        disposeOwner(this.owner);
         if (typeof this.cleanup === 'function') {
             this.cleanup();
             this.cleanup = null;

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

@@ -9,11 +9,13 @@ export interface EffectOptions {
     scheduler?: EffectScheduler;
 }
 export interface ObserverDependency {
+    level: number;
     subscribers: Set<ReactiveObserver>;
 }
 export interface ReactiveObserver {
     deps: Set<ObserverDependency>;
     active: boolean;
+    level: number;
     schedule(): void;
     notify(): void;
 }