@qorejs/qore 0.7.1 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/README.md +120 -3
  2. package/dist/src/core/iterable.d.ts +1 -0
  3. package/dist/src/core/iterable.js +17 -0
  4. package/dist/src/core/response-runtime.d.ts +2 -0
  5. package/dist/src/core/response-runtime.js +233 -0
  6. package/dist/src/core/response-state.d.ts +3 -0
  7. package/dist/src/core/response-state.js +37 -0
  8. package/dist/src/core/response-types.d.ts +73 -0
  9. package/dist/src/core/response-types.js +1 -0
  10. package/dist/src/core/response.d.ts +4 -0
  11. package/dist/src/core/response.js +26 -0
  12. package/dist/src/core/signal-context.d.ts +10 -0
  13. package/dist/src/core/signal-context.js +69 -0
  14. package/dist/src/core/signal-nodes.d.ts +45 -0
  15. package/dist/src/core/signal-nodes.js +197 -0
  16. package/dist/src/core/signal-scheduler.d.ts +2 -0
  17. package/dist/src/core/signal-scheduler.js +19 -0
  18. package/dist/src/core/signal-types.d.ts +19 -0
  19. package/dist/src/core/signal-types.js +1 -0
  20. package/dist/src/core/signal.d.ts +19 -0
  21. package/dist/src/core/signal.js +41 -0
  22. package/dist/src/core/stream-backpressure.d.ts +3 -0
  23. package/dist/src/core/stream-backpressure.js +36 -0
  24. package/dist/src/core/stream-buffer.d.ts +17 -0
  25. package/dist/src/core/stream-buffer.js +162 -0
  26. package/dist/src/core/stream-iterator.d.ts +6 -0
  27. package/dist/src/core/stream-iterator.js +14 -0
  28. package/dist/src/core/stream-lifecycle.d.ts +10 -0
  29. package/dist/src/core/stream-lifecycle.js +28 -0
  30. package/dist/src/core/stream-queue.d.ts +17 -0
  31. package/dist/src/core/stream-queue.js +62 -0
  32. package/dist/src/core/stream-runtime.d.ts +2 -0
  33. package/dist/src/core/stream-runtime.js +127 -0
  34. package/dist/src/core/stream-source.d.ts +2 -0
  35. package/dist/src/core/stream-source.js +28 -0
  36. package/dist/src/core/stream-state.d.ts +4 -0
  37. package/dist/src/core/stream-state.js +20 -0
  38. package/dist/src/core/stream-types.d.ts +61 -0
  39. package/dist/src/core/stream-types.js +1 -0
  40. package/dist/src/core/stream.d.ts +11 -0
  41. package/dist/src/core/stream.js +90 -0
  42. package/dist/src/dom/app.d.ts +38 -0
  43. package/dist/src/dom/app.js +102 -0
  44. package/dist/src/dom/dom.d.ts +13 -0
  45. package/dist/src/dom/dom.js +197 -0
  46. package/dist/src/dom/properties.d.ts +3 -0
  47. package/dist/src/dom/properties.js +147 -0
  48. package/dist/src/dom/reactive.d.ts +6 -0
  49. package/dist/src/dom/reactive.js +14 -0
  50. package/dist/src/dom/response-view.d.ts +4 -0
  51. package/dist/src/dom/response-view.js +37 -0
  52. package/dist/src/dom/scope.d.ts +10 -0
  53. package/dist/src/dom/scope.js +49 -0
  54. package/dist/src/dom/types.d.ts +34 -0
  55. package/dist/src/dom/types.js +1 -0
  56. package/dist/src/index.d.ts +16 -0
  57. package/dist/src/index.js +10 -0
  58. package/dist/src/providers/anthropic.d.ts +2 -0
  59. package/dist/src/providers/anthropic.js +102 -0
  60. package/dist/src/providers/openai.d.ts +2 -0
  61. package/dist/src/providers/openai.js +96 -0
  62. package/dist/src/providers/sse-adapter.d.ts +2 -0
  63. package/dist/src/providers/sse-adapter.js +83 -0
  64. package/dist/src/providers/sse-env.d.ts +4 -0
  65. package/dist/src/providers/sse-env.js +33 -0
  66. package/dist/src/providers/sse-parser.d.ts +5 -0
  67. package/dist/src/providers/sse-parser.js +99 -0
  68. package/dist/src/providers/sse.d.ts +4 -0
  69. package/dist/src/providers/sse.js +3 -0
  70. package/dist/src/providers/types.d.ts +94 -0
  71. package/dist/src/providers/types.js +1 -0
  72. package/dist/src/shared/utils.d.ts +2 -0
  73. package/dist/src/shared/utils.js +32 -0
  74. package/package.json +25 -11
  75. package/src/anthropic.js +0 -122
  76. package/src/app.js +0 -123
  77. package/src/dom.js +0 -527
  78. package/src/index.d.ts +0 -405
  79. package/src/index.js +0 -10
  80. package/src/iterable.js +0 -20
  81. package/src/openai.js +0 -112
  82. package/src/response.js +0 -312
  83. package/src/signal.js +0 -328
  84. package/src/sse.js +0 -264
  85. package/src/stream.js +0 -582
  86. package/src/utils.js +0 -39
