@qorejs/qore 0.6.0 → 0.7.0

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,228 @@
+# Qore
+
+Qore 的灵魂只有四个字：`流式响应`。
+
+它不是把数据当快照，而是把数据当河流。token 一段一段地到来，UI 就应该一段一段地响应，不需要手动拼字符串，不需要到处补 `loading`，也不需要把 partial render 当成特例处理。
+
+## Installation
+
+```bash
+npm i @qorejs/qore
+```
+
+- Package name: `@qorejs/qore`
+- Module format: `ESM`
+- Supported runtime: `Node >= 18`
+
+## Core Idea
+
+`stream` 是数据流动的方式，`signal` 是 UI 响应变化的方式。
+
+在 Qore 里，这两者是同一个 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()));
+```
+
+这里的 `answer` 同时是：
+
+- 一个只读 `signal`，`answer()` 拿到当前累积值
+- 一个 `AsyncIterable`，可以继续 `for await...of`
+- 一个带生命周期的流状态，支持 `status()`、`streaming()`、`error()`、`chunks()`
+
+## Why Qore
+
+- React 把 stream 当成特殊情况，需要额外心智去补
+- SolidJS 的 signal 很强，但没有原生 stream primitive
+- Vue 的 ref 很顺手，但 stream 依旧是外置概念
+- Qore 直接把 `stream = signal` 做成核心 API
+
+## Quick Start
+
+```js
+import { h, mount, stream, text } from '@qorejs/qore';
+
+const answer = stream(async function* () {
+  yield '流';
+  yield '式';
+  yield '响应';
+}());
+
+mount('#app', () => h('div', { className: 'answer' }, text(() => answer())));
+```
+
+上面这个例子只会更新那一个 text node，不会 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?)`
+
+如果你的后端本来就已经在吐 SSE，Qore 也可以直接把它收编进同一个 story：
+
+```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'));
+```
+
+这让 `stream(provider.chat(...))` 不再绑定某一家 SDK，而是成为一个通用入口。
+
+## API Shape
+
+### `stream(source, options?)`
+
+默认把 chunk 累积成文本 signal：
+
+```js
+const answer = stream(openai.chat('hello'));
+
+answer();           // 当前文本
+answer.status();    // idle | pending | streaming | completed | error | aborted
+answer.streaming(); // boolean
+answer.chunks();    // 原始 chunk 列表
+await answer.ready; // 等待结束
+```
+
+如果你需要结构化流：
+
+```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 现在不只是“睡一下”：
+
+- `interval`：chunk 进入 signal / UI 之间的最小间隔
+- `buffer`：在 UI 前面最多允许排队多少个 chunk
+- `overflow`：缓冲区满了以后怎么办，可选 `wait` / `drop-oldest` / `drop-newest` / `error`
+
+你还可以直接观察压力状态：
+
+```js
+answer.buffered(); // 当前还有多少 chunk 在排队
+answer.dropped();  // 因 overflow 策略被丢掉了多少 chunk
+```
+
+### `signal`, `computed`, `effect`
+
+```js
+import { computed, signal, stream } from '@qorejs/qore';
+
+const answer = stream(openai.chat('hello'));
+const length = computed(() => answer().length);
+```
+
+### `response`
+
+`response` 仍然保留，但它更像底层状态机 escape hatch，适合复杂 reducer 或自定义聚合。
+
+如果你的目标是“把流直接接进 UI”，优先使用 `stream(...)`。
+
+## Demos
+
+仓库里带了完整 landing page 和 focused 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)
+
+本地预览：
+
+```bash
+git clone git@github.com:qorejs/qore.git
+cd qore
+python3 -m http.server 4173
+```
+
+然后打开 [http://127.0.0.1:4173/](http://127.0.0.1:4173/)。
+
+## Package Boundary
+
+Qore 核心包不内置 Button、Dialog、Tabs 这类 UI primitives。
+
+核心包只做三件事：
+
+- 让流进入状态
+- 让状态进入 UI
+- 让整个过程保持细粒度响应
+
+一切不服务于 `流式响应` 的东西，都应该放到实验层或者外围仓库。
+
+## Testing
+
+```bash
+npm test
+```
+
+当前测试覆盖了：
+
+- signal / computed / effect
+- stream = signal 的核心行为
+- response 与 async iterable 的兼容
+- OpenAI / Anthropic / generic SSE adapters
+
+## Roadmap
+
+- 围绕服务端流式渲染收敛 hydration 模型
+- 做公开 benchmark，把 Qore 和 React/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.0",
+  "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;
+}