@qorejs/qore 0.6.0 → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# Qore
+
+Qore is a streaming-response framework where `stream = signal`.
+
+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.
+
+## Installation
+
+```bash
+npm i @qorejs/qore
+```
+
+- Package name: `@qorejs/qore`
+- Module format: `ESM`
+- Supported runtime: `Node >= 18`
+
+## Core Idea
+
+`stream` is how data flows.
+`signal` is how the UI reacts.
+
+In Qore, they are two sides of the same primitive:
+
+```js
+import { createOpenAI, h, stream, text } from '@qorejs/qore';
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const answer = stream(openai.chat('hello'));
+
+return h('div', {}, text(() => answer()));
+```
+
+Here, `answer` is all of the following at once:
+
+- A read-only `signal`, so `answer()` returns the current accumulated value
+- An `AsyncIterable`, so you can still use `for await...of`
+- A lifecycle-aware streaming state, with `status()`, `streaming()`, `error()`, and `chunks()`
+
+## Why Qore
+
+- React treats streaming as a special case that needs extra machinery
+- SolidJS has excellent signals, but no native stream primitive
+- Vue has ergonomic refs, but stream handling still lives outside the core model
+- Qore makes `stream = signal` the core API from the start
+
+## Quick Start
+
+```js
+import { h, mount, stream, text } from '@qorejs/qore';
+
+const answer = stream(async function* () {
+  yield 'stream';
+  yield ' = ';
+  yield 'signal';
+}());
+
+mount('#app', () => h('div', { className: 'answer' }, text(() => answer())));
+```
+
+This updates only the text node that depends on the stream. It does not re-render the whole tree.
+
+## Providers
+
+### `createOpenAI(options?)`
+
+```js
+import { createOpenAI, stream } from '@qorejs/qore';
+
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-5'
+});
+
+const answer = stream(openai.chat('Why should stream be signal?'));
+```
+
+### `createAnthropic(options?)`
+
+```js
+import { createAnthropic, stream } from '@qorejs/qore';
+
+const anthropic = createAnthropic({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  model: 'claude-sonnet-4-20250514'
+});
+
+const answer = stream(anthropic.chat('Why should stream be signal?'));
+```
+
+### `createSSEAdapter(options?)`
+
+If your backend already streams `text/event-stream`, Qore can adopt it directly:
+
+```js
+import { createSSEAdapter, stream } from '@qorejs/qore';
+
+const provider = createSSEAdapter({
+  name: 'Local Chat',
+  url: 'http://localhost:3000/api/chat',
+  buildRequest(request) {
+    return {
+      method: 'POST',
+      body: JSON.stringify(request)
+    };
+  },
+  buildChatRequest(input) {
+    return { prompt: input };
+  },
+  eventToText(event) {
+    return event.data?.type === 'token' ? event.data.text : undefined;
+  }
+});
+
+const answer = stream(provider.chat('hello'));
+```
+
+That makes `stream(provider.chat(...))` a general entry point instead of something tied to a single SDK.
+
+## API Shape
+
+### `stream(source, options?)`
+
+By default, `stream(...)` accumulates chunks into a text signal:
+
+```js
+const answer = stream(openai.chat('hello'));
+
+answer();           // current text
+answer.status();    // idle | pending | streaming | completed | error | aborted
+answer.streaming(); // boolean
+answer.chunks();    // raw chunks
+await answer.ready; // wait for completion
+```
+
+If you need structured streams:
+
+```js
+const events = stream.list(eventSource);
+const latest = stream.latest(modelEvents);
+```
+
+### Backpressure
+
+```js
+const answer = stream.withBackpressure(openai.chat('hello'), {
+  interval: 16,
+  buffer: 8,
+  overflow: 'drop-oldest'
+});
+```
+
+Backpressure is not just a delay wrapper:
+
+- `interval`: the minimum spacing between chunk delivery into the signal and UI
+- `buffer`: the maximum number of queued chunks before the UI catches up
+- `overflow`: what to do when the buffer is full: `wait`, `drop-oldest`, `drop-newest`, or `error`
+
+You can also observe stream pressure directly:
+
+```js
+answer.buffered(); // how many chunks are queued right now
+answer.dropped();  // how many chunks were dropped by the overflow policy
+```
+
+### `signal`, `computed`, `effect`
+
+```js
+import { computed, signal, stream } from '@qorejs/qore';
+
+const answer = stream(openai.chat('hello'));
+const length = computed(() => answer().length);
+```
+
+### `response`
+
+`response` still exists, but it is closer to a lower-level state machine escape hatch for custom reducers and aggregators.
+
+If your goal is to pipe a stream directly into the UI, prefer `stream(...)`.
+
+## Demos
+
+The repository includes a landing page and a focused streaming demo:
+
+- [Landing Page Source](https://github.com/qorejs/qore/blob/main/index.html)
+- [Homepage Logic](https://github.com/qorejs/qore/blob/main/examples/showcase.js)
+- [Homepage Styles](https://github.com/qorejs/qore/blob/main/examples/showcase.css)
+- [Focused Demo](https://github.com/qorejs/qore/blob/main/examples/streaming-response.html)
+- [Focused Chat Logic](https://github.com/qorejs/qore/blob/main/examples/qore-chat.js)
+- [React Compare](https://github.com/qorejs/qore/blob/main/examples/react-chat.jsx)
+
+For a local preview:
+
+```bash
+git clone git@github.com:qorejs/qore.git
+cd qore
+python3 -m http.server 4173
+```
+
+Then open [http://127.0.0.1:4173/](http://127.0.0.1:4173/).
+
+## Package Boundary
+
+Qore does not ship a built-in catalog of buttons, dialogs, tabs, or other UI primitives.
+
+The core package does only three things:
+
+- Move streams into state
+- Move state into the UI
+- Keep the whole process finely reactive
+
+Anything that does not serve `streaming response` belongs in an experimental layer or a separate package.
+
+## Testing
+
+```bash
+npm test
+```
+
+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
+
+## Roadmap
+
+- Tighten the hydration model around server-streamed rendering
+- Publish repeatable benchmarks that compare Qore with React and the Vercel AI SDK

package/package.json

@@ -1,76 +1,54 @@
 {
   "name": "@qorejs/qore",
-  "version": "0.6.0",
-  "description": "Qore - AI-Native Frontend Framework (<3kb gzip)",
+  "version": "0.7.1",
+  "description": "Qore is a streaming-response framework where stream becomes signal.",
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
     },
-    "./ssr": {
-      "import": "./dist/ssr.js",
-      "types": "./dist/ssr.d.ts"
-    },
-    "./virtual-list": {
-      "import": "./dist/virtual-list.js",
-      "types": "./dist/virtual-list.d.ts"
-    }
+    "./package.json": "./package.json"
   },
   "files": [
-    "dist",
     "src",
     "README.md",
     "LICENSE"
   ],
   "sideEffects": false,
   "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build",
-    "build:types": "tsc --emitDeclarationOnly",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "prepublishOnly": "pnpm run build && pnpm run test",
-    "publish:npm": "npm publish --access public"
+    "test": "node --test",
+    "release:check": "npm test && npm pack --dry-run",
+    "prepublishOnly": "npm run release:check"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   },
   "keywords": [
     "qore",
-    "frontend",
-    "framework",
-    "ai-native",
-    "reactive",
-    "signals",
+    "stream",
     "streaming",
-    "ssr",
-    "virtual-list",
-    "lightweight",
-    "performance",
-    "typescript"
+    "signal",
+    "reactive",
+    "sse",
+    "ai",
+    "openai",
+    "anthropic",
+    "framework",
+    "async-iterable"
   ],
-  "author": "Qore Team",
-  "license": "MIT",
+  "homepage": "https://github.com/qorejs/qore#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/qorejs/qore.git",
-    "directory": "packages/core"
+    "url": "git+https://github.com/qorejs/qore.git"
   },
-  "homepage": "https://github.com/qorejs/qore#readme",
   "bugs": {
     "url": "https://github.com/qorejs/qore/issues"
   },
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "jsdom": "^29.0.2",
-    "typescript": "^5.4.0",
-    "vite": "^5.2.0",
-    "vite-plugin-dts": "^3.7.0",
-    "vitest": "^1.4.0"
+  "publishConfig": {
+    "access": "public"
   },
-  "engines": {
-    "node": ">=18.0.0"
-  }
+  "license": "MIT"
 }

package/src/anthropic.js

@@ -0,0 +1,122 @@
+import { createSSEAdapter, readEnv } from './sse.js';
+
+const DEFAULT_BASE_URL = 'https://api.anthropic.com/v1';
+const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+const DEFAULT_VERSION = '2023-06-01';
+const DEFAULT_MAX_TOKENS = 1024;
+
+// Normalize single-string prompts into Anthropic's Messages API shape.
+function normalizeMessages(input) {
+  if (typeof input === 'string') {
+    return [{ role: 'user', content: input }];
+  }
+
+  if (Array.isArray(input)) {
+    return input;
+  }
+
+  if (input && typeof input === 'object' && 'role' in input) {
+    return [input];
+  }
+
+  return input;
+}
+
+// Keep provider setup explicit because real API keys should stay off the client.
+export function createAnthropic(options = {}) {
+  const {
+    apiKey,
+    baseURL = DEFAULT_BASE_URL,
+    model = DEFAULT_MODEL,
+    version = DEFAULT_VERSION,
+    maxTokens = DEFAULT_MAX_TOKENS,
+    headers: defaultHeaders = {},
+    fetch: fetchImpl = globalThis.fetch
+  } = options;
+  const resolvedApiKey = apiKey ?? readEnv('ANTHROPIC_API_KEY');
+
+  if (!resolvedApiKey) {
+    throw new Error('Qore Anthropic adapter requires an API key. Pass apiKey or set ANTHROPIC_API_KEY.');
+  }
+
+  const transport = createSSEAdapter({
+    name: 'Anthropic',
+    url: `${baseURL}/messages`,
+    headers: {
+      'content-type': 'application/json',
+      'anthropic-version': version,
+      'x-api-key': resolvedApiKey,
+      ...defaultHeaders
+    },
+    fetch: fetchImpl,
+    buildRequest(request, requestOptions = {}) {
+      const { signal, headers = {}, ...overrides } = requestOptions;
+
+      return {
+        method: 'POST',
+        signal,
+        headers,
+        body: JSON.stringify({
+          model,
+          max_tokens: maxTokens,
+          stream: true,
+          ...request,
+          ...overrides
+        })
+      };
+    },
+    parse: JSON.parse,
+    isError: (event) => event.data?.type === 'error',
+    getError: (event) => event.data?.error?.message ?? 'Anthropic streaming error',
+    eventToText: (event) => (
+      event.data?.type === 'content_block_delta'
+      && event.data.delta?.type === 'text_delta'
+      && typeof event.data.delta.text === 'string'
+    )
+      ? event.data.delta.text
+      : undefined
+  });
+
+  async function* streamEvents(request, requestOptions = {}) {
+    for await (const event of transport.stream(request, requestOptions)) {
+      yield event.data;
+    }
+  }
+
+  async function* streamText(messages, requestOptions = {}) {
+    const request = messages && typeof messages === 'object' && 'messages' in messages
+      ? messages
+      : { messages };
+
+    for await (const chunk of transport.streamText(request, requestOptions)) {
+      yield chunk;
+    }
+  }
+
+  return {
+    // Stream typed semantic events from the Messages API.
+    messages: {
+      stream: streamEvents
+    },
+
+    // Stream only text delta chunks from assistant content blocks.
+    streamText(messages, requestOptions = {}) {
+      return streamText(messages, requestOptions);
+    },
+
+    // Match the Qore narrative directly: stream(anthropic.chat(prompt)).
+    chat(input, requestOptions = {}) {
+      const {
+        signal,
+        headers,
+        ...request
+      } = requestOptions;
+
+      if (!('messages' in request)) {
+        request.messages = normalizeMessages(input);
+      }
+
+      return streamText(request, { signal, headers });
+    }
+  };
+}

package/src/app.js

@@ -0,0 +1,123 @@
+import {
+  dynamic,
+  fragment,
+  h,
+  list,
+  mount,
+  renderResponse,
+  show,
+  text
+} from './dom.js';
+import { batch, computed, effect, signal, untrack } from './signal.js';
+import { response } from './response.js';
+import { from, mapStream, scanStream, stream } from './stream.js';
+
+// Resolve a CSS selector or direct node into the root mount target.
+function resolveTarget(target) {
+  if (typeof document === 'undefined') {
+    throw new Error('Qore app mounting requires a browser-like environment');
+  }
+
+  if (typeof target === 'string') {
+    const element = document.querySelector(target);
+
+    if (!element) {
+      throw new Error(`Qore could not find a mount target for selector: ${target}`);
+    }
+
+    return element;
+  }
+
+  return target;
+}
+
+// Create a tiny application shell around Qore's lower-level primitives.
+export function createApp(setup) {
+  let dispose = null;
+  let mountedRoot = null;
+  let cleanupHandlers = [];
+
+  const app = {
+    // Mount the app, provide framework primitives to setup, and render the resulting view.
+    mount(target, props = {}) {
+      const root = resolveTarget(target);
+      app.unmount();
+
+      cleanupHandlers = [];
+      mountedRoot = root;
+
+      // Expose the core runtime pieces so an app can stay entirely within Qore primitives.
+      const context = {
+        app,
+        root,
+        props,
+        signal,
+        computed,
+        effect,
+        batch,
+        untrack,
+        stream,
+        from,
+        mapStream,
+        scanStream,
+        response,
+        h,
+        text,
+        dynamic,
+        show,
+        list,
+        fragment,
+        renderResponse,
+        onCleanup(handler) {
+          if (typeof handler === 'function') {
+            cleanupHandlers.push(handler);
+          }
+
+          return handler;
+        }
+      };
+
+      // Allow setup to return either a raw view or an object with lifecycle hooks.
+      const result = setup(context);
+      const view = result && typeof result === 'object' && 'view' in result
+        ? result.view
+        : result;
+      const onMount = result && typeof result === 'object' ? result.onMount : null;
+
+      dispose = mount(root, view);
+
+      if (typeof onMount === 'function') {
+        onMount(root);
+      }
+
+      return root;
+    },
+
+    // Tear down the mounted tree and any user-registered cleanup handlers.
+    unmount() {
+      if (dispose) {
+        const stop = dispose;
+        dispose = null;
+        stop();
+      }
+
+      for (let index = cleanupHandlers.length - 1; index >= 0; index -= 1) {
+        try {
+          cleanupHandlers[index]();
+        } catch {
+          // Ignore user cleanup errors so the app can still unmount.
+        }
+      }
+
+      cleanupHandlers = [];
+      mountedRoot = null;
+      return app;
+    },
+
+    get root() {
+      return mountedRoot;
+    }
+  };
+
+  return app;
+}