package/README.md CHANGED
@@ -1,18 +1,55 @@
1
1
  # Qore
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/%40qorejs%2Fqore?color=0f766e&label=npm)](https://www.npmjs.com/package/@qorejs/qore)
4
+ [![ci](https://github.com/qorejs/qore/actions/workflows/ci.yml/badge.svg)](https://github.com/qorejs/qore/actions/workflows/ci.yml)
5
+ [![browser smoke](https://img.shields.io/badge/browser-smoke-playwright-45ba63)](#browser-regression)
6
+ [![release checks](https://github.com/qorejs/qore/actions/workflows/release-check.yml/badge.svg)](https://github.com/qorejs/qore/actions/workflows/release-check.yml)
7
+ [![publish github packages](https://github.com/qorejs/qore/actions/workflows/publish-github-packages.yml/badge.svg)](https://github.com/qorejs/qore/actions/workflows/publish-github-packages.yml)
8
+ [![GitHub Packages](https://img.shields.io/badge/GitHub-Packages-181717?logo=github)](https://github.com/qorejs/qore/packages)
9
+ [![node >= 18](https://img.shields.io/badge/node-%3E%3D18-1f6feb)](https://nodejs.org/)
10
+ [![license: MIT](https://img.shields.io/badge/license-MIT-0f766e)](https://github.com/qorejs/qore/blob/main/LICENSE)
11
+
3
12
  Qore is a streaming-response framework where `stream = signal`.
4
13
 
5
14
  Instead of treating data as a snapshot, Qore treats it like a river. Tokens arrive piece by piece, and the UI should respond piece by piece too. No manual string accumulation. No scattered loading state. No partial rendering workaround layered on top of a snapshot-first mental model.
6
15
 
16
+ Quick links:
17
+
18
+ - [npm package](https://www.npmjs.com/package/@qorejs/qore)
19
+ - [GitHub Packages](https://github.com/qorejs/qore/packages)
20
+ - [landing page source](https://github.com/qorejs/qore/blob/main/index.html)
21
+ - [streaming demo source](https://github.com/qorejs/qore/blob/main/examples/streaming-response.html)
22
+ - [benchmark page](https://github.com/qorejs/qore/blob/main/examples/benchmark.html)
23
+ - [continuous integration](https://github.com/qorejs/qore/actions/workflows/ci.yml)
24
+ - [release workflow](https://github.com/qorejs/qore/actions/workflows/release-check.yml)
25
+ - [contributing guide](https://github.com/qorejs/qore/blob/main/CONTRIBUTING.md)
26
+ - [security policy](https://github.com/qorejs/qore/blob/main/SECURITY.md)
27
+
7
28
  ## Installation
8
29
 
30
+ From npm:
31
+
32
+ ```bash
33
+ npm i @qorejs/qore
34
+ ```
35
+
36
+ From GitHub Packages:
37
+
9
38
  ```bash
39
+ echo "@qorejs:registry=https://npm.pkg.github.com" >> .npmrc
10
40
  npm i @qorejs/qore
11
41
  ```
12
42
 
43
+ GitHub Packages installs require an authenticated session against `https://npm.pkg.github.com`.
44
+
13
45
  - Package name: `@qorejs/qore`
14
46
  - Module format: `ESM`
15
47
  - Supported runtime: `Node >= 18`
48
+ - CI coverage: `Node 18`, `20`, and `22`
49
+ - Browser regression: Playwright desktop + mobile smoke coverage for the homepage, focused demo, and benchmark page
50
+ - Registries:
51
+ - npm: [npmjs.com/package/@qorejs/qore](https://www.npmjs.com/package/@qorejs/qore)
52
+ - GitHub Packages: [github.com/qorejs/qore/packages](https://github.com/qorejs/qore/packages)
16
53
 
17
54
  ## Core Idea
18
55
 
@@ -182,22 +219,102 @@ If your goal is to pipe a stream directly into the UI, prefer `stream(...)`.
182
219
  The repository includes a landing page and a focused streaming demo:
183
220
 
184
221
  - [Landing Page Source](https://github.com/qorejs/qore/blob/main/index.html)
185
- - [Homepage Logic](https://github.com/qorejs/qore/blob/main/examples/showcase.js)
222
+ - [Homepage Logic](https://github.com/qorejs/qore/blob/main/examples/showcase.ts)
186
223
  - [Homepage Styles](https://github.com/qorejs/qore/blob/main/examples/showcase.css)
224
+ - [Benchmark Page](https://github.com/qorejs/qore/blob/main/examples/benchmark.html)
225
+ - [Benchmark Logic](https://github.com/qorejs/qore/blob/main/examples/benchmark-page.ts)
226
+ - [Benchmark Core](https://github.com/qorejs/qore/blob/main/examples/benchmark-core.ts)
187
227
  - [Focused Demo](https://github.com/qorejs/qore/blob/main/examples/streaming-response.html)
188
- - [Focused Chat Logic](https://github.com/qorejs/qore/blob/main/examples/qore-chat.js)
189
- - [React Compare](https://github.com/qorejs/qore/blob/main/examples/react-chat.jsx)
228
+ - [Focused Chat Logic](https://github.com/qorejs/qore/blob/main/examples/qore-chat.ts)
229
+ - [React Compare](https://github.com/qorejs/qore/blob/main/examples/react-chat.ts)
230
+
231
+ ## Project Layout
232
+
233
+ ```text
234
+ src/
235
+ core/ stream, signal, response, iterable
236
+ dom/ app mounting and DOM bindings
237
+ providers/ OpenAI, Anthropic, generic SSE adapters
238
+ shared/ runtime utilities
239
+ index.ts public entrypoint
240
+
241
+ dist/
242
+ src/ compiled package output
243
+ examples/ built showcase scripts for local preview
244
+ test/ compiled test output
245
+ ```
190
246
 
191
247
  For a local preview:
192
248
 
193
249
  ```bash
194
250
  git clone git@github.com:qorejs/qore.git
195
251
  cd qore
252
+ npm install
253
+ npm run build
196
254
  python3 -m http.server 4173
197
255
  ```
198
256
 
199
257
  Then open [http://127.0.0.1:4173/](http://127.0.0.1:4173/).
200
258
 
259
+ ## Browser Regression
260
+
261
+ Install the browser binary once:
262
+
263
+ ```bash
264
+ npm run browsers:install
265
+ ```
266
+
267
+ Then run the browser smoke suite:
268
+
269
+ ```bash
270
+ npm run test:browser
271
+ ```
272
+
273
+ It validates:
274
+
275
+ - the homepage stream demo
276
+ - the focused streaming chat demo
277
+ - the dedicated benchmark page
278
+
279
+ The suite checks desktop and mobile layouts, watches for runtime console errors, exercises the primary interactions, and runs inside `release:check`.
280
+
281
+ 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.
282
+
283
+ 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`.
284
+
285
+ ## Benchmark Methodology
286
+
287
+ Qore now includes a reproducible browser benchmark that compares two rendering paths against the same workload:
288
+
289
+ - `Qore stream = signal`: mount the transcript shell once and advance the same live text node as chunks arrive
290
+ - `Snapshot rerender baseline`: rebuild the transcript shell from a snapshot string on every chunk
291
+
292
+ Both paths use the same transcript history, the same chunk list, and the same final answer text. The benchmark reports first paint time, mutation records, node churn, and regenerated markup so the difference is visible instead of rhetorical.
293
+
294
+ ## GitHub Packages
295
+
296
+ The repository includes GitHub Actions workflows for both release validation and GitHub Packages publishing.
297
+
298
+ - Release validation: `.github/workflows/release-check.yml`
299
+ - GitHub Packages publish: `.github/workflows/publish-github-packages.yml`
300
+ - Both workflows can be triggered manually from the Actions tab
301
+ - Publishing a GitHub Release triggers both the release check and the GitHub Packages publish flow
302
+ - The publish workflow validates the release tag, changelog, test suite, and tarball before it pushes the package
303
+ - The publish workflow uses the repository `GITHUB_TOKEN`, which GitHub documents as the recommended way to publish packages from the workflow repository
304
+ - GitHub Packages starts new packages as private by default, so you may want to switch the package visibility to public after the first publish
305
+
306
+ 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.
307
+
308
+ ## Project Hygiene
309
+
310
+ The repository also includes:
311
+
312
+ - `CONTRIBUTING.md` for contributor expectations and release flow
313
+ - `SECURITY.md` for responsible disclosure
314
+ - issue templates for bugs and feature requests
315
+ - a pull request template
316
+ - `.github/release.yml` to keep GitHub release notes structured
317
+
201
318
  ## Package Boundary
202
319
 
203
320
  Qore does not ship a built-in catalog of buttons, dialogs, tabs, or other UI primitives.
@@ -0,0 +1 @@
1
+ export declare function toAsyncIterable<T>(source: T | Iterable<T> | AsyncIterable<T> | null | undefined): AsyncIterable<T>;
@@ -0,0 +1,17 @@
1
+ // Normalize values, iterables, and async iterables into one async iterable shape.
2
+ export function toAsyncIterable(source) {
3
+ if (source == null) {
4
+ return (async function* empty() { })();
5
+ }
6
+ if (typeof source[Symbol.asyncIterator] === 'function') {
7
+ return source;
8
+ }
9
+ if (typeof source[Symbol.iterator] === 'function') {
10
+ return (async function* fromIterable() {
11
+ yield* source;
12
+ })();
13
+ }
14
+ return (async function* fromValue() {
15
+ yield source;
16
+ })();
17
+ }
@@ -0,0 +1,2 @@
1
+ import type { CreateResponseOptions, ResponseState } from './response-types.js';
2
+ export declare function createResponse<TChunk, TValue>(options: CreateResponseOptions<TChunk, TValue>): ResponseState<TChunk, TValue>;
@@ -0,0 +1,233 @@
1
+ import { batch } from './signal.js';
2
+ import { toAsyncIterable } from './iterable.js';
3
+ import { createResponseState, isTerminalStatus } from './response-state.js';
4
+ import { normalizeError } from '../shared/utils.js';
5
+ function isResponseSourceFactory(source) {
6
+ const callableSource = source;
7
+ return typeof source === 'function'
8
+ && typeof callableSource[Symbol.asyncIterator] !== 'function'
9
+ && typeof callableSource.peek !== 'function';
10
+ }
11
+ // Build a response state machine that accumulates chunks into a reactive value.
12
+ export function createResponse(options) {
13
+ const { seed, reduce } = options;
14
+ const state = createResponseState(seed);
15
+ const { status, value, error, chunks, startedAt, finishedAt, pending, streaming, completed, failed, aborted, chunkCount } = state;
16
+ let activeController = null;
17
+ let runId = 0;
18
+ let api;
19
+ // Abort the active executor when a new run supersedes it.
20
+ function supersedeActiveRun(reason = 'Response superseded by a new run') {
21
+ if (!activeController) {
22
+ return;
23
+ }
24
+ activeController.abort(reason);
25
+ activeController = null;
26
+ }
27
+ // Reset the response to its initial seed and clear all lifecycle markers.
28
+ function reset(nextSeed = seed) {
29
+ supersedeActiveRun('Response reset');
30
+ batch(() => {
31
+ status('idle');
32
+ value(nextSeed);
33
+ error(null);
34
+ chunks([]);
35
+ startedAt(null);
36
+ finishedAt(null);
37
+ });
38
+ return nextSeed;
39
+ }
40
+ // Push a chunk through the reducer and advance the response into streaming state.
41
+ function push(chunk) {
42
+ const currentStatus = status.peek();
43
+ if (isTerminalStatus(currentStatus)) {
44
+ return value.peek();
45
+ }
46
+ const index = chunks.peek().length;
47
+ const nextValue = reduce(value.peek(), chunk, index);
48
+ batch(() => {
49
+ if (status.peek() === 'idle' || status.peek() === 'pending') {
50
+ status('streaming');
51
+ }
52
+ chunks([...chunks.peek(), chunk]);
53
+ value(nextValue);
54
+ });
55
+ return nextValue;
56
+ }
57
+ // Mark the response as completed and freeze the current accumulated value.
58
+ function complete() {
59
+ const currentStatus = status.peek();
60
+ if (isTerminalStatus(currentStatus)) {
61
+ return value.peek();
62
+ }
63
+ activeController = null;
64
+ batch(() => {
65
+ status('completed');
66
+ finishedAt(Date.now());
67
+ });
68
+ return value.peek();
69
+ }
70
+ // Capture an error unless the response is already closed.
71
+ function fail(reason) {
72
+ const currentStatus = status.peek();
73
+ const normalizedError = normalizeError(reason);
74
+ if (isTerminalStatus(currentStatus)) {
75
+ return currentStatus === 'error'
76
+ ? error.peek() ?? normalizedError
77
+ : value.peek();
78
+ }
79
+ activeController = null;
80
+ batch(() => {
81
+ status('error');
82
+ error(normalizedError);
83
+ finishedAt(Date.now());
84
+ });
85
+ return normalizedError;
86
+ }
87
+ // Abort an in-flight response while keeping the value accumulated so far.
88
+ function abort(reason = 'Response aborted') {
89
+ const currentStatus = status.peek();
90
+ if (currentStatus !== 'pending' && currentStatus !== 'streaming') {
91
+ return value.peek();
92
+ }
93
+ activeController?.abort(reason);
94
+ activeController = null;
95
+ batch(() => {
96
+ status('aborted');
97
+ finishedAt(Date.now());
98
+ });
99
+ return value.peek();
100
+ }
101
+ // Run an async executor and guard every lifecycle method to the active run only.
102
+ async function run(executor, options = {}) {
103
+ const { resetValue = true, nextSeed = seed } = options;
104
+ supersedeActiveRun();
105
+ runId += 1;
106
+ const currentRunId = runId;
107
+ const controller = new AbortController();
108
+ activeController = controller;
109
+ // A response may outlive older executors, so every write must prove it still owns the run.
110
+ const isCurrentRun = () => (currentRunId === runId
111
+ && activeController === controller
112
+ && !controller.signal.aborted);
113
+ const settleExitedRun = () => {
114
+ if (currentRunId !== runId) {
115
+ return value.peek();
116
+ }
117
+ if (status.peek() === 'error') {
118
+ throw error.peek() ?? new Error('Response failed');
119
+ }
120
+ return value.peek();
121
+ };
122
+ batch(() => {
123
+ if (resetValue) {
124
+ value(nextSeed);
125
+ chunks([]);
126
+ }
127
+ error(null);
128
+ status('pending');
129
+ startedAt(Date.now());
130
+ finishedAt(null);
131
+ });
132
+ // Expose guarded lifecycle helpers so stale executors cannot leak writes into the latest run.
133
+ const context = {
134
+ get signal() {
135
+ return controller.signal;
136
+ },
137
+ response: api,
138
+ push(chunk) {
139
+ if (!isCurrentRun()) {
140
+ return value.peek();
141
+ }
142
+ return push(chunk);
143
+ },
144
+ complete() {
145
+ if (!isCurrentRun()) {
146
+ return value.peek();
147
+ }
148
+ return complete();
149
+ },
150
+ fail(reason) {
151
+ if (!isCurrentRun()) {
152
+ return status.peek() === 'error'
153
+ ? error.peek() ?? normalizeError(reason)
154
+ : value.peek();
155
+ }
156
+ return fail(reason);
157
+ },
158
+ abort(reason) {
159
+ if (!isCurrentRun()) {
160
+ return value.peek();
161
+ }
162
+ return abort(reason);
163
+ }
164
+ };
165
+ try {
166
+ await executor(context);
167
+ if (!isCurrentRun()) {
168
+ return settleExitedRun();
169
+ }
170
+ return complete();
171
+ }
172
+ catch (reason) {
173
+ if (!isCurrentRun()) {
174
+ return settleExitedRun();
175
+ }
176
+ throw fail(reason);
177
+ }
178
+ finally {
179
+ if (currentRunId === runId && activeController === controller) {
180
+ activeController = null;
181
+ }
182
+ }
183
+ }
184
+ // Consume any async iterable-like source and route each chunk through the guarded writer.
185
+ async function consume(source, options = {}) {
186
+ return run(async ({ signal: abortSignal, push: write }) => {
187
+ const resolvedSource = isResponseSourceFactory(source)
188
+ ? await source({ signal: abortSignal, response: api })
189
+ : await source;
190
+ for await (const chunk of toAsyncIterable(resolvedSource)) {
191
+ if (abortSignal.aborted) {
192
+ break;
193
+ }
194
+ write(chunk);
195
+ }
196
+ }, options);
197
+ }
198
+ // Return a plain snapshot suitable for inspection without exposing mutable internals.
199
+ function snapshot() {
200
+ return {
201
+ status: status.peek(),
202
+ value: value.peek(),
203
+ error: error.peek(),
204
+ chunks: [...chunks.peek()],
205
+ startedAt: startedAt.peek(),
206
+ finishedAt: finishedAt.peek(),
207
+ chunkCount: chunks.peek().length
208
+ };
209
+ }
210
+ api = {
211
+ status,
212
+ value,
213
+ error,
214
+ chunks,
215
+ startedAt,
216
+ finishedAt,
217
+ pending,
218
+ streaming,
219
+ completed,
220
+ failed,
221
+ aborted,
222
+ chunkCount,
223
+ reset,
224
+ push,
225
+ complete,
226
+ fail,
227
+ abort,
228
+ run,
229
+ consume,
230
+ snapshot
231
+ };
232
+ return api;
233
+ }
@@ -0,0 +1,3 @@
1
+ import type { ResponseReactiveState, ResponseStatus } from './response-types.js';
2
+ export declare function isTerminalStatus(currentStatus: ResponseStatus): boolean;
3
+ export declare function createResponseState<TChunk, TValue>(seed: TValue): ResponseReactiveState<TChunk, TValue>;
@@ -0,0 +1,37 @@
1
+ import { computed, signal } from './signal.js';
2
+ // Treat these states as closed so late writes cannot mutate a finished response.
3
+ export function isTerminalStatus(currentStatus) {
4
+ return currentStatus === 'completed' || currentStatus === 'error' || currentStatus === 'aborted';
5
+ }
6
+ // Create the reactive state bundle that powers a response lifecycle.
7
+ export function createResponseState(seed) {
8
+ const status = signal('idle');
9
+ const value = signal(seed);
10
+ const error = signal(null);
11
+ const chunks = signal([]);
12
+ const startedAt = signal(null);
13
+ const finishedAt = signal(null);
14
+ const pending = computed(() => {
15
+ const currentStatus = status();
16
+ return currentStatus === 'pending' || currentStatus === 'streaming';
17
+ });
18
+ const streaming = computed(() => status() === 'streaming');
19
+ const completed = computed(() => status() === 'completed');
20
+ const failed = computed(() => status() === 'error');
21
+ const aborted = computed(() => status() === 'aborted');
22
+ const chunkCount = computed(() => chunks().length);
23
+ return {
24
+ status,
25
+ value,
26
+ error,
27
+ chunks,
28
+ startedAt,
29
+ finishedAt,
30
+ pending,
31
+ streaming,
32
+ completed,
33
+ failed,
34
+ aborted,
35
+ chunkCount
36
+ };
37
+ }
@@ -0,0 +1,73 @@
1
+ import type { ComputedSignal, Signal } from './signal.js';
2
+ export type MaybePromise<T> = T | Promise<T>;
3
+ export type ResponseStatus = 'idle' | 'pending' | 'streaming' | 'completed' | 'error' | 'aborted';
4
+ export type GlobalAbortSignal = typeof globalThis extends {
5
+ AbortSignal: infer T;
6
+ } ? T extends {
7
+ prototype: infer P;
8
+ } ? P : unknown : {
9
+ aborted: boolean;
10
+ reason?: unknown;
11
+ };
12
+ export interface ResponseSnapshot<TChunk = unknown, TValue = unknown> {
13
+ status: ResponseStatus;
14
+ value: TValue;
15
+ error: Error | null;
16
+ chunks: TChunk[];
17
+ startedAt: number | null;
18
+ finishedAt: number | null;
19
+ chunkCount: number;
20
+ }
21
+ export interface ResponseRunOptions<TValue> {
22
+ resetValue?: boolean;
23
+ nextSeed?: TValue;
24
+ }
25
+ export type SourceLike<T> = T | Iterable<T> | AsyncIterable<T> | null | undefined;
26
+ export interface ResponseReactiveState<TChunk, TValue> {
27
+ status: Signal<ResponseStatus>;
28
+ value: Signal<TValue>;
29
+ error: Signal<Error | null>;
30
+ chunks: Signal<TChunk[]>;
31
+ startedAt: Signal<number | null>;
32
+ finishedAt: Signal<number | null>;
33
+ pending: ComputedSignal<boolean>;
34
+ streaming: ComputedSignal<boolean>;
35
+ completed: ComputedSignal<boolean>;
36
+ failed: ComputedSignal<boolean>;
37
+ aborted: ComputedSignal<boolean>;
38
+ chunkCount: ComputedSignal<number>;
39
+ }
40
+ export interface ResponseConsumeContext<TChunk, TValue> {
41
+ signal: GlobalAbortSignal;
42
+ response: ResponseState<TChunk, TValue>;
43
+ }
44
+ export interface ResponseExecutorContext<TChunk, TValue> {
45
+ readonly signal: GlobalAbortSignal;
46
+ response: ResponseState<TChunk, TValue>;
47
+ push(chunk: TChunk): TValue;
48
+ complete(): TValue;
49
+ fail(reason?: unknown): Error | TValue;
50
+ abort(reason?: unknown): TValue;
51
+ }
52
+ export type ResponseSourceFactory<TChunk, TValue> = (context: ResponseConsumeContext<TChunk, TValue>) => MaybePromise<SourceLike<TChunk>>;
53
+ export type ResponseSource<TChunk, TValue> = SourceLike<TChunk> | ResponseSourceFactory<TChunk, TValue>;
54
+ export interface CreateResponseOptions<TChunk, TValue> {
55
+ seed: TValue;
56
+ reduce: (currentValue: TValue, chunk: TChunk, index: number) => TValue;
57
+ }
58
+ export interface ResponseState<TChunk = unknown, TValue = unknown> extends ResponseReactiveState<TChunk, TValue> {
59
+ reset(nextSeed?: TValue): TValue;
60
+ push(chunk: TChunk): TValue;
61
+ complete(): TValue;
62
+ fail(reason?: unknown): Error | TValue;
63
+ abort(reason?: unknown): TValue;
64
+ run(executor: (context: ResponseExecutorContext<TChunk, TValue>) => MaybePromise<unknown>, options?: ResponseRunOptions<TValue>): Promise<TValue>;
65
+ consume(source: ResponseSource<TChunk, TValue>, options?: ResponseRunOptions<TValue>): Promise<TValue>;
66
+ snapshot(): ResponseSnapshot<TChunk, TValue>;
67
+ }
68
+ export interface ResponseFactory {
69
+ create<TChunk, TValue>(options: CreateResponseOptions<TChunk, TValue>): ResponseState<TChunk, TValue>;
70
+ text<TChunk = string>(seed?: string): ResponseState<TChunk, string>;
71
+ list<TChunk>(seed?: TChunk[]): ResponseState<TChunk, TChunk[]>;
72
+ latest<TChunk>(seed?: TChunk | null): ResponseState<TChunk, TChunk | null>;
73
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,4 @@
1
+ import type { ResponseFactory } from './response-types.js';
2
+ export { createResponse } from './response-runtime.js';
3
+ export type { CreateResponseOptions, GlobalAbortSignal, MaybePromise, ResponseConsumeContext, ResponseExecutorContext, ResponseFactory, ResponseReactiveState, ResponseRunOptions, ResponseSnapshot, ResponseSource, ResponseSourceFactory, ResponseState, ResponseStatus, SourceLike } from './response-types.js';
4
+ export declare const response: ResponseFactory;
@@ -0,0 +1,26 @@
1
+ import { createResponse } from './response-runtime.js';
2
+ // Ship a few common reducers as convenience constructors on top of createResponse.
3
+ export { createResponse } from './response-runtime.js';
4
+ export const response = {
5
+ create(options) {
6
+ return createResponse(options);
7
+ },
8
+ text(seed = '') {
9
+ return createResponse({
10
+ seed,
11
+ reduce: (currentValue, chunk) => currentValue + String(chunk)
12
+ });
13
+ },
14
+ list(seed = []) {
15
+ return createResponse({
16
+ seed,
17
+ reduce: (currentValue, chunk) => [...currentValue, chunk]
18
+ });
19
+ },
20
+ latest(seed = null) {
21
+ return createResponse({
22
+ seed,
23
+ reduce: (_, chunk) => chunk
24
+ });
25
+ }
26
+ };
@@ -0,0 +1,10 @@
1
+ import type { ReactiveObserver } from './signal-types.js';
2
+ export declare const READ: unique symbol;
3
+ export declare function getActiveObserver(): ReactiveObserver | null;
4
+ export declare function setActiveObserver(observer: ReactiveObserver | null): void;
5
+ export declare function withActiveObserver<T>(observer: ReactiveObserver | null, fn: () => T): T;
6
+ export declare function cleanupObserver(observer: ReactiveObserver): void;
7
+ export declare function scheduleObserver(observer: ReactiveObserver): void;
8
+ export declare function removePendingObserver(observer: ReactiveObserver): void;
9
+ export declare function batch<T>(fn: () => T): T;
10
+ export declare function untrack<T>(fn: () => T): T;
@@ -0,0 +1,69 @@
1
+ // Use a sentinel so signals can still store undefined as a real value.
2
+ export const READ = Symbol('qore.signal.read');
3
+ let activeObserver = null;
4
+ let batchDepth = 0;
5
+ const pendingObservers = new Set();
6
+ export function getActiveObserver() {
7
+ return activeObserver;
8
+ }
9
+ export function setActiveObserver(observer) {
10
+ activeObserver = observer;
11
+ }
12
+ export function withActiveObserver(observer, fn) {
13
+ const previousObserver = activeObserver;
14
+ activeObserver = observer;
15
+ try {
16
+ return fn();
17
+ }
18
+ finally {
19
+ activeObserver = previousObserver;
20
+ }
21
+ }
22
+ // Remove this observer from every dependency it tracked during the last run.
23
+ export function cleanupObserver(observer) {
24
+ for (const dep of observer.deps) {
25
+ dep.subscribers.delete(observer);
26
+ }
27
+ observer.deps.clear();
28
+ }
29
+ // Queue observer work during batching, otherwise notify immediately.
30
+ export function scheduleObserver(observer) {
31
+ if (!observer.active) {
32
+ return;
33
+ }
34
+ if (batchDepth > 0) {
35
+ pendingObservers.add(observer);
36
+ return;
37
+ }
38
+ observer.schedule();
39
+ }
40
+ export function removePendingObserver(observer) {
41
+ pendingObservers.delete(observer);
42
+ }
43
+ // Flush batched observer work in FIFO-like waves until the queue is empty.
44
+ function flushObservers() {
45
+ while (pendingObservers.size > 0) {
46
+ const queue = Array.from(pendingObservers);
47
+ pendingObservers.clear();
48
+ for (const observer of queue) {
49
+ observer.schedule();
50
+ }
51
+ }
52
+ }
53
+ // Batch synchronous updates so dependent observers only re-run once afterward.
54
+ export function batch(fn) {
55
+ batchDepth += 1;
56
+ try {
57
+ return fn();
58
+ }
59
+ finally {
60
+ batchDepth -= 1;
61
+ if (batchDepth === 0) {
62
+ flushObservers();
63
+ }
64
+ }
65
+ }
66
+ // Read signals without subscribing the current observer to them.
67
+ export function untrack(fn) {
68
+ return withActiveObserver(null, fn);
69
+ }