mirror of
https://github.com/kennethnym/aris.git
synced 2026-02-02 13:11:17 +00:00
Compare commits
19 Commits
2eff7b49dc
...
feat/aris-
| Author | SHA1 | Date | |
|---|---|---|---|
| b744af9c51 | |||
| 1893c516f3 | |||
| 181160b018 | |||
| 559f82ce96 | |||
5e040470c7
|
|||
| c2f2aeec1d | |||
|
75ce06d39b
|
|||
| a7b6232058 | |||
| 5df3dbd1b5 | |||
| b7c7bcfc7c | |||
|
9a47dda767
|
|||
|
286a933d1e
|
|||
|
1d9de2851a
|
|||
| 80192c6dc1 | |||
|
0eb77b73c6
|
|||
| dfce846c9a | |||
|
b73e603c90
|
|||
|
037589cf4f
|
|||
|
3c16dd4275
|
@@ -39,3 +39,4 @@ Use Bun exclusively. Do not use npm or yarn.
|
||||
|
||||
- Branch: `feat/<task>`, `fix/<task>`, `ci/<task>`, etc.
|
||||
- Commits: conventional commit format, title <= 50 chars
|
||||
- Signing: If `GPG_PRIVATE_KEY_PASSPHRASE` env var is available, use it to sign commits with `git commit -S`
|
||||
|
||||
19
apps/aris-backend/package.json
Normal file
19
apps/aris-backend/package.json
Normal file
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"name": "@aris/backend",
|
||||
"version": "0.0.0",
|
||||
"type": "module",
|
||||
"main": "src/index.ts",
|
||||
"scripts": {
|
||||
"dev": "bun run --watch src/index.ts",
|
||||
"start": "bun run src/index.ts",
|
||||
"test": "bun test src/"
|
||||
},
|
||||
"dependencies": {
|
||||
"@aris/core": "workspace:*",
|
||||
"@aris/source-location": "workspace:*",
|
||||
"@aris/source-weatherkit": "workspace:*",
|
||||
"better-auth": "^1",
|
||||
"hono": "^4",
|
||||
"postgres": "^3"
|
||||
}
|
||||
}
|
||||
10
apps/aris-backend/src/index.ts
Normal file
10
apps/aris-backend/src/index.ts
Normal file
@@ -0,0 +1,10 @@
|
||||
import { Hono } from "hono"
|
||||
|
||||
const app = new Hono()
|
||||
|
||||
app.get("/health", (c) => c.json({ status: "ok" }))
|
||||
|
||||
export default {
|
||||
port: 3000,
|
||||
fetch: app.fetch,
|
||||
}
|
||||
7
apps/aris-backend/tsconfig.json
Normal file
7
apps/aris-backend/tsconfig.json
Normal file
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"extends": "../../tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"types": ["bun-types"]
|
||||
},
|
||||
"include": ["src"]
|
||||
}
|
||||
70
bun.lock
70
bun.lock
@@ -13,6 +13,18 @@
|
||||
"typescript": "^5",
|
||||
},
|
||||
},
|
||||
"apps/aris-backend": {
|
||||
"name": "@aris/backend",
|
||||
"version": "0.0.0",
|
||||
"dependencies": {
|
||||
"@aris/core": "workspace:*",
|
||||
"@aris/source-location": "workspace:*",
|
||||
"@aris/source-weatherkit": "workspace:*",
|
||||
"better-auth": "^1",
|
||||
"hono": "^4",
|
||||
"postgres": "^3",
|
||||
},
|
||||
},
|
||||
"packages/aris-core": {
|
||||
"name": "@aris/core",
|
||||
"version": "0.0.0",
|
||||
@@ -33,18 +45,52 @@
|
||||
"arktype": "^2.1.0",
|
||||
},
|
||||
},
|
||||
"packages/aris-source-location": {
|
||||
"name": "@aris/source-location",
|
||||
"version": "0.0.0",
|
||||
"dependencies": {
|
||||
"@aris/core": "workspace:*",
|
||||
},
|
||||
},
|
||||
"packages/aris-source-weatherkit": {
|
||||
"name": "@aris/source-weatherkit",
|
||||
"version": "0.0.0",
|
||||
"dependencies": {
|
||||
"@aris/core": "workspace:*",
|
||||
"@aris/source-location": "workspace:*",
|
||||
"arktype": "^2.1.0",
|
||||
},
|
||||
},
|
||||
},
|
||||
"packages": {
|
||||
"@aris/backend": ["@aris/backend@workspace:apps/aris-backend"],
|
||||
|
||||
"@aris/core": ["@aris/core@workspace:packages/aris-core"],
|
||||
|
||||
"@aris/data-source-tfl": ["@aris/data-source-tfl@workspace:packages/aris-data-source-tfl"],
|
||||
|
||||
"@aris/data-source-weatherkit": ["@aris/data-source-weatherkit@workspace:packages/aris-data-source-weatherkit"],
|
||||
|
||||
"@aris/source-location": ["@aris/source-location@workspace:packages/aris-source-location"],
|
||||
|
||||
"@aris/source-weatherkit": ["@aris/source-weatherkit@workspace:packages/aris-source-weatherkit"],
|
||||
|
||||
"@ark/schema": ["@ark/schema@0.56.0", "", { "dependencies": { "@ark/util": "0.56.0" } }, "sha512-ECg3hox/6Z/nLajxXqNhgPtNdHWC9zNsDyskwO28WinoFEnWow4IsERNz9AnXRhTZJnYIlAJ4uGn3nlLk65vZA=="],
|
||||
|
||||
"@ark/util": ["@ark/util@0.56.0", "", {}, "sha512-BghfRC8b9pNs3vBoDJhcta0/c1J1rsoS1+HgVUreMFPdhz/CRAKReAu57YEllNaSy98rWAdY1gE+gFup7OXpgA=="],
|
||||
|
||||
"@better-auth/core": ["@better-auth/core@1.4.17", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "zod": "^4.3.5" }, "peerDependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21", "better-call": "1.1.8", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1" } }, "sha512-WSaEQDdUO6B1CzAmissN6j0lx9fM9lcslEYzlApB5UzFaBeAOHNUONTdglSyUs6/idiZBoRvt0t/qMXCgIU8ug=="],
|
||||
|
||||
"@better-auth/telemetry": ["@better-auth/telemetry@1.4.17", "", { "dependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21" }, "peerDependencies": { "@better-auth/core": "1.4.17" } }, "sha512-R1BC4e/bNjQbXu7lG6ubpgmsPj7IMqky5DvMlzAtnAJWJhh99pMh/n6w5gOHa0cqDZgEAuj75IPTxv+q3YiInA=="],
|
||||
|
||||
"@better-auth/utils": ["@better-auth/utils@0.3.0", "", {}, "sha512-W+Adw6ZA6mgvnSnhOki270rwJ42t4XzSK6YWGF//BbVXL6SwCLWfyzBc1lN2m/4RM28KubdBKQ4X5VMoLRNPQw=="],
|
||||
|
||||
"@better-fetch/fetch": ["@better-fetch/fetch@1.1.21", "", {}, "sha512-/ImESw0sskqlVR94jB+5+Pxjf+xBwDZF/N5+y2/q4EqD7IARUTSpPfIo8uf39SYpCxyOCtbyYpUrZ3F/k0zT4A=="],
|
||||
|
||||
"@noble/ciphers": ["@noble/ciphers@2.1.1", "", {}, "sha512-bysYuiVfhxNJuldNXlFEitTVdNnYUc+XNJZd7Qm2a5j1vZHgY+fazadNFWFaMK/2vye0JVlxV3gHmC0WDfAOQw=="],
|
||||
|
||||
"@noble/hashes": ["@noble/hashes@2.0.1", "", {}, "sha512-XlOlEbQcE9fmuXxrVTXCTlG2nlRXa9Rj3rr5Ue/+tX+nmkgbX720YHh0VR3hBF9xDvwnb8D2shVGOwNx+ulArw=="],
|
||||
|
||||
"@oxfmt/darwin-arm64": ["@oxfmt/darwin-arm64@0.24.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-aYXuGf/yq8nsyEcHindGhiz9I+GEqLkVq8CfPbd+6VE259CpPEH+CaGHEO1j6vIOmNr8KHRq+IAjeRO2uJpb8A=="],
|
||||
|
||||
"@oxfmt/darwin-x64": ["@oxfmt/darwin-x64@0.24.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-vs3b8Bs53hbiNvcNeBilzE/+IhDTWKjSBB3v/ztr664nZk65j0xr+5IHMBNz3CFppmX7o/aBta2PxY+t+4KoPg=="],
|
||||
@@ -77,6 +123,8 @@
|
||||
|
||||
"@oxlint/win32-x64": ["@oxlint/win32-x64@1.39.0", "", { "os": "win32", "cpu": "x64" }, "sha512-sbi25lfj74hH+6qQtb7s1wEvd1j8OQbTaH8v3xTcDjrwm579Cyh0HBv1YSZ2+gsnVwfVDiCTL1D0JsNqYXszVA=="],
|
||||
|
||||
"@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
|
||||
|
||||
"@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
|
||||
|
||||
"@types/node": ["@types/node@25.0.9", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw=="],
|
||||
@@ -85,16 +133,38 @@
|
||||
|
||||
"arktype": ["arktype@2.1.29", "", { "dependencies": { "@ark/schema": "0.56.0", "@ark/util": "0.56.0", "arkregex": "0.0.5" } }, "sha512-jyfKk4xIOzvYNayqnD8ZJQqOwcrTOUbIU4293yrzAjA3O1dWh61j71ArMQ6tS/u4pD7vabSPe7nG3RCyoXW6RQ=="],
|
||||
|
||||
"better-auth": ["better-auth@1.4.17", "", { "dependencies": { "@better-auth/core": "1.4.17", "@better-auth/telemetry": "1.4.17", "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21", "@noble/ciphers": "^2.0.0", "@noble/hashes": "^2.0.0", "better-call": "1.1.8", "defu": "^6.1.4", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1", "zod": "^4.3.5" }, "peerDependencies": { "@lynx-js/react": "*", "@prisma/client": "^5.0.0 || ^6.0.0 || ^7.0.0", "@sveltejs/kit": "^2.0.0", "@tanstack/react-start": "^1.0.0", "@tanstack/solid-start": "^1.0.0", "better-sqlite3": "^12.0.0", "drizzle-kit": ">=0.31.4", "drizzle-orm": ">=0.41.0", "mongodb": "^6.0.0 || ^7.0.0", "mysql2": "^3.0.0", "next": "^14.0.0 || ^15.0.0 || ^16.0.0", "pg": "^8.0.0", "prisma": "^5.0.0 || ^6.0.0 || ^7.0.0", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0", "solid-js": "^1.0.0", "svelte": "^4.0.0 || ^5.0.0", "vitest": "^2.0.0 || ^3.0.0 || ^4.0.0", "vue": "^3.0.0" }, "optionalPeers": ["@lynx-js/react", "@prisma/client", "@sveltejs/kit", "@tanstack/react-start", "@tanstack/solid-start", "better-sqlite3", "drizzle-kit", "drizzle-orm", "mongodb", "mysql2", "next", "pg", "prisma", "react", "react-dom", "solid-js", "svelte", "vitest", "vue"] }, "sha512-VmHGQyKsEahkEs37qguROKg/6ypYpNF13D7v/lkbO7w7Aivz0Bv2h+VyUkH4NzrGY0QBKXi1577mGhDCVwp0ew=="],
|
||||
|
||||
"better-call": ["better-call@1.1.8", "", { "dependencies": { "@better-auth/utils": "^0.3.0", "@better-fetch/fetch": "^1.1.4", "rou3": "^0.7.10", "set-cookie-parser": "^2.7.1" }, "peerDependencies": { "zod": "^4.0.0" }, "optionalPeers": ["zod"] }, "sha512-XMQ2rs6FNXasGNfMjzbyroSwKwYbZ/T3IxruSS6U2MJRsSYh3wYtG3o6H00ZlKZ/C/UPOAD97tqgQJNsxyeTXw=="],
|
||||
|
||||
"bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
|
||||
|
||||
"defu": ["defu@6.1.4", "", {}, "sha512-mEQCMmwJu317oSz8CwdIOdwf3xMif1ttiM8LTufzc3g6kR+9Pe236twL8j3IYT1F7GfRgGcW6MWxzZjLIkuHIg=="],
|
||||
|
||||
"hono": ["hono@4.11.5", "", {}, "sha512-WemPi9/WfyMwZs+ZUXdiwcCh9Y+m7L+8vki9MzDw3jJ+W9Lc+12HGsd368Qc1vZi1xwW8BWMMsnK5efYKPdt4g=="],
|
||||
|
||||
"jose": ["jose@6.1.3", "", {}, "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ=="],
|
||||
|
||||
"kysely": ["kysely@0.28.10", "", {}, "sha512-ksNxfzIW77OcZ+QWSAPC7yDqUSaIVwkTWnTPNiIy//vifNbwsSgQ57OkkncHxxpcBHM3LRfLAZVEh7kjq5twVA=="],
|
||||
|
||||
"nanostores": ["nanostores@1.1.0", "", {}, "sha512-yJBmDJr18xy47dbNVlHcgdPrulSn1nhSE6Ns9vTG+Nx9VPT6iV1MD6aQFp/t52zpf82FhLLTXAXr30NuCnxvwA=="],
|
||||
|
||||
"oxfmt": ["oxfmt@0.24.0", "", { "dependencies": { "tinypool": "2.0.0" }, "optionalDependencies": { "@oxfmt/darwin-arm64": "0.24.0", "@oxfmt/darwin-x64": "0.24.0", "@oxfmt/linux-arm64-gnu": "0.24.0", "@oxfmt/linux-arm64-musl": "0.24.0", "@oxfmt/linux-x64-gnu": "0.24.0", "@oxfmt/linux-x64-musl": "0.24.0", "@oxfmt/win32-arm64": "0.24.0", "@oxfmt/win32-x64": "0.24.0" }, "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-UjeM3Peez8Tl7IJ9s5UwAoZSiDRMww7BEc21gDYxLq3S3/KqJnM3mjNxsoSHgmBvSeX6RBhoVc2MfC/+96RdSw=="],
|
||||
|
||||
"oxlint": ["oxlint@1.39.0", "", { "optionalDependencies": { "@oxlint/darwin-arm64": "1.39.0", "@oxlint/darwin-x64": "1.39.0", "@oxlint/linux-arm64-gnu": "1.39.0", "@oxlint/linux-arm64-musl": "1.39.0", "@oxlint/linux-x64-gnu": "1.39.0", "@oxlint/linux-x64-musl": "1.39.0", "@oxlint/win32-arm64": "1.39.0", "@oxlint/win32-x64": "1.39.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.10.0" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-wSiLr0wjG+KTU6c1LpVoQk7JZ7l8HCKlAkVDVTJKWmCGazsNxexxnOXl7dsar92mQcRnzko5g077ggP3RINSjA=="],
|
||||
|
||||
"postgres": ["postgres@3.4.8", "", {}, "sha512-d+JFcLM17njZaOLkv6SCev7uoLaBtfK86vMUXhW1Z4glPWh4jozno9APvW/XKFJ3CCxVoC7OL38BqRydtu5nGg=="],
|
||||
|
||||
"rou3": ["rou3@0.7.12", "", {}, "sha512-iFE4hLDuloSWcD7mjdCDhx2bKcIsYbtOTpfH5MHHLSKMOUyjqQXTeZVa289uuwEGEKFoE/BAPbhaU4B774nceg=="],
|
||||
|
||||
"set-cookie-parser": ["set-cookie-parser@2.7.2", "", {}, "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw=="],
|
||||
|
||||
"tinypool": ["tinypool@2.0.0", "", {}, "sha512-/RX9RzeH2xU5ADE7n2Ykvmi9ED3FBGPAjw9u3zucrNNaEBIO0HPSYgL0NT7+3p147ojeSdaVu08F6hjpv31HJg=="],
|
||||
|
||||
"typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
|
||||
|
||||
"undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
|
||||
|
||||
"zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
|
||||
}
|
||||
}
|
||||
|
||||
178
docs/backend-spec.md
Normal file
178
docs/backend-spec.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# ARIS Backend Specification
|
||||
|
||||
## Problem Statement
|
||||
|
||||
ARIS needs a backend service that manages per-user FeedEngine instances and delivers real-time feed updates to clients. The backend must handle authentication, maintain WebSocket connections for live updates, and accept context updates (like location) that trigger feed recalculations.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Authentication
|
||||
- Email/password authentication using BetterAuth
|
||||
- PostgreSQL for session and user storage
|
||||
- Session tokens validated via `Authorization: Bearer <token>` header
|
||||
- Auth endpoints exposed via BetterAuth's built-in routes
|
||||
|
||||
### FeedEngine Management
|
||||
- Each authenticated user gets their own FeedEngine instance
|
||||
- Instances are cached in memory with a 30-minute TTL
|
||||
- TTL resets on any activity (WebSocket message, location update)
|
||||
- Default sources registered for each user: `LocationSource`, `WeatherSource`, `TflSource`
|
||||
- Source configuration is hardcoded initially (customization deferred)
|
||||
|
||||
### WebSocket Connection
|
||||
- Single endpoint: `GET /ws` (upgrades to WebSocket)
|
||||
- Authentication via `Authorization: Bearer <token>` header on upgrade request
|
||||
- Rejected before upgrade if token is invalid
|
||||
- Multiple connections per user allowed (e.g., multiple devices)
|
||||
- All connections for a user receive the same feed updates
|
||||
- On connect: immediately send current feed state
|
||||
|
||||
### JSON-RPC Protocol
|
||||
All WebSocket communication uses JSON-RPC 2.0.
|
||||
|
||||
**Client → Server (Requests):**
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "method": "location.update", "params": { "lat": 51.5, "lng": -0.1, "accuracy": 10, "timestamp": "2025-01-01T12:00:00Z" }, "id": 1 }
|
||||
{ "jsonrpc": "2.0", "method": "feed.refresh", "params": {}, "id": 2 }
|
||||
```
|
||||
|
||||
**Server → Client (Responses):**
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "result": { "ok": true }, "id": 1 }
|
||||
```
|
||||
|
||||
**Server → Client (Notifications - no id):**
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "method": "feed.update", "params": { "items": [...], "errors": [...] } }
|
||||
```
|
||||
|
||||
### JSON-RPC Methods
|
||||
|
||||
| Method | Params | Description |
|
||||
|--------|--------|-------------|
|
||||
| `location.update` | `{ lat, lng, accuracy, timestamp }` | Push location update, triggers feed refresh |
|
||||
| `feed.refresh` | `{}` | Force manual feed refresh |
|
||||
|
||||
### Server Notifications
|
||||
|
||||
| Method | Params | Description |
|
||||
|--------|--------|-------------|
|
||||
| `feed.update` | `{ context, items, errors }` | Feed state changed |
|
||||
| `error` | `{ code, message, data? }` | Source or system error |
|
||||
|
||||
### Error Handling
|
||||
- Source failures during refresh are reported via `error` notification
|
||||
- Format: `{ "jsonrpc": "2.0", "method": "error", "params": { "code": -32000, "message": "...", "data": { "sourceId": "weather" } } }`
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **Auth Flow**
|
||||
- [ ] User can sign up with email/password via `POST /api/auth/sign-up`
|
||||
- [ ] User can sign in via `POST /api/auth/sign-in` and receive session token
|
||||
- [ ] Invalid credentials return 401
|
||||
|
||||
2. **WebSocket Connection**
|
||||
- [ ] `GET /ws` with valid `Authorization` header upgrades to WebSocket
|
||||
- [ ] `GET /ws` without valid token returns 401 (no upgrade)
|
||||
- [ ] On successful connect, client receives `feed.update` notification with current state
|
||||
- [ ] Multiple connections from same user all receive updates
|
||||
|
||||
3. **FeedEngine Lifecycle**
|
||||
- [ ] First connection for a user creates FeedEngine with default sources
|
||||
- [ ] Subsequent connections reuse the same FeedEngine
|
||||
- [ ] FeedEngine is destroyed after 30 minutes of inactivity
|
||||
- [ ] Activity (any WebSocket message) resets the TTL
|
||||
|
||||
4. **JSON-RPC Methods**
|
||||
- [ ] `location.update` updates LocationSource and triggers feed refresh
|
||||
- [ ] `feed.refresh` triggers manual refresh
|
||||
- [ ] Both return `{ "ok": true }` on success
|
||||
- [ ] Invalid method returns JSON-RPC error
|
||||
|
||||
5. **Feed Updates**
|
||||
- [ ] FeedEngine subscription pushes updates to all user's WebSocket connections
|
||||
- [ ] Updates include `context`, `items`, and `errors`
|
||||
|
||||
## Implementation Approach
|
||||
|
||||
### Phase 1: Project Setup
|
||||
1. Create `apps/aris-backend` with Hono
|
||||
2. Configure TypeScript, add dependencies (hono, better-auth, postgres driver)
|
||||
3. Set up database connection and BetterAuth
|
||||
|
||||
### Phase 2: Authentication
|
||||
4. Configure BetterAuth with email/password provider
|
||||
5. Mount BetterAuth routes at `/api/auth/*`
|
||||
6. Create session validation helper for extracting user from token
|
||||
|
||||
### Phase 3: FeedEngine Manager
|
||||
7. Create `FeedEngineManager` class:
|
||||
- `getOrCreate(userId): FeedEngine` - returns cached or creates new
|
||||
- `touch(userId)` - resets TTL
|
||||
- `destroy(userId)` - manual cleanup
|
||||
- Internal TTL cleanup loop
|
||||
8. Factory function to create FeedEngine with default sources
|
||||
|
||||
### Phase 4: WebSocket Handler
|
||||
9. Create WebSocket upgrade endpoint at `/ws`
|
||||
10. Validate `Authorization` header before upgrade
|
||||
11. On connect: register connection, send initial feed state
|
||||
12. On disconnect: unregister connection
|
||||
|
||||
### Phase 5: JSON-RPC Handler
|
||||
13. Create JSON-RPC message parser and dispatcher
|
||||
14. Implement `location.update` method
|
||||
15. Implement `feed.refresh` method
|
||||
16. Wire FeedEngine subscription to broadcast `feed.update` to all user connections
|
||||
|
||||
### Phase 6: Connection Manager
|
||||
17. Create `ConnectionManager` to track WebSocket connections per user
|
||||
18. Broadcast helper to send to all connections for a user
|
||||
|
||||
### Phase 7: Integration & Testing
|
||||
19. Integration test: auth → connect → location update → receive feed
|
||||
20. Test multiple connections receive same updates
|
||||
21. Test TTL cleanup
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
apps/aris-backend/
|
||||
├── package.json
|
||||
├── src/
|
||||
│ ├── index.ts # Entry point, Hono app
|
||||
│ ├── auth.ts # BetterAuth configuration
|
||||
│ ├── db.ts # Database connection
|
||||
│ ├── ws/
|
||||
│ │ ├── handler.ts # WebSocket upgrade & message handling
|
||||
│ │ ├── jsonrpc.ts # JSON-RPC parser & types
|
||||
│ │ └── methods.ts # Method implementations
|
||||
│ ├── feed/
|
||||
│ │ ├── manager.ts # FeedEngineManager (TTL cache)
|
||||
│ │ ├── factory.ts # Creates FeedEngine with default sources
|
||||
│ │ └── connections.ts # ConnectionManager (user → WebSocket[])
|
||||
│ └── types.ts # Shared types
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"hono": "^4",
|
||||
"better-auth": "^1",
|
||||
"postgres": "^3",
|
||||
"@aris/core": "workspace:*",
|
||||
"@aris/source-location": "workspace:*",
|
||||
"@aris/source-weatherkit": "workspace:*",
|
||||
"@aris/data-source-tfl": "workspace:*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Open Questions (Deferred)
|
||||
|
||||
- User source configuration storage (database schema)
|
||||
- Rate limiting on WebSocket methods
|
||||
- Reconnection handling (client-side concern)
|
||||
- Horizontal scaling (would need Redis for shared state)
|
||||
186
packages/aris-core/README.md
Normal file
186
packages/aris-core/README.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# @aris/core
|
||||
|
||||
Core orchestration layer for ARIS feed reconciliation.
|
||||
|
||||
## Overview
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Sources["Feed Sources (Graph)"]
|
||||
LS[Location Source]
|
||||
WS[Weather Source]
|
||||
TS[TFL Source]
|
||||
CS[Calendar Source]
|
||||
end
|
||||
|
||||
LS --> WS
|
||||
LS --> TS
|
||||
|
||||
subgraph Controller["FeedController"]
|
||||
direction TB
|
||||
C1[Holds context]
|
||||
C2[Manages source graph]
|
||||
C3[Reconciles on update]
|
||||
C4[Notifies subscribers]
|
||||
end
|
||||
|
||||
Sources --> Controller
|
||||
Controller --> Sub[Subscribers]
|
||||
```
|
||||
|
||||
## Concepts
|
||||
|
||||
### FeedSource
|
||||
|
||||
A unified interface for sources that provide context and/or feed items. Sources form a dependency graph.
|
||||
|
||||
```ts
|
||||
interface FeedSource<TItem extends FeedItem = FeedItem> {
|
||||
readonly id: string
|
||||
readonly dependencies?: readonly string[]
|
||||
|
||||
// Context production (optional)
|
||||
onContextUpdate?(
|
||||
callback: (update: Partial<Context>) => void,
|
||||
getContext: () => Context,
|
||||
): () => void
|
||||
fetchContext?(context: Context): Promise<Partial<Context>>
|
||||
|
||||
// Feed item production (optional)
|
||||
onItemsUpdate?(callback: (items: TItem[]) => void, getContext: () => Context): () => void
|
||||
fetchItems?(context: Context): Promise<TItem[]>
|
||||
}
|
||||
```
|
||||
|
||||
A source may:
|
||||
|
||||
- Provide context for other sources (implement `fetchContext`/`onContextUpdate`)
|
||||
- Produce feed items (implement `fetchItems`/`onItemsUpdate`)
|
||||
- Both
|
||||
|
||||
### Context Keys
|
||||
|
||||
Each package exports typed context keys for type-safe access:
|
||||
|
||||
```ts
|
||||
import { contextKey, type ContextKey } from "@aris/core"
|
||||
|
||||
interface Location {
|
||||
lat: number
|
||||
lng: number
|
||||
}
|
||||
|
||||
export const LocationKey: ContextKey<Location> = contextKey("location")
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Define a Context-Only Source
|
||||
|
||||
```ts
|
||||
import type { FeedSource } from "@aris/core"
|
||||
|
||||
const locationSource: FeedSource = {
|
||||
id: "location",
|
||||
|
||||
onContextUpdate(callback, _getContext) {
|
||||
const watchId = navigator.geolocation.watchPosition((pos) => {
|
||||
callback({
|
||||
[LocationKey]: { lat: pos.coords.latitude, lng: pos.coords.longitude },
|
||||
})
|
||||
})
|
||||
return () => navigator.geolocation.clearWatch(watchId)
|
||||
},
|
||||
|
||||
async fetchContext() {
|
||||
const pos = await getCurrentPosition()
|
||||
return {
|
||||
[LocationKey]: { lat: pos.coords.latitude, lng: pos.coords.longitude },
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Define a Source with Dependencies
|
||||
|
||||
```ts
|
||||
import type { FeedSource, FeedItem } from "@aris/core"
|
||||
import { contextValue } from "@aris/core"
|
||||
|
||||
type WeatherItem = FeedItem<"weather", { temp: number; condition: string }>
|
||||
|
||||
const weatherSource: FeedSource<WeatherItem> = {
|
||||
id: "weather",
|
||||
dependencies: ["location"],
|
||||
|
||||
async fetchContext(context) {
|
||||
const location = contextValue(context, LocationKey)
|
||||
if (!location) return {}
|
||||
|
||||
const weather = await fetchWeatherApi(location)
|
||||
return { [WeatherKey]: weather }
|
||||
},
|
||||
|
||||
async fetchItems(context) {
|
||||
const weather = contextValue(context, WeatherKey)
|
||||
if (!weather) return []
|
||||
|
||||
return [
|
||||
{
|
||||
id: `weather-${Date.now()}`,
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: { temp: weather.temp, condition: weather.condition },
|
||||
},
|
||||
]
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Graph Behavior
|
||||
|
||||
The source graph:
|
||||
|
||||
1. Validates all dependencies exist
|
||||
2. Detects circular dependencies
|
||||
3. Topologically sorts sources
|
||||
|
||||
On refresh:
|
||||
|
||||
1. `fetchContext` runs in dependency order
|
||||
2. `fetchItems` runs on all sources
|
||||
3. Combined items returned to subscribers
|
||||
|
||||
On reactive update:
|
||||
|
||||
1. Source pushes context update via `onContextUpdate` callback
|
||||
2. Dependent sources re-run `fetchContext`
|
||||
3. Affected sources re-run `fetchItems`
|
||||
4. Subscribers notified
|
||||
|
||||
## API
|
||||
|
||||
### Context
|
||||
|
||||
| Export | Description |
|
||||
| ---------------------------- | --------------------------------------- |
|
||||
| `ContextKey<T>` | Branded type for type-safe context keys |
|
||||
| `contextKey<T>(key)` | Creates a typed context key |
|
||||
| `contextValue(context, key)` | Type-safe context value accessor |
|
||||
| `Context` | Time + arbitrary key-value bag |
|
||||
|
||||
### Feed
|
||||
|
||||
| Export | Description |
|
||||
| ------------------------ | ------------------------ |
|
||||
| `FeedSource<TItem>` | Unified source interface |
|
||||
| `FeedItem<TType, TData>` | Single item in the feed |
|
||||
|
||||
### Legacy (deprecated)
|
||||
|
||||
| Export | Description |
|
||||
| ---------------------------- | ------------------------ |
|
||||
| `DataSource<TItem, TConfig>` | Use `FeedSource` instead |
|
||||
| `ContextProvider<T>` | Use `FeedSource` instead |
|
||||
| `ContextBridge` | Use source graph instead |
|
||||
@@ -1,10 +0,0 @@
|
||||
export interface Location {
|
||||
lat: number
|
||||
lng: number
|
||||
accuracy: number
|
||||
}
|
||||
|
||||
export interface Context {
|
||||
time: Date
|
||||
location?: Location
|
||||
}
|
||||
@@ -1,7 +0,0 @@
|
||||
import type { Context } from "./context"
|
||||
import type { FeedItem } from "./feed"
|
||||
|
||||
export interface DataSource<TItem extends FeedItem = FeedItem, TConfig = unknown> {
|
||||
readonly type: TItem["type"]
|
||||
query(context: Context, config: TConfig): Promise<TItem[]>
|
||||
}
|
||||
@@ -1,10 +0,0 @@
|
||||
export interface FeedItem<
|
||||
TType extends string = string,
|
||||
TData extends Record<string, unknown> = Record<string, unknown>,
|
||||
> {
|
||||
id: string
|
||||
type: TType
|
||||
priority: number
|
||||
timestamp: Date
|
||||
data: TData
|
||||
}
|
||||
@@ -1,5 +0,0 @@
|
||||
export type { Context, Location } from "./context"
|
||||
export type { FeedItem } from "./feed"
|
||||
export type { DataSource } from "./data-source"
|
||||
export type { ReconcilerConfig, ReconcileResult, SourceError } from "./reconciler"
|
||||
export { Reconciler } from "./reconciler"
|
||||
@@ -2,8 +2,8 @@
|
||||
"name": "@aris/core",
|
||||
"version": "0.0.0",
|
||||
"type": "module",
|
||||
"main": "index.ts",
|
||||
"types": "index.ts",
|
||||
"main": "src/index.ts",
|
||||
"types": "src/index.ts",
|
||||
"scripts": {
|
||||
"test": "bun test ."
|
||||
}
|
||||
|
||||
@@ -1,240 +0,0 @@
|
||||
import { describe, expect, test } from "bun:test"
|
||||
|
||||
import type { Context } from "./context"
|
||||
import type { DataSource } from "./data-source"
|
||||
import type { FeedItem } from "./feed"
|
||||
|
||||
import { Reconciler } from "./reconciler"
|
||||
|
||||
type WeatherData = { temp: number }
|
||||
type WeatherItem = FeedItem<"weather", WeatherData>
|
||||
|
||||
type CalendarData = { title: string }
|
||||
type CalendarItem = FeedItem<"calendar", CalendarData>
|
||||
|
||||
const createMockContext = (): Context => ({
|
||||
time: new Date("2026-01-15T12:00:00Z"),
|
||||
})
|
||||
|
||||
const createWeatherSource = (items: WeatherItem[], delay = 0): DataSource<WeatherItem> => ({
|
||||
type: "weather",
|
||||
async query() {
|
||||
if (delay > 0) {
|
||||
await new Promise((resolve) => setTimeout(resolve, delay))
|
||||
}
|
||||
return items
|
||||
},
|
||||
})
|
||||
|
||||
const createCalendarSource = (items: CalendarItem[]): DataSource<CalendarItem> => ({
|
||||
type: "calendar",
|
||||
async query() {
|
||||
return items
|
||||
},
|
||||
})
|
||||
|
||||
const createFailingSource = (type: string, error: Error): DataSource<FeedItem> => ({
|
||||
type,
|
||||
async query() {
|
||||
throw error
|
||||
},
|
||||
})
|
||||
|
||||
describe("Reconciler", () => {
|
||||
test("returns empty result when no sources registered", async () => {
|
||||
const reconciler = new Reconciler()
|
||||
const result = await reconciler.reconcile(createMockContext())
|
||||
|
||||
expect(result.items).toEqual([])
|
||||
expect(result.errors).toEqual([])
|
||||
})
|
||||
|
||||
test("collects items from single source", async () => {
|
||||
const items: WeatherItem[] = [
|
||||
{
|
||||
id: "weather-1",
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: { temp: 20 },
|
||||
},
|
||||
]
|
||||
|
||||
const reconciler = new Reconciler().register(createWeatherSource(items))
|
||||
const result = await reconciler.reconcile(createMockContext())
|
||||
|
||||
expect(result.items).toEqual(items)
|
||||
expect(result.errors).toEqual([])
|
||||
})
|
||||
|
||||
test("collects items from multiple sources", async () => {
|
||||
const weatherItems: WeatherItem[] = [
|
||||
{
|
||||
id: "weather-1",
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: { temp: 20 },
|
||||
},
|
||||
]
|
||||
|
||||
const calendarItems: CalendarItem[] = [
|
||||
{
|
||||
id: "calendar-1",
|
||||
type: "calendar",
|
||||
priority: 0.8,
|
||||
timestamp: new Date(),
|
||||
data: { title: "Meeting" },
|
||||
},
|
||||
]
|
||||
|
||||
const reconciler = new Reconciler()
|
||||
.register(createWeatherSource(weatherItems))
|
||||
.register(createCalendarSource(calendarItems))
|
||||
|
||||
const result = await reconciler.reconcile(createMockContext())
|
||||
|
||||
expect(result.items).toHaveLength(2)
|
||||
expect(result.errors).toEqual([])
|
||||
})
|
||||
|
||||
test("sorts items by priority descending", async () => {
|
||||
const weatherItems: WeatherItem[] = [
|
||||
{
|
||||
id: "weather-1",
|
||||
type: "weather",
|
||||
priority: 0.2,
|
||||
timestamp: new Date(),
|
||||
data: { temp: 20 },
|
||||
},
|
||||
]
|
||||
|
||||
const calendarItems: CalendarItem[] = [
|
||||
{
|
||||
id: "calendar-1",
|
||||
type: "calendar",
|
||||
priority: 0.9,
|
||||
timestamp: new Date(),
|
||||
data: { title: "Meeting" },
|
||||
},
|
||||
]
|
||||
|
||||
const reconciler = new Reconciler()
|
||||
.register(createWeatherSource(weatherItems))
|
||||
.register(createCalendarSource(calendarItems))
|
||||
|
||||
const result = await reconciler.reconcile(createMockContext())
|
||||
|
||||
expect(result.items[0]?.id).toBe("calendar-1")
|
||||
expect(result.items[1]?.id).toBe("weather-1")
|
||||
})
|
||||
|
||||
test("captures errors from failing sources", async () => {
|
||||
const error = new Error("Source failed")
|
||||
|
||||
const reconciler = new Reconciler().register(createFailingSource("failing", error))
|
||||
|
||||
const result = await reconciler.reconcile(createMockContext())
|
||||
|
||||
expect(result.items).toEqual([])
|
||||
expect(result.errors).toHaveLength(1)
|
||||
expect(result.errors[0]?.sourceType).toBe("failing")
|
||||
expect(result.errors[0]?.error.message).toBe("Source failed")
|
||||
})
|
||||
|
||||
test("returns partial results when some sources fail", async () => {
|
||||
const items: WeatherItem[] = [
|
||||
{
|
||||
id: "weather-1",
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: { temp: 20 },
|
||||
},
|
||||
]
|
||||
|
||||
const reconciler = new Reconciler()
|
||||
.register(createWeatherSource(items))
|
||||
.register(createFailingSource("failing", new Error("Failed")))
|
||||
|
||||
const result = await reconciler.reconcile(createMockContext())
|
||||
|
||||
expect(result.items).toHaveLength(1)
|
||||
expect(result.errors).toHaveLength(1)
|
||||
})
|
||||
|
||||
test("times out slow sources", async () => {
|
||||
const items: WeatherItem[] = [
|
||||
{
|
||||
id: "weather-1",
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: { temp: 20 },
|
||||
},
|
||||
]
|
||||
|
||||
const reconciler = new Reconciler({ timeout: 50 }).register(createWeatherSource(items, 100))
|
||||
|
||||
const result = await reconciler.reconcile(createMockContext())
|
||||
|
||||
expect(result.items).toEqual([])
|
||||
expect(result.errors).toHaveLength(1)
|
||||
expect(result.errors[0]?.sourceType).toBe("weather")
|
||||
expect(result.errors[0]?.error.message).toContain("timed out")
|
||||
})
|
||||
|
||||
test("unregister removes source", async () => {
|
||||
const items: WeatherItem[] = [
|
||||
{
|
||||
id: "weather-1",
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: { temp: 20 },
|
||||
},
|
||||
]
|
||||
|
||||
const reconciler = new Reconciler().register(createWeatherSource(items)).unregister("weather")
|
||||
|
||||
const result = await reconciler.reconcile(createMockContext())
|
||||
expect(result.items).toEqual([])
|
||||
})
|
||||
|
||||
test("infers discriminated union type from chained registers", async () => {
|
||||
const weatherItems: WeatherItem[] = [
|
||||
{
|
||||
id: "weather-1",
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: { temp: 20 },
|
||||
},
|
||||
]
|
||||
|
||||
const calendarItems: CalendarItem[] = [
|
||||
{
|
||||
id: "calendar-1",
|
||||
type: "calendar",
|
||||
priority: 0.8,
|
||||
timestamp: new Date(),
|
||||
data: { title: "Meeting" },
|
||||
},
|
||||
]
|
||||
|
||||
const reconciler = new Reconciler()
|
||||
.register(createWeatherSource(weatherItems))
|
||||
.register(createCalendarSource(calendarItems))
|
||||
|
||||
const { items } = await reconciler.reconcile(createMockContext())
|
||||
|
||||
// Type narrowing should work
|
||||
for (const item of items) {
|
||||
if (item.type === "weather") {
|
||||
expect(typeof item.data.temp).toBe("number")
|
||||
} else if (item.type === "calendar") {
|
||||
expect(typeof item.data.title).toBe("string")
|
||||
}
|
||||
}
|
||||
})
|
||||
})
|
||||
102
packages/aris-core/src/context-bridge.ts
Normal file
102
packages/aris-core/src/context-bridge.ts
Normal file
@@ -0,0 +1,102 @@
|
||||
import type { Context } from "./context"
|
||||
import type { ContextProvider } from "./context-provider"
|
||||
|
||||
interface ContextUpdatable {
|
||||
pushContextUpdate(update: Partial<Context>): void
|
||||
}
|
||||
|
||||
export interface ProviderError {
|
||||
key: string
|
||||
error: Error
|
||||
}
|
||||
|
||||
export interface RefreshResult {
|
||||
errors: ProviderError[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Bridges context providers to a feed controller.
|
||||
*
|
||||
* Subscribes to provider updates and forwards them to the controller.
|
||||
* Supports manual refresh to gather current values from all providers.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const controller = new FeedController()
|
||||
* .addDataSource(new WeatherDataSource())
|
||||
* .addDataSource(new TflDataSource())
|
||||
*
|
||||
* const bridge = new ContextBridge(controller)
|
||||
* .addProvider(new LocationProvider())
|
||||
* .addProvider(new MusicProvider())
|
||||
*
|
||||
* // Manual refresh gathers from all providers
|
||||
* await bridge.refresh()
|
||||
*
|
||||
* // Cleanup
|
||||
* bridge.stop()
|
||||
* controller.stop()
|
||||
* ```
|
||||
*/
|
||||
export class ContextBridge {
|
||||
private controller: ContextUpdatable
|
||||
private providers = new Map<string, ContextProvider>()
|
||||
private cleanups: Array<() => void> = []
|
||||
|
||||
constructor(controller: ContextUpdatable) {
|
||||
this.controller = controller
|
||||
}
|
||||
|
||||
/**
|
||||
* Registers a context provider. Immediately subscribes to updates.
|
||||
*/
|
||||
addProvider<T>(provider: ContextProvider<T>): this {
|
||||
this.providers.set(provider.key, provider as ContextProvider)
|
||||
|
||||
const cleanup = provider.onUpdate((value) => {
|
||||
this.controller.pushContextUpdate({ [provider.key]: value })
|
||||
})
|
||||
this.cleanups.push(cleanup)
|
||||
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Gathers current values from all providers and pushes to controller.
|
||||
* Use for manual refresh when user pulls to refresh.
|
||||
* Returns errors from providers that failed to fetch.
|
||||
*/
|
||||
async refresh(): Promise<RefreshResult> {
|
||||
const updates: Partial<Context> = {}
|
||||
const errors: ProviderError[] = []
|
||||
|
||||
const entries = Array.from(this.providers.entries())
|
||||
const results = await Promise.allSettled(
|
||||
entries.map(([_, provider]) => provider.fetchCurrentValue()),
|
||||
)
|
||||
|
||||
entries.forEach(([key], i) => {
|
||||
const result = results[i]
|
||||
if (result?.status === "fulfilled") {
|
||||
updates[key] = result.value
|
||||
} else if (result?.status === "rejected") {
|
||||
errors.push({
|
||||
key,
|
||||
error: result.reason instanceof Error ? result.reason : new Error(String(result.reason)),
|
||||
})
|
||||
}
|
||||
})
|
||||
|
||||
this.controller.pushContextUpdate(updates)
|
||||
|
||||
return { errors }
|
||||
}
|
||||
|
||||
/**
|
||||
* Unsubscribes from all providers.
|
||||
*/
|
||||
stop(): void {
|
||||
this.cleanups.forEach((cleanup) => cleanup())
|
||||
this.cleanups = []
|
||||
}
|
||||
}
|
||||
35
packages/aris-core/src/context-provider.ts
Normal file
35
packages/aris-core/src/context-provider.ts
Normal file
@@ -0,0 +1,35 @@
|
||||
/**
|
||||
* Provides context values reactively and on-demand.
|
||||
*
|
||||
* Implementations push updates when values change (reactive) and
|
||||
* return current values when requested (for manual refresh).
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* class LocationProvider implements ContextProvider<Location> {
|
||||
* readonly key = LocationKey
|
||||
*
|
||||
* onUpdate(callback: (value: Location) => void): () => void {
|
||||
* const watchId = navigator.geolocation.watchPosition(pos => {
|
||||
* callback({ lat: pos.coords.latitude, lng: pos.coords.longitude, accuracy: pos.coords.accuracy })
|
||||
* })
|
||||
* return () => navigator.geolocation.clearWatch(watchId)
|
||||
* }
|
||||
*
|
||||
* async fetchCurrentValue(): Promise<Location> {
|
||||
* const pos = await getCurrentPosition()
|
||||
* return { lat: pos.coords.latitude, lng: pos.coords.longitude, accuracy: pos.coords.accuracy }
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export interface ContextProvider<T = unknown> {
|
||||
/** The context key this provider populates */
|
||||
readonly key: string
|
||||
|
||||
/** Subscribe to value changes. Returns cleanup function. */
|
||||
onUpdate(callback: (value: T) => void): () => void
|
||||
|
||||
/** Fetch current value on-demand (used for manual refresh). */
|
||||
fetchCurrentValue(): Promise<T>
|
||||
}
|
||||
46
packages/aris-core/src/context.ts
Normal file
46
packages/aris-core/src/context.ts
Normal file
@@ -0,0 +1,46 @@
|
||||
/**
|
||||
* Branded type for type-safe context keys.
|
||||
*
|
||||
* Each package defines its own keys with associated value types:
|
||||
* ```ts
|
||||
* const LocationKey: ContextKey<Location> = contextKey("location")
|
||||
* ```
|
||||
*/
|
||||
export type ContextKey<T> = string & { __contextValue?: T }
|
||||
|
||||
/**
|
||||
* Creates a typed context key.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* interface Location { lat: number; lng: number; accuracy: number }
|
||||
* const LocationKey: ContextKey<Location> = contextKey("location")
|
||||
* ```
|
||||
*/
|
||||
export function contextKey<T>(key: string): ContextKey<T> {
|
||||
return key as ContextKey<T>
|
||||
}
|
||||
|
||||
/**
|
||||
* Type-safe accessor for context values.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const location = contextValue(context, LocationKey)
|
||||
* if (location) {
|
||||
* console.log(location.lat, location.lng)
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export function contextValue<T>(context: Context, key: ContextKey<T>): T | undefined {
|
||||
return context[key] as T | undefined
|
||||
}
|
||||
|
||||
/**
|
||||
* Arbitrary key-value bag representing the current state.
|
||||
* Always includes `time`. Other keys are added by context providers.
|
||||
*/
|
||||
export interface Context {
|
||||
time: Date
|
||||
[key: string]: unknown
|
||||
}
|
||||
35
packages/aris-core/src/data-source.ts
Normal file
35
packages/aris-core/src/data-source.ts
Normal file
@@ -0,0 +1,35 @@
|
||||
import type { Context } from "./context"
|
||||
import type { FeedItem } from "./feed"
|
||||
|
||||
/**
|
||||
* Produces feed items from an external source.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* type WeatherItem = FeedItem<"weather", { temp: number }>
|
||||
*
|
||||
* class WeatherDataSource implements DataSource<WeatherItem> {
|
||||
* readonly type = "weather"
|
||||
*
|
||||
* async query(context: Context): Promise<WeatherItem[]> {
|
||||
* const location = contextValue(context, LocationKey)
|
||||
* if (!location) return []
|
||||
* const data = await fetchWeather(location)
|
||||
* return [{
|
||||
* id: `weather-${Date.now()}`,
|
||||
* type: this.type,
|
||||
* priority: 0.5,
|
||||
* timestamp: context.time,
|
||||
* data: { temp: data.temperature },
|
||||
* }]
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export interface DataSource<TItem extends FeedItem = FeedItem, TConfig = unknown> {
|
||||
/** Unique identifier for this source type */
|
||||
readonly type: TItem["type"]
|
||||
|
||||
/** Queries the source and returns feed items */
|
||||
query(context: Context, config: TConfig): Promise<TItem[]>
|
||||
}
|
||||
161
packages/aris-core/src/feed-controller.ts
Normal file
161
packages/aris-core/src/feed-controller.ts
Normal file
@@ -0,0 +1,161 @@
|
||||
import type { Context } from "./context"
|
||||
import type { DataSource } from "./data-source"
|
||||
import type { FeedItem } from "./feed"
|
||||
import type { ReconcileResult } from "./reconciler"
|
||||
|
||||
import { Reconciler } from "./reconciler"
|
||||
|
||||
export interface FeedControllerConfig {
|
||||
/** Timeout for each data source query in milliseconds */
|
||||
timeout?: number
|
||||
/** Debounce window for batching context updates (default: 100ms) */
|
||||
debounceMs?: number
|
||||
/** Initial context state */
|
||||
initialContext?: Context
|
||||
}
|
||||
|
||||
export type FeedSubscriber<TItems extends FeedItem> = (result: ReconcileResult<TItems>) => void
|
||||
|
||||
interface RegisteredSource {
|
||||
source: DataSource<FeedItem, unknown>
|
||||
config: unknown
|
||||
}
|
||||
|
||||
const DEFAULT_DEBOUNCE_MS = 100
|
||||
|
||||
/**
|
||||
* Orchestrates feed reconciliation in response to context updates.
|
||||
*
|
||||
* Holds context state, debounces updates, queries data sources, and
|
||||
* notifies subscribers. Each user should have their own instance.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const controller = new FeedController({ debounceMs: 100 })
|
||||
* .addDataSource(new WeatherDataSource())
|
||||
* .addDataSource(new TflDataSource())
|
||||
*
|
||||
* controller.subscribe((result) => {
|
||||
* console.log(result.items)
|
||||
* })
|
||||
*
|
||||
* // Context update triggers debounced reconcile
|
||||
* controller.pushContextUpdate({ [LocationKey]: location })
|
||||
*
|
||||
* // Direct reconcile (no debounce)
|
||||
* const result = await controller.reconcile()
|
||||
*
|
||||
* // Cleanup
|
||||
* controller.stop()
|
||||
* ```
|
||||
*/
|
||||
export class FeedController<TItems extends FeedItem = never> {
|
||||
private sources = new Map<string, RegisteredSource>()
|
||||
private subscribers = new Set<FeedSubscriber<TItems>>()
|
||||
private context: Context
|
||||
private debounceMs: number
|
||||
private timeout: number | undefined
|
||||
private pendingTimeout: ReturnType<typeof setTimeout> | null = null
|
||||
private stopped = false
|
||||
|
||||
constructor(config?: FeedControllerConfig) {
|
||||
this.context = config?.initialContext ?? { time: new Date() }
|
||||
this.debounceMs = config?.debounceMs ?? DEFAULT_DEBOUNCE_MS
|
||||
this.timeout = config?.timeout
|
||||
}
|
||||
|
||||
/** Registers a data source. */
|
||||
addDataSource<TItem extends FeedItem, TConfig>(
|
||||
source: DataSource<TItem, TConfig>,
|
||||
config?: TConfig,
|
||||
): FeedController<TItems | TItem> {
|
||||
this.sources.set(source.type, {
|
||||
source: source as DataSource<FeedItem, unknown>,
|
||||
config,
|
||||
})
|
||||
return this as FeedController<TItems | TItem>
|
||||
}
|
||||
|
||||
/** Removes a data source by type. */
|
||||
removeDataSource<T extends TItems["type"]>(
|
||||
sourceType: T,
|
||||
): FeedController<Exclude<TItems, { type: T }>> {
|
||||
this.sources.delete(sourceType)
|
||||
return this as unknown as FeedController<Exclude<TItems, { type: T }>>
|
||||
}
|
||||
|
||||
/** Stops the controller and cancels pending reconciles. */
|
||||
stop(): void {
|
||||
this.stopped = true
|
||||
|
||||
if (this.pendingTimeout) {
|
||||
clearTimeout(this.pendingTimeout)
|
||||
this.pendingTimeout = null
|
||||
}
|
||||
}
|
||||
|
||||
/** Merges update into context and schedules a debounced reconcile. */
|
||||
pushContextUpdate(update: Partial<Context>): void {
|
||||
this.context = { ...this.context, ...update, time: new Date() }
|
||||
this.scheduleReconcile()
|
||||
}
|
||||
|
||||
/** Subscribes to feed updates. Returns unsubscribe function. */
|
||||
subscribe(callback: FeedSubscriber<TItems>): () => void {
|
||||
this.subscribers.add(callback)
|
||||
|
||||
return () => {
|
||||
this.subscribers.delete(callback)
|
||||
}
|
||||
}
|
||||
|
||||
/** Immediately reconciles with current or provided context. */
|
||||
async reconcile(context?: Context): Promise<ReconcileResult<TItems>> {
|
||||
const ctx = context ?? this.context
|
||||
const reconciler = this.createReconciler()
|
||||
return reconciler.reconcile(ctx)
|
||||
}
|
||||
|
||||
/** Returns current context. */
|
||||
getContext(): Context {
|
||||
return this.context
|
||||
}
|
||||
|
||||
private scheduleReconcile(): void {
|
||||
if (this.pendingTimeout) return
|
||||
|
||||
this.pendingTimeout = setTimeout(() => {
|
||||
this.flushPending()
|
||||
}, this.debounceMs)
|
||||
}
|
||||
|
||||
private async flushPending(): Promise<void> {
|
||||
this.pendingTimeout = null
|
||||
|
||||
if (this.stopped) return
|
||||
if (this.sources.size === 0) return
|
||||
|
||||
const reconciler = this.createReconciler()
|
||||
const result = await reconciler.reconcile(this.context)
|
||||
|
||||
this.notifySubscribers(result)
|
||||
}
|
||||
|
||||
private createReconciler(): Reconciler<TItems> {
|
||||
const reconciler = new Reconciler<TItems>({ timeout: this.timeout })
|
||||
Array.from(this.sources.values()).forEach(({ source, config }) => {
|
||||
reconciler.register(source, config)
|
||||
})
|
||||
return reconciler as Reconciler<TItems>
|
||||
}
|
||||
|
||||
private notifySubscribers(result: ReconcileResult<TItems>): void {
|
||||
this.subscribers.forEach((callback) => {
|
||||
try {
|
||||
callback(result)
|
||||
} catch {
|
||||
// Subscriber errors shouldn't break other subscribers
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
458
packages/aris-core/src/feed-engine.test.ts
Normal file
458
packages/aris-core/src/feed-engine.test.ts
Normal file
@@ -0,0 +1,458 @@
|
||||
import { describe, expect, test } from "bun:test"
|
||||
|
||||
import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
|
||||
|
||||
import { FeedEngine } from "./feed-engine"
|
||||
import { contextKey, contextValue } from "./index"
|
||||
|
||||
// =============================================================================
|
||||
// CONTEXT KEYS
|
||||
// =============================================================================
|
||||
|
||||
interface Location {
|
||||
lat: number
|
||||
lng: number
|
||||
}
|
||||
|
||||
interface Weather {
|
||||
temperature: number
|
||||
condition: string
|
||||
}
|
||||
|
||||
const LocationKey: ContextKey<Location> = contextKey("location")
|
||||
const WeatherKey: ContextKey<Weather> = contextKey("weather")
|
||||
|
||||
// =============================================================================
|
||||
// FEED ITEMS
|
||||
// =============================================================================
|
||||
|
||||
type WeatherFeedItem = FeedItem<"weather", { temperature: number; condition: string }>
|
||||
type AlertFeedItem = FeedItem<"alert", { message: string }>
|
||||
|
||||
// =============================================================================
|
||||
// TEST HELPERS
|
||||
// =============================================================================
|
||||
|
||||
interface SimulatedLocationSource extends FeedSource {
|
||||
simulateUpdate(location: Location): void
|
||||
}
|
||||
|
||||
function createLocationSource(): SimulatedLocationSource {
|
||||
let callback: ((update: Partial<Context>) => void) | null = null
|
||||
let currentLocation: Location = { lat: 0, lng: 0 }
|
||||
|
||||
return {
|
||||
id: "location",
|
||||
|
||||
onContextUpdate(cb) {
|
||||
callback = cb
|
||||
return () => {
|
||||
callback = null
|
||||
}
|
||||
},
|
||||
|
||||
async fetchContext() {
|
||||
return { [LocationKey]: currentLocation }
|
||||
},
|
||||
|
||||
simulateUpdate(location: Location) {
|
||||
currentLocation = location
|
||||
callback?.({ [LocationKey]: location })
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createWeatherSource(
|
||||
fetchWeather: (location: Location) => Promise<Weather> = async () => ({
|
||||
temperature: 20,
|
||||
condition: "sunny",
|
||||
}),
|
||||
): FeedSource<WeatherFeedItem> {
|
||||
return {
|
||||
id: "weather",
|
||||
dependencies: ["location"],
|
||||
|
||||
async fetchContext(context) {
|
||||
const location = contextValue(context, LocationKey)
|
||||
if (!location) return {}
|
||||
|
||||
const weather = await fetchWeather(location)
|
||||
return { [WeatherKey]: weather }
|
||||
},
|
||||
|
||||
async fetchItems(context) {
|
||||
const weather = contextValue(context, WeatherKey)
|
||||
if (!weather) return []
|
||||
|
||||
return [
|
||||
{
|
||||
id: `weather-${Date.now()}`,
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: {
|
||||
temperature: weather.temperature,
|
||||
condition: weather.condition,
|
||||
},
|
||||
},
|
||||
]
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createAlertSource(): FeedSource<AlertFeedItem> {
|
||||
return {
|
||||
id: "alert",
|
||||
dependencies: ["weather"],
|
||||
|
||||
async fetchItems(context) {
|
||||
const weather = contextValue(context, WeatherKey)
|
||||
if (!weather) return []
|
||||
|
||||
if (weather.condition === "storm") {
|
||||
return [
|
||||
{
|
||||
id: "alert-storm",
|
||||
type: "alert",
|
||||
priority: 1.0,
|
||||
timestamp: new Date(),
|
||||
data: { message: "Storm warning!" },
|
||||
},
|
||||
]
|
||||
}
|
||||
|
||||
return []
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// TESTS
|
||||
// =============================================================================
|
||||
|
||||
describe("FeedEngine", () => {
|
||||
describe("registration", () => {
|
||||
test("registers sources", () => {
|
||||
const engine = new FeedEngine()
|
||||
const location = createLocationSource()
|
||||
|
||||
engine.register(location)
|
||||
|
||||
// Can refresh without error
|
||||
expect(engine.refresh()).resolves.toBeDefined()
|
||||
})
|
||||
|
||||
test("unregisters sources", async () => {
|
||||
const engine = new FeedEngine()
|
||||
const location = createLocationSource()
|
||||
|
||||
engine.register(location)
|
||||
engine.unregister("location")
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.items).toHaveLength(0)
|
||||
})
|
||||
|
||||
test("allows chained registration", () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(createLocationSource())
|
||||
.register(createWeatherSource())
|
||||
.register(createAlertSource())
|
||||
|
||||
expect(engine.refresh()).resolves.toBeDefined()
|
||||
})
|
||||
})
|
||||
|
||||
describe("graph validation", () => {
|
||||
test("throws on missing dependency", () => {
|
||||
const engine = new FeedEngine()
|
||||
const orphan: FeedSource = {
|
||||
id: "orphan",
|
||||
dependencies: ["nonexistent"],
|
||||
}
|
||||
|
||||
engine.register(orphan)
|
||||
|
||||
expect(engine.refresh()).rejects.toThrow(
|
||||
'Source "orphan" depends on "nonexistent" which is not registered',
|
||||
)
|
||||
})
|
||||
|
||||
test("throws on circular dependency", () => {
|
||||
const engine = new FeedEngine()
|
||||
const a: FeedSource = { id: "a", dependencies: ["b"] }
|
||||
const b: FeedSource = { id: "b", dependencies: ["a"] }
|
||||
|
||||
engine.register(a).register(b)
|
||||
|
||||
expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
|
||||
})
|
||||
|
||||
test("throws on longer cycles", () => {
|
||||
const engine = new FeedEngine()
|
||||
const a: FeedSource = { id: "a", dependencies: ["c"] }
|
||||
const b: FeedSource = { id: "b", dependencies: ["a"] }
|
||||
const c: FeedSource = { id: "c", dependencies: ["b"] }
|
||||
|
||||
engine.register(a).register(b).register(c)
|
||||
|
||||
expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
|
||||
})
|
||||
})
|
||||
|
||||
describe("refresh", () => {
|
||||
test("runs fetchContext in dependency order", async () => {
|
||||
const order: string[] = []
|
||||
|
||||
const location: FeedSource = {
|
||||
id: "location",
|
||||
async fetchContext() {
|
||||
order.push("location")
|
||||
return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
|
||||
},
|
||||
}
|
||||
|
||||
const weather: FeedSource = {
|
||||
id: "weather",
|
||||
dependencies: ["location"],
|
||||
async fetchContext(ctx) {
|
||||
order.push("weather")
|
||||
const loc = contextValue(ctx, LocationKey)
|
||||
expect(loc).toBeDefined()
|
||||
return { [WeatherKey]: { temperature: 20, condition: "sunny" } }
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine().register(weather).register(location)
|
||||
|
||||
await engine.refresh()
|
||||
|
||||
expect(order).toEqual(["location", "weather"])
|
||||
})
|
||||
|
||||
test("accumulates context across sources", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather)
|
||||
|
||||
const { context } = await engine.refresh()
|
||||
|
||||
expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
|
||||
expect(contextValue(context, WeatherKey)).toEqual({ temperature: 20, condition: "sunny" })
|
||||
})
|
||||
|
||||
test("collects items from all sources", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather)
|
||||
|
||||
const { items } = await engine.refresh()
|
||||
|
||||
expect(items).toHaveLength(1)
|
||||
expect(items[0]!.type).toBe("weather")
|
||||
})
|
||||
|
||||
test("sorts items by priority descending", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const weather = createWeatherSource(async () => ({
|
||||
temperature: 15,
|
||||
condition: "storm",
|
||||
}))
|
||||
|
||||
const alert = createAlertSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather).register(alert)
|
||||
|
||||
const { items } = await engine.refresh()
|
||||
|
||||
expect(items).toHaveLength(2)
|
||||
expect(items[0]!.type).toBe("alert") // priority 1.0
|
||||
expect(items[1]!.type).toBe("weather") // priority 0.5
|
||||
})
|
||||
|
||||
test("handles missing upstream context gracefully", async () => {
|
||||
const location: FeedSource = {
|
||||
id: "location",
|
||||
async fetchContext() {
|
||||
return {} // No location available
|
||||
},
|
||||
}
|
||||
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather)
|
||||
|
||||
const { context, items } = await engine.refresh()
|
||||
|
||||
expect(contextValue(context, WeatherKey)).toBeUndefined()
|
||||
expect(items).toHaveLength(0)
|
||||
})
|
||||
|
||||
test("captures errors from fetchContext", async () => {
|
||||
const failing: FeedSource = {
|
||||
id: "failing",
|
||||
async fetchContext() {
|
||||
throw new Error("Context fetch failed")
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine().register(failing)
|
||||
|
||||
const { errors } = await engine.refresh()
|
||||
|
||||
expect(errors).toHaveLength(1)
|
||||
expect(errors[0]!.sourceId).toBe("failing")
|
||||
expect(errors[0]!.error.message).toBe("Context fetch failed")
|
||||
})
|
||||
|
||||
test("captures errors from fetchItems", async () => {
|
||||
const failing: FeedSource = {
|
||||
id: "failing",
|
||||
async fetchItems() {
|
||||
throw new Error("Items fetch failed")
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine().register(failing)
|
||||
|
||||
const { errors } = await engine.refresh()
|
||||
|
||||
expect(errors).toHaveLength(1)
|
||||
expect(errors[0]!.sourceId).toBe("failing")
|
||||
expect(errors[0]!.error.message).toBe("Items fetch failed")
|
||||
})
|
||||
|
||||
test("continues after source error", async () => {
|
||||
const failing: FeedSource = {
|
||||
id: "failing",
|
||||
async fetchContext() {
|
||||
throw new Error("Failed")
|
||||
},
|
||||
}
|
||||
|
||||
const working: FeedSource = {
|
||||
id: "working",
|
||||
async fetchItems() {
|
||||
return [
|
||||
{
|
||||
id: "item-1",
|
||||
type: "test",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: {},
|
||||
},
|
||||
]
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine().register(failing).register(working)
|
||||
|
||||
const { items, errors } = await engine.refresh()
|
||||
|
||||
expect(errors).toHaveLength(1)
|
||||
expect(items).toHaveLength(1)
|
||||
})
|
||||
})
|
||||
|
||||
describe("currentContext", () => {
|
||||
test("returns initial context before refresh", () => {
|
||||
const engine = new FeedEngine()
|
||||
|
||||
const context = engine.currentContext()
|
||||
|
||||
expect(context.time).toBeInstanceOf(Date)
|
||||
})
|
||||
|
||||
test("returns accumulated context after refresh", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const engine = new FeedEngine().register(location)
|
||||
|
||||
await engine.refresh()
|
||||
|
||||
const context = engine.currentContext()
|
||||
expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
|
||||
})
|
||||
})
|
||||
|
||||
describe("subscribe", () => {
|
||||
test("returns unsubscribe function", () => {
|
||||
const engine = new FeedEngine()
|
||||
let callCount = 0
|
||||
|
||||
const unsubscribe = engine.subscribe(() => {
|
||||
callCount++
|
||||
})
|
||||
|
||||
unsubscribe()
|
||||
|
||||
// Subscriber should not be called after unsubscribe
|
||||
expect(callCount).toBe(0)
|
||||
})
|
||||
})
|
||||
|
||||
describe("reactive updates", () => {
|
||||
test("start subscribes to onContextUpdate", async () => {
|
||||
const location = createLocationSource()
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather)
|
||||
|
||||
const results: Array<{ items: FeedItem[] }> = []
|
||||
engine.subscribe((result) => {
|
||||
results.push({ items: result.items })
|
||||
})
|
||||
|
||||
engine.start()
|
||||
|
||||
// Simulate location update
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
// Wait for async refresh
|
||||
await new Promise((resolve) => setTimeout(resolve, 50))
|
||||
|
||||
expect(results.length).toBeGreaterThan(0)
|
||||
expect(results[0]!.items[0]!.type).toBe("weather")
|
||||
})
|
||||
|
||||
test("stop unsubscribes from all sources", async () => {
|
||||
const location = createLocationSource()
|
||||
|
||||
const engine = new FeedEngine().register(location)
|
||||
|
||||
let callCount = 0
|
||||
engine.subscribe(() => {
|
||||
callCount++
|
||||
})
|
||||
|
||||
engine.start()
|
||||
engine.stop()
|
||||
|
||||
// Simulate update after stop
|
||||
location.simulateUpdate({ lat: 1, lng: 1 })
|
||||
|
||||
await new Promise((resolve) => setTimeout(resolve, 50))
|
||||
|
||||
expect(callCount).toBe(0)
|
||||
})
|
||||
|
||||
test("start is idempotent", () => {
|
||||
const location = createLocationSource()
|
||||
const engine = new FeedEngine().register(location)
|
||||
|
||||
// Should not throw or double-subscribe
|
||||
engine.start()
|
||||
engine.start()
|
||||
engine.stop()
|
||||
})
|
||||
})
|
||||
})
|
||||
335
packages/aris-core/src/feed-engine.ts
Normal file
335
packages/aris-core/src/feed-engine.ts
Normal file
@@ -0,0 +1,335 @@
|
||||
import type { Context } from "./context"
|
||||
import type { FeedItem } from "./feed"
|
||||
import type { FeedSource } from "./feed-source"
|
||||
|
||||
export interface SourceError {
|
||||
sourceId: string
|
||||
error: Error
|
||||
}
|
||||
|
||||
export interface FeedResult<TItem extends FeedItem = FeedItem> {
|
||||
context: Context
|
||||
items: TItem[]
|
||||
errors: SourceError[]
|
||||
}
|
||||
|
||||
export type FeedSubscriber<TItem extends FeedItem = FeedItem> = (result: FeedResult<TItem>) => void
|
||||
|
||||
interface SourceGraph {
|
||||
sources: Map<string, FeedSource>
|
||||
sorted: FeedSource[]
|
||||
dependents: Map<string, string[]>
|
||||
}
|
||||
|
||||
/**
|
||||
* Orchestrates FeedSources, managing the dependency graph and context flow.
|
||||
*
|
||||
* Sources declare dependencies on other sources. The engine:
|
||||
* - Validates the dependency graph (no missing deps, no cycles)
|
||||
* - Runs fetchContext() in topological order during refresh
|
||||
* - Runs fetchItems() on all sources with accumulated context
|
||||
* - Subscribes to reactive updates via onContextUpdate/onItemsUpdate
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const engine = new FeedEngine()
|
||||
* .register(locationSource)
|
||||
* .register(weatherSource)
|
||||
* .register(alertSource)
|
||||
*
|
||||
* // Pull-based refresh
|
||||
* const { context, items, errors } = await engine.refresh()
|
||||
*
|
||||
* // Reactive updates
|
||||
* engine.subscribe((result) => {
|
||||
* console.log(result.items)
|
||||
* })
|
||||
* engine.start()
|
||||
*
|
||||
* // Cleanup
|
||||
* engine.stop()
|
||||
* ```
|
||||
*/
|
||||
export class FeedEngine<TItems extends FeedItem = FeedItem> {
|
||||
private sources = new Map<string, FeedSource>()
|
||||
private graph: SourceGraph | null = null
|
||||
private context: Context = { time: new Date() }
|
||||
private subscribers = new Set<FeedSubscriber<TItems>>()
|
||||
private cleanups: Array<() => void> = []
|
||||
private started = false
|
||||
|
||||
/**
|
||||
* Registers a FeedSource. Invalidates the cached graph.
|
||||
*/
|
||||
register<TItem extends FeedItem>(source: FeedSource<TItem>): FeedEngine<TItems | TItem> {
|
||||
this.sources.set(source.id, source)
|
||||
this.graph = null
|
||||
return this as FeedEngine<TItems | TItem>
|
||||
}
|
||||
|
||||
/**
|
||||
* Unregisters a FeedSource by ID. Invalidates the cached graph.
|
||||
*/
|
||||
unregister(sourceId: string): this {
|
||||
this.sources.delete(sourceId)
|
||||
this.graph = null
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Refreshes the feed by running all sources in dependency order.
|
||||
* Calls fetchContext() then fetchItems() on each source.
|
||||
*/
|
||||
async refresh(): Promise<FeedResult<TItems>> {
|
||||
const graph = this.ensureGraph()
|
||||
const errors: SourceError[] = []
|
||||
|
||||
// Reset context with fresh time
|
||||
let context: Context = { time: new Date() }
|
||||
|
||||
// Run fetchContext in topological order
|
||||
for (const source of graph.sorted) {
|
||||
if (source.fetchContext) {
|
||||
try {
|
||||
const update = await source.fetchContext(context)
|
||||
context = { ...context, ...update }
|
||||
} catch (err) {
|
||||
errors.push({
|
||||
sourceId: source.id,
|
||||
error: err instanceof Error ? err : new Error(String(err)),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Run fetchItems on all sources
|
||||
const items: FeedItem[] = []
|
||||
for (const source of graph.sorted) {
|
||||
if (source.fetchItems) {
|
||||
try {
|
||||
const sourceItems = await source.fetchItems(context)
|
||||
items.push(...sourceItems)
|
||||
} catch (err) {
|
||||
errors.push({
|
||||
sourceId: source.id,
|
||||
error: err instanceof Error ? err : new Error(String(err)),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Sort by priority descending
|
||||
items.sort((a, b) => b.priority - a.priority)
|
||||
|
||||
this.context = context
|
||||
|
||||
return { context, items: items as TItems[], errors }
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscribes to feed updates. Returns unsubscribe function.
|
||||
*/
|
||||
subscribe(callback: FeedSubscriber<TItems>): () => void {
|
||||
this.subscribers.add(callback)
|
||||
return () => {
|
||||
this.subscribers.delete(callback)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Starts reactive subscriptions on all sources.
|
||||
* Sources with onContextUpdate will trigger re-computation of dependents.
|
||||
*/
|
||||
start(): void {
|
||||
if (this.started) return
|
||||
|
||||
this.started = true
|
||||
const graph = this.ensureGraph()
|
||||
|
||||
for (const source of graph.sorted) {
|
||||
if (source.onContextUpdate) {
|
||||
const cleanup = source.onContextUpdate(
|
||||
(update) => {
|
||||
this.handleContextUpdate(source.id, update)
|
||||
},
|
||||
() => this.context,
|
||||
)
|
||||
this.cleanups.push(cleanup)
|
||||
}
|
||||
|
||||
if (source.onItemsUpdate) {
|
||||
const cleanup = source.onItemsUpdate(
|
||||
() => {
|
||||
this.scheduleRefresh()
|
||||
},
|
||||
() => this.context,
|
||||
)
|
||||
this.cleanups.push(cleanup)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Stops all reactive subscriptions.
|
||||
*/
|
||||
stop(): void {
|
||||
this.started = false
|
||||
for (const cleanup of this.cleanups) {
|
||||
cleanup()
|
||||
}
|
||||
this.cleanups = []
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the current accumulated context.
|
||||
*/
|
||||
currentContext(): Context {
|
||||
return this.context
|
||||
}
|
||||
|
||||
private ensureGraph(): SourceGraph {
|
||||
if (!this.graph) {
|
||||
this.graph = buildGraph(Array.from(this.sources.values()))
|
||||
}
|
||||
return this.graph
|
||||
}
|
||||
|
||||
private handleContextUpdate(sourceId: string, update: Partial<Context>): void {
|
||||
this.context = { ...this.context, ...update, time: new Date() }
|
||||
|
||||
// Re-run dependents and notify
|
||||
this.refreshDependents(sourceId)
|
||||
}
|
||||
|
||||
private async refreshDependents(sourceId: string): Promise<void> {
|
||||
const graph = this.ensureGraph()
|
||||
const toRefresh = this.collectDependents(sourceId, graph)
|
||||
|
||||
// Re-run fetchContext for dependents in order
|
||||
for (const id of toRefresh) {
|
||||
const source = graph.sources.get(id)
|
||||
if (source?.fetchContext) {
|
||||
try {
|
||||
const update = await source.fetchContext(this.context)
|
||||
this.context = { ...this.context, ...update }
|
||||
} catch {
|
||||
// Errors during reactive updates are logged but don't stop propagation
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Collect items from all sources
|
||||
const items: FeedItem[] = []
|
||||
const errors: SourceError[] = []
|
||||
|
||||
for (const source of graph.sorted) {
|
||||
if (source.fetchItems) {
|
||||
try {
|
||||
const sourceItems = await source.fetchItems(this.context)
|
||||
items.push(...sourceItems)
|
||||
} catch (err) {
|
||||
errors.push({
|
||||
sourceId: source.id,
|
||||
error: err instanceof Error ? err : new Error(String(err)),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
items.sort((a, b) => b.priority - a.priority)
|
||||
|
||||
this.notifySubscribers({ context: this.context, items: items as TItems[], errors })
|
||||
}
|
||||
|
||||
private collectDependents(sourceId: string, graph: SourceGraph): string[] {
|
||||
const result: string[] = []
|
||||
const visited = new Set<string>()
|
||||
|
||||
const collect = (id: string): void => {
|
||||
const deps = graph.dependents.get(id) ?? []
|
||||
for (const dep of deps) {
|
||||
if (!visited.has(dep)) {
|
||||
visited.add(dep)
|
||||
result.push(dep)
|
||||
collect(dep)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
collect(sourceId)
|
||||
|
||||
// Return in topological order
|
||||
return graph.sorted.filter((s) => result.includes(s.id)).map((s) => s.id)
|
||||
}
|
||||
|
||||
private scheduleRefresh(): void {
|
||||
// Simple immediate refresh for now - could add debouncing later
|
||||
this.refresh().then((result) => {
|
||||
this.notifySubscribers(result)
|
||||
})
|
||||
}
|
||||
|
||||
private notifySubscribers(result: FeedResult<TItems>): void {
|
||||
this.subscribers.forEach((callback) => {
|
||||
try {
|
||||
callback(result)
|
||||
} catch {
|
||||
// Subscriber errors shouldn't break other subscribers
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
function buildGraph(sources: FeedSource[]): SourceGraph {
|
||||
const byId = new Map<string, FeedSource>()
|
||||
for (const source of sources) {
|
||||
byId.set(source.id, source)
|
||||
}
|
||||
|
||||
// Validate dependencies exist
|
||||
for (const source of sources) {
|
||||
for (const dep of source.dependencies ?? []) {
|
||||
if (!byId.has(dep)) {
|
||||
throw new Error(`Source "${source.id}" depends on "${dep}" which is not registered`)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Check for cycles and topologically sort
|
||||
const visited = new Set<string>()
|
||||
const visiting = new Set<string>()
|
||||
const sorted: FeedSource[] = []
|
||||
|
||||
function visit(id: string, path: string[]): void {
|
||||
if (visiting.has(id)) {
|
||||
const cycle = [...path.slice(path.indexOf(id)), id].join(" → ")
|
||||
throw new Error(`Circular dependency detected: ${cycle}`)
|
||||
}
|
||||
if (visited.has(id)) return
|
||||
|
||||
visiting.add(id)
|
||||
const source = byId.get(id)!
|
||||
for (const dep of source.dependencies ?? []) {
|
||||
visit(dep, [...path, id])
|
||||
}
|
||||
visiting.delete(id)
|
||||
visited.add(id)
|
||||
sorted.push(source)
|
||||
}
|
||||
|
||||
for (const source of sources) {
|
||||
visit(source.id, [])
|
||||
}
|
||||
|
||||
// Build reverse dependency map
|
||||
const dependents = new Map<string, string[]>()
|
||||
for (const source of sources) {
|
||||
for (const dep of source.dependencies ?? []) {
|
||||
const list = dependents.get(dep) ?? []
|
||||
list.push(source.id)
|
||||
dependents.set(dep, list)
|
||||
}
|
||||
}
|
||||
|
||||
return { sources: byId, sorted, dependents }
|
||||
}
|
||||
422
packages/aris-core/src/feed-source.test.ts
Normal file
422
packages/aris-core/src/feed-source.test.ts
Normal file
@@ -0,0 +1,422 @@
|
||||
import { describe, expect, test } from "bun:test"
|
||||
|
||||
import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
|
||||
|
||||
import { contextKey, contextValue } from "./index"
|
||||
|
||||
// =============================================================================
|
||||
// CONTEXT KEYS
|
||||
// =============================================================================
|
||||
|
||||
interface Location {
|
||||
lat: number
|
||||
lng: number
|
||||
}
|
||||
|
||||
interface Weather {
|
||||
temperature: number
|
||||
condition: string
|
||||
}
|
||||
|
||||
const LocationKey: ContextKey<Location> = contextKey("location")
|
||||
const WeatherKey: ContextKey<Weather> = contextKey("weather")
|
||||
|
||||
// =============================================================================
|
||||
// FEED ITEMS
|
||||
// =============================================================================
|
||||
|
||||
type WeatherFeedItem = FeedItem<"weather", { temperature: number; condition: string }>
|
||||
type AlertFeedItem = FeedItem<"alert", { message: string }>
|
||||
|
||||
// =============================================================================
|
||||
// TEST HELPERS
|
||||
// =============================================================================
|
||||
|
||||
interface SimulatedLocationSource extends FeedSource {
|
||||
simulateUpdate(location: Location): void
|
||||
}
|
||||
|
||||
function createLocationSource(): SimulatedLocationSource {
|
||||
let callback: ((update: Partial<Context>) => void) | null = null
|
||||
let currentLocation: Location = { lat: 0, lng: 0 }
|
||||
|
||||
return {
|
||||
id: "location",
|
||||
|
||||
onContextUpdate(cb) {
|
||||
callback = cb
|
||||
return () => {
|
||||
callback = null
|
||||
}
|
||||
},
|
||||
|
||||
async fetchContext() {
|
||||
return { [LocationKey]: currentLocation }
|
||||
},
|
||||
|
||||
simulateUpdate(location: Location) {
|
||||
currentLocation = location
|
||||
callback?.({ [LocationKey]: location })
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createWeatherSource(
|
||||
fetchWeather: (location: Location) => Promise<Weather> = async () => ({
|
||||
temperature: 20,
|
||||
condition: "sunny",
|
||||
}),
|
||||
): FeedSource<WeatherFeedItem> {
|
||||
return {
|
||||
id: "weather",
|
||||
dependencies: ["location"],
|
||||
|
||||
async fetchContext(context) {
|
||||
const location = contextValue(context, LocationKey)
|
||||
if (!location) return {}
|
||||
|
||||
const weather = await fetchWeather(location)
|
||||
return { [WeatherKey]: weather }
|
||||
},
|
||||
|
||||
async fetchItems(context) {
|
||||
const weather = contextValue(context, WeatherKey)
|
||||
if (!weather) return []
|
||||
|
||||
return [
|
||||
{
|
||||
id: `weather-${Date.now()}`,
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: {
|
||||
temperature: weather.temperature,
|
||||
condition: weather.condition,
|
||||
},
|
||||
},
|
||||
]
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createAlertSource(): FeedSource<AlertFeedItem> {
|
||||
return {
|
||||
id: "alert",
|
||||
dependencies: ["weather"],
|
||||
|
||||
async fetchItems(context) {
|
||||
const weather = contextValue(context, WeatherKey)
|
||||
if (!weather) return []
|
||||
|
||||
if (weather.condition === "storm") {
|
||||
return [
|
||||
{
|
||||
id: "alert-storm",
|
||||
type: "alert",
|
||||
priority: 1.0,
|
||||
timestamp: new Date(),
|
||||
data: { message: "Storm warning!" },
|
||||
},
|
||||
]
|
||||
}
|
||||
|
||||
return []
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// GRAPH SIMULATION (until FeedController is updated)
|
||||
// =============================================================================
|
||||
|
||||
interface SourceGraph {
|
||||
sources: Map<string, FeedSource>
|
||||
sorted: FeedSource[]
|
||||
dependents: Map<string, string[]>
|
||||
}
|
||||
|
||||
function buildGraph(sources: FeedSource[]): SourceGraph {
|
||||
const byId = new Map<string, FeedSource>()
|
||||
for (const source of sources) {
|
||||
byId.set(source.id, source)
|
||||
}
|
||||
|
||||
// Validate dependencies exist
|
||||
for (const source of sources) {
|
||||
for (const dep of source.dependencies ?? []) {
|
||||
if (!byId.has(dep)) {
|
||||
throw new Error(`Source "${source.id}" depends on "${dep}" which is not registered`)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Check for cycles and topologically sort
|
||||
const visited = new Set<string>()
|
||||
const visiting = new Set<string>()
|
||||
const sorted: FeedSource[] = []
|
||||
|
||||
function visit(id: string, path: string[]): void {
|
||||
if (visiting.has(id)) {
|
||||
const cycle = [...path.slice(path.indexOf(id)), id].join(" → ")
|
||||
throw new Error(`Circular dependency detected: ${cycle}`)
|
||||
}
|
||||
if (visited.has(id)) return
|
||||
|
||||
visiting.add(id)
|
||||
const source = byId.get(id)!
|
||||
for (const dep of source.dependencies ?? []) {
|
||||
visit(dep, [...path, id])
|
||||
}
|
||||
visiting.delete(id)
|
||||
visited.add(id)
|
||||
sorted.push(source)
|
||||
}
|
||||
|
||||
for (const source of sources) {
|
||||
visit(source.id, [])
|
||||
}
|
||||
|
||||
// Build reverse dependency map
|
||||
const dependents = new Map<string, string[]>()
|
||||
for (const source of sources) {
|
||||
for (const dep of source.dependencies ?? []) {
|
||||
const list = dependents.get(dep) ?? []
|
||||
list.push(source.id)
|
||||
dependents.set(dep, list)
|
||||
}
|
||||
}
|
||||
|
||||
return { sources: byId, sorted, dependents }
|
||||
}
|
||||
|
||||
async function refreshGraph(graph: SourceGraph): Promise<{ context: Context; items: FeedItem[] }> {
|
||||
let context: Context = { time: new Date() }
|
||||
|
||||
// Run fetchContext in topological order
|
||||
for (const source of graph.sorted) {
|
||||
if (source.fetchContext) {
|
||||
const update = await source.fetchContext(context)
|
||||
context = { ...context, ...update }
|
||||
}
|
||||
}
|
||||
|
||||
// Run fetchItems on all sources
|
||||
const items: FeedItem[] = []
|
||||
for (const source of graph.sorted) {
|
||||
if (source.fetchItems) {
|
||||
const sourceItems = await source.fetchItems(context)
|
||||
items.push(...sourceItems)
|
||||
}
|
||||
}
|
||||
|
||||
// Sort by priority descending
|
||||
items.sort((a, b) => b.priority - a.priority)
|
||||
|
||||
return { context, items }
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// TESTS
|
||||
// =============================================================================
|
||||
|
||||
describe("FeedSource", () => {
|
||||
describe("interface", () => {
|
||||
test("source with only context production", () => {
|
||||
const source = createLocationSource()
|
||||
|
||||
expect(source.id).toBe("location")
|
||||
expect(source.dependencies).toBeUndefined()
|
||||
expect(source.fetchContext).toBeDefined()
|
||||
expect(source.onContextUpdate).toBeDefined()
|
||||
expect(source.fetchItems).toBeUndefined()
|
||||
})
|
||||
|
||||
test("source with dependencies and both context and items", () => {
|
||||
const source = createWeatherSource()
|
||||
|
||||
expect(source.id).toBe("weather")
|
||||
expect(source.dependencies).toEqual(["location"])
|
||||
expect(source.fetchContext).toBeDefined()
|
||||
expect(source.fetchItems).toBeDefined()
|
||||
})
|
||||
|
||||
test("source with only item production", () => {
|
||||
const source = createAlertSource()
|
||||
|
||||
expect(source.id).toBe("alert")
|
||||
expect(source.dependencies).toEqual(["weather"])
|
||||
expect(source.fetchContext).toBeUndefined()
|
||||
expect(source.fetchItems).toBeDefined()
|
||||
})
|
||||
})
|
||||
|
||||
describe("graph validation", () => {
|
||||
test("validates all dependencies exist", () => {
|
||||
const orphan: FeedSource = {
|
||||
id: "orphan",
|
||||
dependencies: ["nonexistent"],
|
||||
}
|
||||
|
||||
expect(() => buildGraph([orphan])).toThrow(
|
||||
'Source "orphan" depends on "nonexistent" which is not registered',
|
||||
)
|
||||
})
|
||||
|
||||
test("detects circular dependencies", () => {
|
||||
const a: FeedSource = { id: "a", dependencies: ["b"] }
|
||||
const b: FeedSource = { id: "b", dependencies: ["a"] }
|
||||
|
||||
expect(() => buildGraph([a, b])).toThrow("Circular dependency detected: a → b → a")
|
||||
})
|
||||
|
||||
test("detects longer cycles", () => {
|
||||
const a: FeedSource = { id: "a", dependencies: ["c"] }
|
||||
const b: FeedSource = { id: "b", dependencies: ["a"] }
|
||||
const c: FeedSource = { id: "c", dependencies: ["b"] }
|
||||
|
||||
expect(() => buildGraph([a, b, c])).toThrow("Circular dependency detected")
|
||||
})
|
||||
|
||||
test("topologically sorts sources", () => {
|
||||
const location = createLocationSource()
|
||||
const weather = createWeatherSource()
|
||||
const alert = createAlertSource()
|
||||
|
||||
// Register in wrong order
|
||||
const graph = buildGraph([alert, weather, location])
|
||||
|
||||
expect(graph.sorted.map((s) => s.id)).toEqual(["location", "weather", "alert"])
|
||||
})
|
||||
|
||||
test("builds reverse dependency map", () => {
|
||||
const location = createLocationSource()
|
||||
const weather = createWeatherSource()
|
||||
const alert = createAlertSource()
|
||||
|
||||
const graph = buildGraph([location, weather, alert])
|
||||
|
||||
expect(graph.dependents.get("location")).toEqual(["weather"])
|
||||
expect(graph.dependents.get("weather")).toEqual(["alert"])
|
||||
expect(graph.dependents.get("alert")).toBeUndefined()
|
||||
})
|
||||
})
|
||||
|
||||
describe("graph refresh", () => {
|
||||
test("runs fetchContext in dependency order", async () => {
|
||||
const order: string[] = []
|
||||
|
||||
const location: FeedSource = {
|
||||
id: "location",
|
||||
async fetchContext() {
|
||||
order.push("location")
|
||||
return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
|
||||
},
|
||||
}
|
||||
|
||||
const weather: FeedSource = {
|
||||
id: "weather",
|
||||
dependencies: ["location"],
|
||||
async fetchContext(ctx) {
|
||||
order.push("weather")
|
||||
const loc = contextValue(ctx, LocationKey)
|
||||
expect(loc).toBeDefined()
|
||||
return { [WeatherKey]: { temperature: 20, condition: "sunny" } }
|
||||
},
|
||||
}
|
||||
|
||||
const graph = buildGraph([weather, location])
|
||||
await refreshGraph(graph)
|
||||
|
||||
expect(order).toEqual(["location", "weather"])
|
||||
})
|
||||
|
||||
test("accumulates context across sources", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const graph = buildGraph([location, weather])
|
||||
const { context } = await refreshGraph(graph)
|
||||
|
||||
expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
|
||||
expect(contextValue(context, WeatherKey)).toEqual({ temperature: 20, condition: "sunny" })
|
||||
})
|
||||
|
||||
test("collects items from all sources", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const graph = buildGraph([location, weather])
|
||||
const { items } = await refreshGraph(graph)
|
||||
|
||||
expect(items).toHaveLength(1)
|
||||
expect(items[0]!.type).toBe("weather")
|
||||
})
|
||||
|
||||
test("downstream source receives upstream context", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const weather = createWeatherSource(async () => ({
|
||||
temperature: 15,
|
||||
condition: "storm",
|
||||
}))
|
||||
|
||||
const alert = createAlertSource()
|
||||
|
||||
const graph = buildGraph([location, weather, alert])
|
||||
const { items } = await refreshGraph(graph)
|
||||
|
||||
expect(items).toHaveLength(2)
|
||||
expect(items[0]!.type).toBe("alert") // priority 1.0
|
||||
expect(items[1]!.type).toBe("weather") // priority 0.5
|
||||
})
|
||||
|
||||
test("source without location context returns empty items", async () => {
|
||||
// Location source exists but hasn't been updated (returns default 0,0)
|
||||
const location: FeedSource = {
|
||||
id: "location",
|
||||
async fetchContext() {
|
||||
// Simulate no location available
|
||||
return {}
|
||||
},
|
||||
}
|
||||
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const graph = buildGraph([location, weather])
|
||||
const { context, items } = await refreshGraph(graph)
|
||||
|
||||
expect(contextValue(context, WeatherKey)).toBeUndefined()
|
||||
expect(items).toHaveLength(0)
|
||||
})
|
||||
})
|
||||
|
||||
describe("reactive updates", () => {
|
||||
test("onContextUpdate receives callback and returns cleanup", () => {
|
||||
const location = createLocationSource()
|
||||
let updateCount = 0
|
||||
|
||||
const cleanup = location.onContextUpdate!(
|
||||
() => {
|
||||
updateCount++
|
||||
},
|
||||
() => ({ time: new Date() }),
|
||||
)
|
||||
|
||||
location.simulateUpdate({ lat: 1, lng: 1 })
|
||||
expect(updateCount).toBe(1)
|
||||
|
||||
location.simulateUpdate({ lat: 2, lng: 2 })
|
||||
expect(updateCount).toBe(2)
|
||||
|
||||
cleanup()
|
||||
|
||||
location.simulateUpdate({ lat: 3, lng: 3 })
|
||||
expect(updateCount).toBe(2) // no more updates after cleanup
|
||||
})
|
||||
})
|
||||
})
|
||||
76
packages/aris-core/src/feed-source.ts
Normal file
76
packages/aris-core/src/feed-source.ts
Normal file
@@ -0,0 +1,76 @@
|
||||
import type { Context } from "./context"
|
||||
import type { FeedItem } from "./feed"
|
||||
|
||||
/**
|
||||
* Unified interface for sources that provide context and/or feed items.
|
||||
*
|
||||
* Sources form a dependency graph - a source declares which other sources
|
||||
* it depends on, and the graph ensures dependencies are resolved before
|
||||
* dependents run.
|
||||
*
|
||||
* A source may:
|
||||
* - Provide context for other sources (implement fetchContext/onContextUpdate)
|
||||
* - Produce feed items (implement fetchItems/onItemsUpdate)
|
||||
* - Both
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // Location source - provides context only
|
||||
* const locationSource: FeedSource = {
|
||||
* id: "location",
|
||||
* fetchContext: async () => {
|
||||
* const pos = await getCurrentPosition()
|
||||
* return { location: { lat: pos.coords.latitude, lng: pos.coords.longitude } }
|
||||
* },
|
||||
* }
|
||||
*
|
||||
* // Weather source - depends on location, provides both context and items
|
||||
* const weatherSource: FeedSource<WeatherFeedItem> = {
|
||||
* id: "weather",
|
||||
* dependencies: ["location"],
|
||||
* fetchContext: async (ctx) => {
|
||||
* const weather = await fetchWeather(ctx.location)
|
||||
* return { weather }
|
||||
* },
|
||||
* fetchItems: async (ctx) => {
|
||||
* return createWeatherFeedItems(ctx.weather)
|
||||
* },
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export interface FeedSource<TItem extends FeedItem = FeedItem> {
|
||||
/** Unique identifier for this source */
|
||||
readonly id: string
|
||||
|
||||
/** IDs of sources this source depends on */
|
||||
readonly dependencies?: readonly string[]
|
||||
|
||||
/**
|
||||
* Subscribe to reactive context updates.
|
||||
* Called when the source can push context changes proactively.
|
||||
* Returns cleanup function.
|
||||
*/
|
||||
onContextUpdate?(
|
||||
callback: (update: Partial<Context>) => void,
|
||||
getContext: () => Context,
|
||||
): () => void
|
||||
|
||||
/**
|
||||
* Fetch context on-demand.
|
||||
* Called during manual refresh or initial load.
|
||||
*/
|
||||
fetchContext?(context: Context): Promise<Partial<Context>>
|
||||
|
||||
/**
|
||||
* Subscribe to reactive feed item updates.
|
||||
* Called when the source can push item changes proactively.
|
||||
* Returns cleanup function.
|
||||
*/
|
||||
onItemsUpdate?(callback: (items: TItem[]) => void, getContext: () => Context): () => void
|
||||
|
||||
/**
|
||||
* Fetch feed items on-demand.
|
||||
* Called during manual refresh or when dependencies update.
|
||||
*/
|
||||
fetchItems?(context: Context): Promise<TItem[]>
|
||||
}
|
||||
31
packages/aris-core/src/feed.ts
Normal file
31
packages/aris-core/src/feed.ts
Normal file
@@ -0,0 +1,31 @@
|
||||
/**
|
||||
* A single item in the feed.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* type WeatherItem = FeedItem<"weather", { temp: number; condition: string }>
|
||||
*
|
||||
* const item: WeatherItem = {
|
||||
* id: "weather-123",
|
||||
* type: "weather",
|
||||
* priority: 0.5,
|
||||
* timestamp: new Date(),
|
||||
* data: { temp: 18, condition: "cloudy" },
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export interface FeedItem<
|
||||
TType extends string = string,
|
||||
TData extends Record<string, unknown> = Record<string, unknown>,
|
||||
> {
|
||||
/** Unique identifier */
|
||||
id: string
|
||||
/** Item type, matches the data source type */
|
||||
type: TType
|
||||
/** Sort priority (higher = more important, shown first) */
|
||||
priority: number
|
||||
/** When this item was generated */
|
||||
timestamp: Date
|
||||
/** Type-specific payload */
|
||||
data: TData
|
||||
}
|
||||
42
packages/aris-core/src/index.ts
Normal file
42
packages/aris-core/src/index.ts
Normal file
@@ -0,0 +1,42 @@
|
||||
// Context
|
||||
export type { Context, ContextKey } from "./context"
|
||||
export { contextKey, contextValue } from "./context"
|
||||
|
||||
// Feed
|
||||
export type { FeedItem } from "./feed"
|
||||
|
||||
// Feed Source
|
||||
export type { FeedSource } from "./feed-source"
|
||||
|
||||
// Feed Engine
|
||||
export type { FeedResult, FeedSubscriber, SourceError } from "./feed-engine"
|
||||
export { FeedEngine } from "./feed-engine"
|
||||
|
||||
// =============================================================================
|
||||
// DEPRECATED - Use FeedSource + FeedEngine instead
|
||||
// =============================================================================
|
||||
|
||||
// Data Source (deprecated - use FeedSource)
|
||||
export type { DataSource } from "./data-source"
|
||||
|
||||
// Context Provider (deprecated - use FeedSource)
|
||||
export type { ContextProvider } from "./context-provider"
|
||||
|
||||
// Context Bridge (deprecated - use FeedEngine)
|
||||
export type { ProviderError, RefreshResult } from "./context-bridge"
|
||||
export { ContextBridge } from "./context-bridge"
|
||||
|
||||
// Reconciler (deprecated - use FeedEngine)
|
||||
export type {
|
||||
ReconcileResult,
|
||||
ReconcilerConfig,
|
||||
SourceError as ReconcilerSourceError,
|
||||
} from "./reconciler"
|
||||
export { Reconciler } from "./reconciler"
|
||||
|
||||
// Feed Controller (deprecated - use FeedEngine)
|
||||
export type {
|
||||
FeedControllerConfig,
|
||||
FeedSubscriber as FeedControllerSubscriber,
|
||||
} from "./feed-controller"
|
||||
export { FeedController } from "./feed-controller"
|
||||
@@ -1,5 +1,5 @@
|
||||
import type { Context, DataSource } from "@aris/core"
|
||||
import { TflApi, type ITflApi } from "./tfl-api.ts"
|
||||
|
||||
import type {
|
||||
StationLocation,
|
||||
TflAlertData,
|
||||
@@ -10,6 +10,8 @@ import type {
|
||||
TflLineId,
|
||||
} from "./types.ts"
|
||||
|
||||
import { TflApi, type ITflApi } from "./tfl-api.ts"
|
||||
|
||||
const SEVERITY_PRIORITY: Record<TflAlertSeverity, number> = {
|
||||
closure: 100,
|
||||
"major-delays": 80,
|
||||
@@ -22,7 +24,10 @@ function haversineDistance(lat1: number, lng1: number, lat2: number, lng2: numbe
|
||||
const dLng = ((lng2 - lng1) * Math.PI) / 180
|
||||
const a =
|
||||
Math.sin(dLat / 2) * Math.sin(dLat / 2) +
|
||||
Math.cos((lat1 * Math.PI) / 180) * Math.cos((lat2 * Math.PI) / 180) * Math.sin(dLng / 2) * Math.sin(dLng / 2)
|
||||
Math.cos((lat1 * Math.PI) / 180) *
|
||||
Math.cos((lat2 * Math.PI) / 180) *
|
||||
Math.sin(dLng / 2) *
|
||||
Math.sin(dLng / 2)
|
||||
const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
|
||||
return R * c
|
||||
}
|
||||
@@ -62,13 +67,20 @@ export class TflDataSource implements DataSource<TflAlertFeedItem, TflDataSource
|
||||
}
|
||||
|
||||
async query(context: Context, config: TflDataSourceConfig): Promise<TflAlertFeedItem[]> {
|
||||
const [statuses, stations] = await Promise.all([this.api.fetchLineStatuses(config.lines), this.api.fetchStations()])
|
||||
const [statuses, stations] = await Promise.all([
|
||||
this.api.fetchLineStatuses(config.lines),
|
||||
this.api.fetchStations(),
|
||||
])
|
||||
|
||||
const items: TflAlertFeedItem[] = statuses.map((status) => {
|
||||
const closestStationDistance =
|
||||
context.location ?
|
||||
findClosestStationDistance(status.lineId, stations, context.location.lat, context.location.lng)
|
||||
: null
|
||||
const closestStationDistance = context.location
|
||||
? findClosestStationDistance(
|
||||
status.lineId,
|
||||
stations,
|
||||
context.location.lat,
|
||||
context.location.lng,
|
||||
)
|
||||
: null
|
||||
|
||||
const data: TflAlertData = {
|
||||
line: status.lineId,
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
import type { Context } from "@aris/core"
|
||||
|
||||
import { describe, expect, test } from "bun:test"
|
||||
|
||||
import type { Context } from "@aris/core"
|
||||
import { TflDataSource } from "./data-source.ts"
|
||||
import type { ITflApi, TflLineStatus } from "./tfl-api.ts"
|
||||
import type { StationLocation, TflLineId } from "./types.ts"
|
||||
|
||||
import fixtures from "../fixtures/tfl-responses.json"
|
||||
import { TflDataSource } from "./data-source.ts"
|
||||
|
||||
// Mock API that returns fixture data
|
||||
class FixtureTflApi implements ITflApi {
|
||||
@@ -109,9 +110,10 @@ describe("TfL Feed Items (using fixture data)", () => {
|
||||
expect(typeof item.data.lineName).toBe("string")
|
||||
expect(["minor-delays", "major-delays", "closure"]).toContain(item.data.severity)
|
||||
expect(typeof item.data.description).toBe("string")
|
||||
expect(item.data.closestStationDistance === null || typeof item.data.closestStationDistance === "number").toBe(
|
||||
true,
|
||||
)
|
||||
expect(
|
||||
item.data.closestStationDistance === null ||
|
||||
typeof item.data.closestStationDistance === "number",
|
||||
).toBe(true)
|
||||
}
|
||||
})
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { type } from "arktype"
|
||||
|
||||
import type { StationLocation, TflAlertSeverity } from "./types.ts"
|
||||
|
||||
const TFL_API_BASE = "https://api.tfl.gov.uk"
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import type { FeedItem } from "@aris/core"
|
||||
|
||||
import type { TflLineId } from "./tfl-api.ts"
|
||||
|
||||
export type { TflLineId } from "./tfl-api.ts"
|
||||
|
||||
112
packages/aris-source-location/README.md
Normal file
112
packages/aris-source-location/README.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# @aris/source-location
|
||||
|
||||
A FeedSource that provides location context to the ARIS feed graph.
|
||||
|
||||
## Overview
|
||||
|
||||
This source accepts external location pushes and does not query location itself. It provides location context to downstream sources (e.g., weather, transit) but does not produce feed items.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
bun add @aris/source-location
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```ts
|
||||
import { LocationSource, LocationKey, type Location } from "@aris/source-location"
|
||||
import { contextValue } from "@aris/core"
|
||||
|
||||
// Create source with default history size (1)
|
||||
const locationSource = new LocationSource()
|
||||
|
||||
// Or keep last 10 locations
|
||||
const locationSource = new LocationSource({ historySize: 10 })
|
||||
|
||||
// Push location from external provider (GPS, network, etc.)
|
||||
locationSource.pushLocation({
|
||||
lat: 37.7749,
|
||||
lng: -122.4194,
|
||||
accuracy: 10,
|
||||
timestamp: new Date(),
|
||||
})
|
||||
|
||||
// Access current location
|
||||
locationSource.lastLocation // { lat, lng, accuracy, timestamp } | null
|
||||
|
||||
// Access location history (oldest first)
|
||||
locationSource.locationHistory // readonly Location[]
|
||||
```
|
||||
|
||||
### With FeedController
|
||||
|
||||
```ts
|
||||
import { FeedController } from "@aris/core"
|
||||
import { LocationSource } from "@aris/source-location"
|
||||
|
||||
const locationSource = new LocationSource()
|
||||
|
||||
const controller = new FeedController({
|
||||
sources: [locationSource, weatherSource, transitSource],
|
||||
})
|
||||
|
||||
// Push location updates - downstream sources will re-fetch
|
||||
locationSource.pushLocation({
|
||||
lat: 37.7749,
|
||||
lng: -122.4194,
|
||||
accuracy: 10,
|
||||
timestamp: new Date(),
|
||||
})
|
||||
```
|
||||
|
||||
### Reading Location in Downstream Sources
|
||||
|
||||
```ts
|
||||
import { contextValue, type FeedSource } from "@aris/core"
|
||||
import { LocationKey } from "@aris/source-location"
|
||||
|
||||
const weatherSource: FeedSource = {
|
||||
id: "weather",
|
||||
dependencies: ["location"],
|
||||
|
||||
async fetchContext(context) {
|
||||
const location = contextValue(context, LocationKey)
|
||||
if (!location) return {}
|
||||
|
||||
const weather = await fetchWeather(location.lat, location.lng)
|
||||
return { [WeatherKey]: weather }
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### `LocationSource`
|
||||
|
||||
| Member | Type | Description |
|
||||
| ------------------------ | --------------------- | ------------------------------------- |
|
||||
| `id` | `"location"` | Source identifier |
|
||||
| `constructor(options?)` | | Create with optional `historySize` |
|
||||
| `pushLocation(location)` | `void` | Push new location, notifies listeners |
|
||||
| `lastLocation` | `Location \| null` | Most recent location |
|
||||
| `locationHistory` | `readonly Location[]` | All retained locations, oldest first |
|
||||
|
||||
### `Location`
|
||||
|
||||
```ts
|
||||
interface Location {
|
||||
lat: number
|
||||
lng: number
|
||||
accuracy: number // meters
|
||||
timestamp: Date
|
||||
}
|
||||
```
|
||||
|
||||
### `LocationKey`
|
||||
|
||||
Typed context key for accessing location in downstream sources:
|
||||
|
||||
```ts
|
||||
const location = contextValue(context, LocationKey)
|
||||
```
|
||||
13
packages/aris-source-location/package.json
Normal file
13
packages/aris-source-location/package.json
Normal file
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"name": "@aris/source-location",
|
||||
"version": "0.0.0",
|
||||
"type": "module",
|
||||
"main": "src/index.ts",
|
||||
"types": "src/index.ts",
|
||||
"scripts": {
|
||||
"test": "bun test src/"
|
||||
},
|
||||
"dependencies": {
|
||||
"@aris/core": "workspace:*"
|
||||
}
|
||||
}
|
||||
6
packages/aris-source-location/src/index.ts
Normal file
6
packages/aris-source-location/src/index.ts
Normal file
@@ -0,0 +1,6 @@
|
||||
export {
|
||||
LocationSource,
|
||||
LocationKey,
|
||||
type Location,
|
||||
type LocationSourceOptions,
|
||||
} from "./location-source.ts"
|
||||
150
packages/aris-source-location/src/location-source.test.ts
Normal file
150
packages/aris-source-location/src/location-source.test.ts
Normal file
@@ -0,0 +1,150 @@
|
||||
import { describe, expect, mock, test } from "bun:test"
|
||||
|
||||
import { LocationKey, LocationSource, type Location } from "./location-source.ts"
|
||||
|
||||
function createLocation(overrides: Partial<Location> = {}): Location {
|
||||
return {
|
||||
lat: 37.7749,
|
||||
lng: -122.4194,
|
||||
accuracy: 10,
|
||||
timestamp: new Date(),
|
||||
...overrides,
|
||||
}
|
||||
}
|
||||
|
||||
describe("LocationSource", () => {
|
||||
describe("FeedSource interface", () => {
|
||||
test("has correct id", () => {
|
||||
const source = new LocationSource()
|
||||
expect(source.id).toBe("location")
|
||||
})
|
||||
|
||||
test("fetchItems always returns empty array", async () => {
|
||||
const source = new LocationSource()
|
||||
source.pushLocation(createLocation())
|
||||
|
||||
const items = await source.fetchItems()
|
||||
expect(items).toEqual([])
|
||||
})
|
||||
|
||||
test("fetchContext returns empty when no location", async () => {
|
||||
const source = new LocationSource()
|
||||
|
||||
const context = await source.fetchContext()
|
||||
expect(context).toEqual({})
|
||||
})
|
||||
|
||||
test("fetchContext returns location when available", async () => {
|
||||
const source = new LocationSource()
|
||||
const location = createLocation()
|
||||
source.pushLocation(location)
|
||||
|
||||
const context = await source.fetchContext()
|
||||
expect(context).toEqual({ [LocationKey]: location })
|
||||
})
|
||||
})
|
||||
|
||||
describe("pushLocation", () => {
|
||||
test("updates lastLocation", () => {
|
||||
const source = new LocationSource()
|
||||
expect(source.lastLocation).toBeNull()
|
||||
|
||||
const location = createLocation()
|
||||
source.pushLocation(location)
|
||||
|
||||
expect(source.lastLocation).toEqual(location)
|
||||
})
|
||||
|
||||
test("notifies listeners", () => {
|
||||
const source = new LocationSource()
|
||||
const listener = mock()
|
||||
|
||||
source.onContextUpdate(listener)
|
||||
|
||||
const location = createLocation()
|
||||
source.pushLocation(location)
|
||||
|
||||
expect(listener).toHaveBeenCalledTimes(1)
|
||||
expect(listener).toHaveBeenCalledWith({ [LocationKey]: location })
|
||||
})
|
||||
})
|
||||
|
||||
describe("history", () => {
|
||||
test("default historySize is 1", () => {
|
||||
const source = new LocationSource()
|
||||
|
||||
source.pushLocation(createLocation({ lat: 1 }))
|
||||
source.pushLocation(createLocation({ lat: 2 }))
|
||||
|
||||
expect(source.locationHistory).toHaveLength(1)
|
||||
expect(source.lastLocation?.lat).toBe(2)
|
||||
})
|
||||
|
||||
test("respects configured historySize", () => {
|
||||
const source = new LocationSource({ historySize: 3 })
|
||||
|
||||
const loc1 = createLocation({ lat: 1 })
|
||||
const loc2 = createLocation({ lat: 2 })
|
||||
const loc3 = createLocation({ lat: 3 })
|
||||
|
||||
source.pushLocation(loc1)
|
||||
source.pushLocation(loc2)
|
||||
source.pushLocation(loc3)
|
||||
|
||||
expect(source.locationHistory).toEqual([loc1, loc2, loc3])
|
||||
})
|
||||
|
||||
test("evicts oldest when exceeding historySize", () => {
|
||||
const source = new LocationSource({ historySize: 2 })
|
||||
|
||||
const loc1 = createLocation({ lat: 1 })
|
||||
const loc2 = createLocation({ lat: 2 })
|
||||
const loc3 = createLocation({ lat: 3 })
|
||||
|
||||
source.pushLocation(loc1)
|
||||
source.pushLocation(loc2)
|
||||
source.pushLocation(loc3)
|
||||
|
||||
expect(source.locationHistory).toEqual([loc2, loc3])
|
||||
})
|
||||
|
||||
test("locationHistory is readonly", () => {
|
||||
const source = new LocationSource({ historySize: 3 })
|
||||
source.pushLocation(createLocation())
|
||||
|
||||
const history = source.locationHistory
|
||||
expect(Array.isArray(history)).toBe(true)
|
||||
})
|
||||
})
|
||||
|
||||
describe("onContextUpdate", () => {
|
||||
test("returns cleanup function", () => {
|
||||
const source = new LocationSource()
|
||||
const listener = mock()
|
||||
|
||||
const cleanup = source.onContextUpdate(listener)
|
||||
|
||||
source.pushLocation(createLocation({ lat: 1 }))
|
||||
expect(listener).toHaveBeenCalledTimes(1)
|
||||
|
||||
cleanup()
|
||||
|
||||
source.pushLocation(createLocation({ lat: 2 }))
|
||||
expect(listener).toHaveBeenCalledTimes(1)
|
||||
})
|
||||
|
||||
test("supports multiple listeners", () => {
|
||||
const source = new LocationSource()
|
||||
const listener1 = mock()
|
||||
const listener2 = mock()
|
||||
|
||||
source.onContextUpdate(listener1)
|
||||
source.onContextUpdate(listener2)
|
||||
|
||||
source.pushLocation(createLocation())
|
||||
|
||||
expect(listener1).toHaveBeenCalledTimes(1)
|
||||
expect(listener2).toHaveBeenCalledTimes(1)
|
||||
})
|
||||
})
|
||||
})
|
||||
86
packages/aris-source-location/src/location-source.ts
Normal file
86
packages/aris-source-location/src/location-source.ts
Normal file
@@ -0,0 +1,86 @@
|
||||
import type { Context, FeedSource } from "@aris/core"
|
||||
|
||||
import { contextKey, type ContextKey } from "@aris/core"
|
||||
|
||||
/**
|
||||
* Geographic coordinates with accuracy and timestamp.
|
||||
*/
|
||||
export interface Location {
|
||||
lat: number
|
||||
lng: number
|
||||
/** Accuracy in meters */
|
||||
accuracy: number
|
||||
timestamp: Date
|
||||
}
|
||||
|
||||
export interface LocationSourceOptions {
|
||||
/** Number of locations to retain in history. Defaults to 1. */
|
||||
historySize?: number
|
||||
}
|
||||
|
||||
export const LocationKey: ContextKey<Location> = contextKey("location")
|
||||
|
||||
/**
|
||||
* A FeedSource that provides location context.
|
||||
*
|
||||
* This source accepts external location pushes and does not query location itself.
|
||||
* Use `pushLocation` to update the location from an external provider (e.g., GPS, network).
|
||||
*
|
||||
* Does not produce feed items - always returns empty array from `fetchItems`.
|
||||
*/
|
||||
export class LocationSource implements FeedSource {
|
||||
readonly id = "location"
|
||||
|
||||
private readonly historySize: number
|
||||
private locations: Location[] = []
|
||||
private listeners = new Set<(update: Partial<Context>) => void>()
|
||||
|
||||
constructor(options: LocationSourceOptions = {}) {
|
||||
this.historySize = options.historySize ?? 1
|
||||
}
|
||||
|
||||
/**
|
||||
* Push a new location update. Notifies all context listeners.
|
||||
*/
|
||||
pushLocation(location: Location): void {
|
||||
this.locations.push(location)
|
||||
if (this.locations.length > this.historySize) {
|
||||
this.locations.shift()
|
||||
}
|
||||
this.listeners.forEach((listener) => {
|
||||
listener({ [LocationKey]: location })
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Most recent location, or null if none pushed.
|
||||
*/
|
||||
get lastLocation(): Location | null {
|
||||
return this.locations[this.locations.length - 1] ?? null
|
||||
}
|
||||
|
||||
/**
|
||||
* Location history, oldest first. Length limited by `historySize`.
|
||||
*/
|
||||
get locationHistory(): readonly Location[] {
|
||||
return this.locations
|
||||
}
|
||||
|
||||
onContextUpdate(callback: (update: Partial<Context>) => void): () => void {
|
||||
this.listeners.add(callback)
|
||||
return () => {
|
||||
this.listeners.delete(callback)
|
||||
}
|
||||
}
|
||||
|
||||
async fetchContext(): Promise<Partial<Context>> {
|
||||
if (this.lastLocation) {
|
||||
return { [LocationKey]: this.lastLocation }
|
||||
}
|
||||
return {}
|
||||
}
|
||||
|
||||
async fetchItems(): Promise<[]> {
|
||||
return []
|
||||
}
|
||||
}
|
||||
101
packages/aris-source-weatherkit/README.md
Normal file
101
packages/aris-source-weatherkit/README.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# @aris/source-weatherkit
|
||||
|
||||
Weather feed source using Apple WeatherKit API.
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Setup
|
||||
|
||||
```ts
|
||||
import { WeatherSource, Units } from "@aris/source-weatherkit"
|
||||
|
||||
const weatherSource = new WeatherSource({
|
||||
credentials: {
|
||||
privateKey: process.env.WEATHERKIT_PRIVATE_KEY!,
|
||||
keyId: process.env.WEATHERKIT_KEY_ID!,
|
||||
teamId: process.env.WEATHERKIT_TEAM_ID!,
|
||||
serviceId: process.env.WEATHERKIT_SERVICE_ID!,
|
||||
},
|
||||
units: Units.metric,
|
||||
})
|
||||
```
|
||||
|
||||
### With Feed Source Graph
|
||||
|
||||
```ts
|
||||
import { LocationSource } from "@aris/source-location"
|
||||
import { WeatherSource } from "@aris/source-weatherkit"
|
||||
|
||||
const locationSource = new LocationSource()
|
||||
const weatherSource = new WeatherSource({ credentials })
|
||||
|
||||
// Weather depends on location - graph handles ordering
|
||||
const sources = [locationSource, weatherSource]
|
||||
```
|
||||
|
||||
### Reading Weather Context
|
||||
|
||||
Downstream sources can access weather data:
|
||||
|
||||
```ts
|
||||
import { contextValue } from "@aris/core"
|
||||
import { WeatherKey } from "@aris/source-weatherkit"
|
||||
|
||||
async function fetchContext(context: Context) {
|
||||
const weather = contextValue(context, WeatherKey)
|
||||
|
||||
if (weather?.condition === "Rain") {
|
||||
// Suggest umbrella, indoor activities, etc.
|
||||
}
|
||||
|
||||
if (weather && weather.uvIndex > 7) {
|
||||
// Suggest sunscreen
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Exports
|
||||
|
||||
| Export | Description |
|
||||
| --------------- | --------------------------------------- |
|
||||
| `WeatherSource` | FeedSource implementation |
|
||||
| `WeatherKey` | Context key for simplified weather data |
|
||||
| `Weather` | Type for weather context |
|
||||
| `Units` | `metric` or `imperial` |
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Default | Description |
|
||||
| ------------- | -------- | -------------------------- |
|
||||
| `credentials` | - | WeatherKit API credentials |
|
||||
| `client` | - | Custom WeatherKit client |
|
||||
| `hourlyLimit` | `12` | Max hourly forecasts |
|
||||
| `dailyLimit` | `7` | Max daily forecasts |
|
||||
| `units` | `metric` | Temperature/speed units |
|
||||
|
||||
## Context
|
||||
|
||||
Provides simplified weather context for downstream sources:
|
||||
|
||||
```ts
|
||||
interface Weather {
|
||||
temperature: number
|
||||
temperatureApparent: number
|
||||
condition: ConditionCode
|
||||
humidity: number
|
||||
uvIndex: number
|
||||
windSpeed: number
|
||||
daylight: boolean
|
||||
}
|
||||
```
|
||||
|
||||
## Feed Items
|
||||
|
||||
Produces feed items:
|
||||
|
||||
- `weather-current` - Current conditions
|
||||
- `weather-hourly` - Hourly forecasts (up to `hourlyLimit`)
|
||||
- `weather-daily` - Daily forecasts (up to `dailyLimit`)
|
||||
- `weather-alert` - Weather alerts when present
|
||||
|
||||
Priority is adjusted based on weather severity (storms, extreme temperatures).
|
||||
File diff suppressed because one or more lines are too long
15
packages/aris-source-weatherkit/package.json
Normal file
15
packages/aris-source-weatherkit/package.json
Normal file
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"name": "@aris/source-weatherkit",
|
||||
"version": "0.0.0",
|
||||
"type": "module",
|
||||
"main": "src/index.ts",
|
||||
"types": "src/index.ts",
|
||||
"scripts": {
|
||||
"test": "bun test ."
|
||||
},
|
||||
"dependencies": {
|
||||
"@aris/core": "workspace:*",
|
||||
"@aris/source-location": "workspace:*",
|
||||
"arktype": "^2.1.0"
|
||||
}
|
||||
}
|
||||
97
packages/aris-source-weatherkit/src/feed-items.ts
Normal file
97
packages/aris-source-weatherkit/src/feed-items.ts
Normal file
@@ -0,0 +1,97 @@
|
||||
import type { FeedItem } from "@aris/core"
|
||||
|
||||
import type { Certainty, ConditionCode, PrecipitationType, Severity, Urgency } from "./weatherkit"
|
||||
|
||||
export const WeatherFeedItemType = {
|
||||
current: "weather-current",
|
||||
hourly: "weather-hourly",
|
||||
daily: "weather-daily",
|
||||
alert: "weather-alert",
|
||||
} as const
|
||||
|
||||
export type WeatherFeedItemType = (typeof WeatherFeedItemType)[keyof typeof WeatherFeedItemType]
|
||||
|
||||
export type CurrentWeatherData = {
|
||||
conditionCode: ConditionCode
|
||||
daylight: boolean
|
||||
humidity: number
|
||||
precipitationIntensity: number
|
||||
pressure: number
|
||||
pressureTrend: "rising" | "falling" | "steady"
|
||||
temperature: number
|
||||
temperatureApparent: number
|
||||
uvIndex: number
|
||||
visibility: number
|
||||
windDirection: number
|
||||
windGust: number
|
||||
windSpeed: number
|
||||
}
|
||||
|
||||
export interface CurrentWeatherFeedItem extends FeedItem<
|
||||
typeof WeatherFeedItemType.current,
|
||||
CurrentWeatherData
|
||||
> {}
|
||||
|
||||
export type HourlyWeatherData = {
|
||||
forecastTime: Date
|
||||
conditionCode: ConditionCode
|
||||
daylight: boolean
|
||||
humidity: number
|
||||
precipitationAmount: number
|
||||
precipitationChance: number
|
||||
precipitationType: PrecipitationType
|
||||
temperature: number
|
||||
temperatureApparent: number
|
||||
uvIndex: number
|
||||
windDirection: number
|
||||
windGust: number
|
||||
windSpeed: number
|
||||
}
|
||||
|
||||
export interface HourlyWeatherFeedItem extends FeedItem<
|
||||
typeof WeatherFeedItemType.hourly,
|
||||
HourlyWeatherData
|
||||
> {}
|
||||
|
||||
export type DailyWeatherData = {
|
||||
forecastDate: Date
|
||||
conditionCode: ConditionCode
|
||||
maxUvIndex: number
|
||||
precipitationAmount: number
|
||||
precipitationChance: number
|
||||
precipitationType: PrecipitationType
|
||||
snowfallAmount: number
|
||||
sunrise: Date
|
||||
sunset: Date
|
||||
temperatureMax: number
|
||||
temperatureMin: number
|
||||
}
|
||||
|
||||
export interface DailyWeatherFeedItem extends FeedItem<
|
||||
typeof WeatherFeedItemType.daily,
|
||||
DailyWeatherData
|
||||
> {}
|
||||
|
||||
export type WeatherAlertData = {
|
||||
alertId: string
|
||||
areaName: string
|
||||
certainty: Certainty
|
||||
description: string
|
||||
detailsUrl: string
|
||||
effectiveTime: Date
|
||||
expireTime: Date
|
||||
severity: Severity
|
||||
source: string
|
||||
urgency: Urgency
|
||||
}
|
||||
|
||||
export interface WeatherAlertFeedItem extends FeedItem<
|
||||
typeof WeatherFeedItemType.alert,
|
||||
WeatherAlertData
|
||||
> {}
|
||||
|
||||
export type WeatherFeedItem =
|
||||
| CurrentWeatherFeedItem
|
||||
| HourlyWeatherFeedItem
|
||||
| DailyWeatherFeedItem
|
||||
| WeatherAlertFeedItem
|
||||
39
packages/aris-source-weatherkit/src/index.ts
Normal file
39
packages/aris-source-weatherkit/src/index.ts
Normal file
@@ -0,0 +1,39 @@
|
||||
export { WeatherKey, type Weather } from "./weather-context"
|
||||
export {
|
||||
WeatherSource,
|
||||
Units,
|
||||
type Units as UnitsType,
|
||||
type WeatherSourceOptions,
|
||||
} from "./weather-source"
|
||||
|
||||
export {
|
||||
WeatherFeedItemType,
|
||||
type WeatherFeedItemType as WeatherFeedItemTypeType,
|
||||
type WeatherFeedItem,
|
||||
type CurrentWeatherFeedItem,
|
||||
type CurrentWeatherData,
|
||||
type HourlyWeatherFeedItem,
|
||||
type HourlyWeatherData,
|
||||
type DailyWeatherFeedItem,
|
||||
type DailyWeatherData,
|
||||
type WeatherAlertFeedItem,
|
||||
type WeatherAlertData,
|
||||
} from "./feed-items"
|
||||
|
||||
export {
|
||||
ConditionCode,
|
||||
Severity,
|
||||
Urgency,
|
||||
Certainty,
|
||||
PrecipitationType,
|
||||
DefaultWeatherKitClient,
|
||||
type ConditionCode as ConditionCodeType,
|
||||
type Severity as SeverityType,
|
||||
type Urgency as UrgencyType,
|
||||
type Certainty as CertaintyType,
|
||||
type PrecipitationType as PrecipitationTypeType,
|
||||
type WeatherKitClient,
|
||||
type WeatherKitCredentials,
|
||||
type WeatherKitQueryOptions,
|
||||
type WeatherKitResponse,
|
||||
} from "./weatherkit"
|
||||
27
packages/aris-source-weatherkit/src/weather-context.ts
Normal file
27
packages/aris-source-weatherkit/src/weather-context.ts
Normal file
@@ -0,0 +1,27 @@
|
||||
import type { ContextKey } from "@aris/core"
|
||||
|
||||
import { contextKey } from "@aris/core"
|
||||
|
||||
import type { ConditionCode } from "./weatherkit"
|
||||
|
||||
/**
|
||||
* Simplified weather context for downstream sources.
|
||||
*/
|
||||
export interface Weather {
|
||||
/** Current temperature */
|
||||
temperature: number
|
||||
/** Feels-like temperature */
|
||||
temperatureApparent: number
|
||||
/** Weather condition */
|
||||
condition: ConditionCode
|
||||
/** Relative humidity (0-1) */
|
||||
humidity: number
|
||||
/** UV index */
|
||||
uvIndex: number
|
||||
/** Wind speed */
|
||||
windSpeed: number
|
||||
/** Is it currently daytime */
|
||||
daylight: boolean
|
||||
}
|
||||
|
||||
export const WeatherKey: ContextKey<Weather> = contextKey("weather")
|
||||
182
packages/aris-source-weatherkit/src/weather-source.test.ts
Normal file
182
packages/aris-source-weatherkit/src/weather-source.test.ts
Normal file
@@ -0,0 +1,182 @@
|
||||
import { contextValue, type Context } from "@aris/core"
|
||||
import { LocationKey } from "@aris/source-location"
|
||||
import { describe, expect, test } from "bun:test"
|
||||
|
||||
import type { WeatherKitClient, WeatherKitResponse } from "./weatherkit"
|
||||
|
||||
import fixture from "../fixtures/san-francisco.json"
|
||||
import { WeatherFeedItemType } from "./feed-items"
|
||||
import { WeatherKey } from "./weather-context"
|
||||
import { WeatherSource, Units } from "./weather-source"
|
||||
|
||||
const mockCredentials = {
|
||||
privateKey: "mock",
|
||||
keyId: "mock",
|
||||
teamId: "mock",
|
||||
serviceId: "mock",
|
||||
}
|
||||
|
||||
function createMockClient(response: WeatherKitResponse): WeatherKitClient {
|
||||
return {
|
||||
fetch: async () => response,
|
||||
}
|
||||
}
|
||||
|
||||
function createMockContext(location?: { lat: number; lng: number }): Context {
|
||||
const ctx: Context = { time: new Date("2026-01-17T00:00:00Z") }
|
||||
if (location) {
|
||||
ctx[LocationKey] = { ...location, accuracy: 10, timestamp: new Date() }
|
||||
}
|
||||
return ctx
|
||||
}
|
||||
|
||||
describe("WeatherSource", () => {
|
||||
describe("properties", () => {
|
||||
test("has correct id", () => {
|
||||
const source = new WeatherSource({ credentials: mockCredentials })
|
||||
expect(source.id).toBe("weather")
|
||||
})
|
||||
|
||||
test("depends on location", () => {
|
||||
const source = new WeatherSource({ credentials: mockCredentials })
|
||||
expect(source.dependencies).toEqual(["location"])
|
||||
})
|
||||
|
||||
test("throws error if neither client nor credentials provided", () => {
|
||||
expect(() => new WeatherSource({} as never)).toThrow(
|
||||
"Either client or credentials must be provided",
|
||||
)
|
||||
})
|
||||
})
|
||||
|
||||
describe("fetchContext", () => {
|
||||
const mockClient = createMockClient(fixture.response as WeatherKitResponse)
|
||||
|
||||
test("returns empty when no location", async () => {
|
||||
const source = new WeatherSource({ client: mockClient })
|
||||
const result = await source.fetchContext(createMockContext())
|
||||
|
||||
expect(result).toEqual({})
|
||||
})
|
||||
|
||||
test("returns simplified weather context", async () => {
|
||||
const source = new WeatherSource({ client: mockClient })
|
||||
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
|
||||
|
||||
const result = await source.fetchContext(context)
|
||||
const weather = contextValue(result, WeatherKey)
|
||||
|
||||
expect(weather).toBeDefined()
|
||||
expect(typeof weather!.temperature).toBe("number")
|
||||
expect(typeof weather!.temperatureApparent).toBe("number")
|
||||
expect(typeof weather!.condition).toBe("string")
|
||||
expect(typeof weather!.humidity).toBe("number")
|
||||
expect(typeof weather!.uvIndex).toBe("number")
|
||||
expect(typeof weather!.windSpeed).toBe("number")
|
||||
expect(typeof weather!.daylight).toBe("boolean")
|
||||
})
|
||||
|
||||
test("converts temperature to imperial", async () => {
|
||||
const source = new WeatherSource({ client: mockClient, units: Units.imperial })
|
||||
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
|
||||
|
||||
const result = await source.fetchContext(context)
|
||||
const weather = contextValue(result, WeatherKey)
|
||||
|
||||
// Fixture has temperature around 10°C, imperial should be around 50°F
|
||||
expect(weather!.temperature).toBeGreaterThan(40)
|
||||
})
|
||||
})
|
||||
|
||||
describe("fetchItems", () => {
|
||||
const mockClient = createMockClient(fixture.response as WeatherKitResponse)
|
||||
|
||||
test("returns empty array when no location", async () => {
|
||||
const source = new WeatherSource({ client: mockClient })
|
||||
const items = await source.fetchItems(createMockContext())
|
||||
|
||||
expect(items).toEqual([])
|
||||
})
|
||||
|
||||
test("returns feed items with all types", async () => {
|
||||
const source = new WeatherSource({ client: mockClient })
|
||||
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
|
||||
|
||||
const items = await source.fetchItems(context)
|
||||
|
||||
expect(items.length).toBeGreaterThan(0)
|
||||
expect(items.some((i) => i.type === WeatherFeedItemType.current)).toBe(true)
|
||||
expect(items.some((i) => i.type === WeatherFeedItemType.hourly)).toBe(true)
|
||||
expect(items.some((i) => i.type === WeatherFeedItemType.daily)).toBe(true)
|
||||
})
|
||||
|
||||
test("applies hourly and daily limits", async () => {
|
||||
const source = new WeatherSource({
|
||||
client: mockClient,
|
||||
hourlyLimit: 3,
|
||||
dailyLimit: 2,
|
||||
})
|
||||
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
|
||||
|
||||
const items = await source.fetchItems(context)
|
||||
|
||||
const hourlyItems = items.filter((i) => i.type === WeatherFeedItemType.hourly)
|
||||
const dailyItems = items.filter((i) => i.type === WeatherFeedItemType.daily)
|
||||
|
||||
expect(hourlyItems.length).toBe(3)
|
||||
expect(dailyItems.length).toBe(2)
|
||||
})
|
||||
|
||||
test("sets timestamp from context.time", async () => {
|
||||
const source = new WeatherSource({ client: mockClient })
|
||||
const queryTime = new Date("2026-01-17T12:00:00Z")
|
||||
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
|
||||
context.time = queryTime
|
||||
|
||||
const items = await source.fetchItems(context)
|
||||
|
||||
for (const item of items) {
|
||||
expect(item.timestamp).toEqual(queryTime)
|
||||
}
|
||||
})
|
||||
|
||||
test("assigns priority based on weather conditions", async () => {
|
||||
const source = new WeatherSource({ client: mockClient })
|
||||
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
|
||||
|
||||
const items = await source.fetchItems(context)
|
||||
|
||||
for (const item of items) {
|
||||
expect(item.priority).toBeGreaterThanOrEqual(0)
|
||||
expect(item.priority).toBeLessThanOrEqual(1)
|
||||
}
|
||||
|
||||
const currentItem = items.find((i) => i.type === WeatherFeedItemType.current)
|
||||
expect(currentItem).toBeDefined()
|
||||
expect(currentItem!.priority).toBeGreaterThanOrEqual(0.5)
|
||||
})
|
||||
|
||||
test("generates unique IDs for each item", async () => {
|
||||
const source = new WeatherSource({ client: mockClient })
|
||||
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
|
||||
|
||||
const items = await source.fetchItems(context)
|
||||
const ids = items.map((i) => i.id)
|
||||
const uniqueIds = new Set(ids)
|
||||
|
||||
expect(uniqueIds.size).toBe(ids.length)
|
||||
})
|
||||
})
|
||||
|
||||
describe("no reactive methods", () => {
|
||||
test("does not implement onContextUpdate", () => {
|
||||
const source = new WeatherSource({ credentials: mockCredentials })
|
||||
expect(source.onContextUpdate).toBeUndefined()
|
||||
})
|
||||
|
||||
test("does not implement onItemsUpdate", () => {
|
||||
const source = new WeatherSource({ credentials: mockCredentials })
|
||||
expect(source.onItemsUpdate).toBeUndefined()
|
||||
})
|
||||
})
|
||||
})
|
||||
363
packages/aris-source-weatherkit/src/weather-source.ts
Normal file
363
packages/aris-source-weatherkit/src/weather-source.ts
Normal file
@@ -0,0 +1,363 @@
|
||||
import type { Context, FeedSource } from "@aris/core"
|
||||
|
||||
import { contextValue } from "@aris/core"
|
||||
import { LocationKey } from "@aris/source-location"
|
||||
|
||||
import { WeatherFeedItemType, type WeatherFeedItem } from "./feed-items"
|
||||
import { WeatherKey, type Weather } from "./weather-context"
|
||||
import {
|
||||
DefaultWeatherKitClient,
|
||||
type ConditionCode,
|
||||
type CurrentWeather,
|
||||
type DailyForecast,
|
||||
type HourlyForecast,
|
||||
type Severity,
|
||||
type WeatherAlert,
|
||||
type WeatherKitClient,
|
||||
type WeatherKitCredentials,
|
||||
} from "./weatherkit"
|
||||
|
||||
export const Units = {
|
||||
metric: "metric",
|
||||
imperial: "imperial",
|
||||
} as const
|
||||
|
||||
export type Units = (typeof Units)[keyof typeof Units]
|
||||
|
||||
export interface WeatherSourceOptions {
|
||||
credentials?: WeatherKitCredentials
|
||||
client?: WeatherKitClient
|
||||
/** Number of hourly forecasts to include (default: 12) */
|
||||
hourlyLimit?: number
|
||||
/** Number of daily forecasts to include (default: 7) */
|
||||
dailyLimit?: number
|
||||
/** Units for temperature and measurements (default: metric) */
|
||||
units?: Units
|
||||
}
|
||||
|
||||
const DEFAULT_HOURLY_LIMIT = 12
|
||||
const DEFAULT_DAILY_LIMIT = 7
|
||||
|
||||
const BASE_PRIORITY = {
|
||||
current: 0.5,
|
||||
hourly: 0.3,
|
||||
daily: 0.2,
|
||||
alert: 0.7,
|
||||
} as const
|
||||
|
||||
const SEVERE_CONDITIONS = new Set<ConditionCode>([
|
||||
"SevereThunderstorm",
|
||||
"Hurricane",
|
||||
"Tornado",
|
||||
"TropicalStorm",
|
||||
"Blizzard",
|
||||
"FreezingRain",
|
||||
"Hail",
|
||||
"Frigid",
|
||||
"Hot",
|
||||
])
|
||||
|
||||
const MODERATE_CONDITIONS = new Set<ConditionCode>([
|
||||
"Thunderstorm",
|
||||
"IsolatedThunderstorms",
|
||||
"ScatteredThunderstorms",
|
||||
"HeavyRain",
|
||||
"HeavySnow",
|
||||
"FreezingDrizzle",
|
||||
"BlowingSnow",
|
||||
])
|
||||
|
||||
/**
|
||||
* A FeedSource that provides weather context and feed items using Apple WeatherKit.
|
||||
*
|
||||
* Depends on location source for coordinates. Provides simplified weather context
|
||||
* for downstream sources and produces weather feed items (current, hourly, daily, alerts).
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const weatherSource = new WeatherSource({
|
||||
* credentials: {
|
||||
* privateKey: process.env.WEATHERKIT_PRIVATE_KEY!,
|
||||
* keyId: process.env.WEATHERKIT_KEY_ID!,
|
||||
* teamId: process.env.WEATHERKIT_TEAM_ID!,
|
||||
* serviceId: process.env.WEATHERKIT_SERVICE_ID!,
|
||||
* },
|
||||
* units: Units.metric,
|
||||
* })
|
||||
*
|
||||
* // Access weather context in downstream sources
|
||||
* const weather = contextValue(context, WeatherKey)
|
||||
* if (weather?.condition === "Rain") {
|
||||
* // suggest umbrella
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export class WeatherSource implements FeedSource<WeatherFeedItem> {
|
||||
readonly id = "weather"
|
||||
readonly dependencies = ["location"]
|
||||
|
||||
private readonly client: WeatherKitClient
|
||||
private readonly hourlyLimit: number
|
||||
private readonly dailyLimit: number
|
||||
private readonly units: Units
|
||||
|
||||
constructor(options: WeatherSourceOptions) {
|
||||
if (!options.client && !options.credentials) {
|
||||
throw new Error("Either client or credentials must be provided")
|
||||
}
|
||||
this.client = options.client ?? new DefaultWeatherKitClient(options.credentials!)
|
||||
this.hourlyLimit = options.hourlyLimit ?? DEFAULT_HOURLY_LIMIT
|
||||
this.dailyLimit = options.dailyLimit ?? DEFAULT_DAILY_LIMIT
|
||||
this.units = options.units ?? Units.metric
|
||||
}
|
||||
|
||||
async fetchContext(context: Context): Promise<Partial<Context>> {
|
||||
const location = contextValue(context, LocationKey)
|
||||
if (!location) {
|
||||
return {}
|
||||
}
|
||||
|
||||
const response = await this.client.fetch({
|
||||
lat: location.lat,
|
||||
lng: location.lng,
|
||||
})
|
||||
|
||||
if (!response.currentWeather) {
|
||||
return {}
|
||||
}
|
||||
|
||||
const weather: Weather = {
|
||||
temperature: convertTemperature(response.currentWeather.temperature, this.units),
|
||||
temperatureApparent: convertTemperature(
|
||||
response.currentWeather.temperatureApparent,
|
||||
this.units,
|
||||
),
|
||||
condition: response.currentWeather.conditionCode,
|
||||
humidity: response.currentWeather.humidity,
|
||||
uvIndex: response.currentWeather.uvIndex,
|
||||
windSpeed: convertSpeed(response.currentWeather.windSpeed, this.units),
|
||||
daylight: response.currentWeather.daylight,
|
||||
}
|
||||
|
||||
return { [WeatherKey]: weather }
|
||||
}
|
||||
|
||||
async fetchItems(context: Context): Promise<WeatherFeedItem[]> {
|
||||
const location = contextValue(context, LocationKey)
|
||||
if (!location) {
|
||||
return []
|
||||
}
|
||||
|
||||
const timestamp = context.time
|
||||
|
||||
const response = await this.client.fetch({
|
||||
lat: location.lat,
|
||||
lng: location.lng,
|
||||
})
|
||||
|
||||
const items: WeatherFeedItem[] = []
|
||||
|
||||
if (response.currentWeather) {
|
||||
items.push(createCurrentWeatherFeedItem(response.currentWeather, timestamp, this.units))
|
||||
}
|
||||
|
||||
if (response.forecastHourly?.hours) {
|
||||
const hours = response.forecastHourly.hours.slice(0, this.hourlyLimit)
|
||||
for (let i = 0; i < hours.length; i++) {
|
||||
const hour = hours[i]
|
||||
if (hour) {
|
||||
items.push(createHourlyWeatherFeedItem(hour, i, timestamp, this.units))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (response.forecastDaily?.days) {
|
||||
const days = response.forecastDaily.days.slice(0, this.dailyLimit)
|
||||
for (let i = 0; i < days.length; i++) {
|
||||
const day = days[i]
|
||||
if (day) {
|
||||
items.push(createDailyWeatherFeedItem(day, i, timestamp, this.units))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (response.weatherAlerts?.alerts) {
|
||||
for (const alert of response.weatherAlerts.alerts) {
|
||||
items.push(createWeatherAlertFeedItem(alert, timestamp))
|
||||
}
|
||||
}
|
||||
|
||||
return items
|
||||
}
|
||||
}
|
||||
|
||||
function adjustPriorityForCondition(basePriority: number, conditionCode: ConditionCode): number {
|
||||
if (SEVERE_CONDITIONS.has(conditionCode)) {
|
||||
return Math.min(1, basePriority + 0.3)
|
||||
}
|
||||
if (MODERATE_CONDITIONS.has(conditionCode)) {
|
||||
return Math.min(1, basePriority + 0.15)
|
||||
}
|
||||
return basePriority
|
||||
}
|
||||
|
||||
function adjustPriorityForAlertSeverity(severity: Severity): number {
|
||||
switch (severity) {
|
||||
case "extreme":
|
||||
return 1
|
||||
case "severe":
|
||||
return 0.9
|
||||
case "moderate":
|
||||
return 0.75
|
||||
case "minor":
|
||||
return BASE_PRIORITY.alert
|
||||
}
|
||||
}
|
||||
|
||||
function convertTemperature(celsius: number, units: Units): number {
|
||||
if (units === Units.imperial) {
|
||||
return (celsius * 9) / 5 + 32
|
||||
}
|
||||
return celsius
|
||||
}
|
||||
|
||||
function convertSpeed(kmh: number, units: Units): number {
|
||||
if (units === Units.imperial) {
|
||||
return kmh * 0.621371
|
||||
}
|
||||
return kmh
|
||||
}
|
||||
|
||||
function convertDistance(km: number, units: Units): number {
|
||||
if (units === Units.imperial) {
|
||||
return km * 0.621371
|
||||
}
|
||||
return km
|
||||
}
|
||||
|
||||
function convertPrecipitation(mm: number, units: Units): number {
|
||||
if (units === Units.imperial) {
|
||||
return mm * 0.0393701
|
||||
}
|
||||
return mm
|
||||
}
|
||||
|
||||
function convertPressure(mb: number, units: Units): number {
|
||||
if (units === Units.imperial) {
|
||||
return mb * 0.02953
|
||||
}
|
||||
return mb
|
||||
}
|
||||
|
||||
function createCurrentWeatherFeedItem(
|
||||
current: CurrentWeather,
|
||||
timestamp: Date,
|
||||
units: Units,
|
||||
): WeatherFeedItem {
|
||||
const priority = adjustPriorityForCondition(BASE_PRIORITY.current, current.conditionCode)
|
||||
|
||||
return {
|
||||
id: `weather-current-${timestamp.getTime()}`,
|
||||
type: WeatherFeedItemType.current,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
conditionCode: current.conditionCode,
|
||||
daylight: current.daylight,
|
||||
humidity: current.humidity,
|
||||
precipitationIntensity: convertPrecipitation(current.precipitationIntensity, units),
|
||||
pressure: convertPressure(current.pressure, units),
|
||||
pressureTrend: current.pressureTrend,
|
||||
temperature: convertTemperature(current.temperature, units),
|
||||
temperatureApparent: convertTemperature(current.temperatureApparent, units),
|
||||
uvIndex: current.uvIndex,
|
||||
visibility: convertDistance(current.visibility, units),
|
||||
windDirection: current.windDirection,
|
||||
windGust: convertSpeed(current.windGust, units),
|
||||
windSpeed: convertSpeed(current.windSpeed, units),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createHourlyWeatherFeedItem(
|
||||
hourly: HourlyForecast,
|
||||
index: number,
|
||||
timestamp: Date,
|
||||
units: Units,
|
||||
): WeatherFeedItem {
|
||||
const priority = adjustPriorityForCondition(BASE_PRIORITY.hourly, hourly.conditionCode)
|
||||
|
||||
return {
|
||||
id: `weather-hourly-${timestamp.getTime()}-${index}`,
|
||||
type: WeatherFeedItemType.hourly,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
forecastTime: new Date(hourly.forecastStart),
|
||||
conditionCode: hourly.conditionCode,
|
||||
daylight: hourly.daylight,
|
||||
humidity: hourly.humidity,
|
||||
precipitationAmount: convertPrecipitation(hourly.precipitationAmount, units),
|
||||
precipitationChance: hourly.precipitationChance,
|
||||
precipitationType: hourly.precipitationType,
|
||||
temperature: convertTemperature(hourly.temperature, units),
|
||||
temperatureApparent: convertTemperature(hourly.temperatureApparent, units),
|
||||
uvIndex: hourly.uvIndex,
|
||||
windDirection: hourly.windDirection,
|
||||
windGust: convertSpeed(hourly.windGust, units),
|
||||
windSpeed: convertSpeed(hourly.windSpeed, units),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createDailyWeatherFeedItem(
|
||||
daily: DailyForecast,
|
||||
index: number,
|
||||
timestamp: Date,
|
||||
units: Units,
|
||||
): WeatherFeedItem {
|
||||
const priority = adjustPriorityForCondition(BASE_PRIORITY.daily, daily.conditionCode)
|
||||
|
||||
return {
|
||||
id: `weather-daily-${timestamp.getTime()}-${index}`,
|
||||
type: WeatherFeedItemType.daily,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
forecastDate: new Date(daily.forecastStart),
|
||||
conditionCode: daily.conditionCode,
|
||||
maxUvIndex: daily.maxUvIndex,
|
||||
precipitationAmount: convertPrecipitation(daily.precipitationAmount, units),
|
||||
precipitationChance: daily.precipitationChance,
|
||||
precipitationType: daily.precipitationType,
|
||||
snowfallAmount: convertPrecipitation(daily.snowfallAmount, units),
|
||||
sunrise: new Date(daily.sunrise),
|
||||
sunset: new Date(daily.sunset),
|
||||
temperatureMax: convertTemperature(daily.temperatureMax, units),
|
||||
temperatureMin: convertTemperature(daily.temperatureMin, units),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createWeatherAlertFeedItem(alert: WeatherAlert, timestamp: Date): WeatherFeedItem {
|
||||
const priority = adjustPriorityForAlertSeverity(alert.severity)
|
||||
|
||||
return {
|
||||
id: `weather-alert-${alert.id}`,
|
||||
type: WeatherFeedItemType.alert,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
alertId: alert.id,
|
||||
areaName: alert.areaName,
|
||||
certainty: alert.certainty,
|
||||
description: alert.description,
|
||||
detailsUrl: alert.detailsUrl,
|
||||
effectiveTime: new Date(alert.effectiveTime),
|
||||
expireTime: new Date(alert.expireTime),
|
||||
severity: alert.severity,
|
||||
source: alert.source,
|
||||
urgency: alert.urgency,
|
||||
},
|
||||
}
|
||||
}
|
||||
367
packages/aris-source-weatherkit/src/weatherkit.ts
Normal file
367
packages/aris-source-weatherkit/src/weatherkit.ts
Normal file
@@ -0,0 +1,367 @@
|
||||
// WeatherKit REST API client and response types
|
||||
// https://developer.apple.com/documentation/weatherkitrestapi
|
||||
|
||||
import { type } from "arktype"
|
||||
|
||||
export interface WeatherKitCredentials {
|
||||
privateKey: string
|
||||
keyId: string
|
||||
teamId: string
|
||||
serviceId: string
|
||||
}
|
||||
|
||||
export interface WeatherKitQueryOptions {
|
||||
lat: number
|
||||
lng: number
|
||||
language?: string
|
||||
timezone?: string
|
||||
}
|
||||
|
||||
export interface WeatherKitClient {
|
||||
fetch(query: WeatherKitQueryOptions): Promise<WeatherKitResponse>
|
||||
}
|
||||
|
||||
export class DefaultWeatherKitClient implements WeatherKitClient {
|
||||
private readonly credentials: WeatherKitCredentials
|
||||
|
||||
constructor(credentials: WeatherKitCredentials) {
|
||||
this.credentials = credentials
|
||||
}
|
||||
|
||||
async fetch(query: WeatherKitQueryOptions): Promise<WeatherKitResponse> {
|
||||
const token = await generateJwt(this.credentials)
|
||||
|
||||
const dataSets = ["currentWeather", "forecastHourly", "forecastDaily", "weatherAlerts"].join(
|
||||
",",
|
||||
)
|
||||
|
||||
const url = new URL(
|
||||
`${WEATHERKIT_API_BASE}/weather/${query.language ?? "en"}/${query.lat}/${query.lng}`,
|
||||
)
|
||||
url.searchParams.set("dataSets", dataSets)
|
||||
if (query.timezone) {
|
||||
url.searchParams.set("timezone", query.timezone)
|
||||
}
|
||||
|
||||
const response = await fetch(url.toString(), {
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`,
|
||||
},
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
const body = await response.text()
|
||||
throw new Error(`WeatherKit API error: ${response.status} ${response.statusText}: ${body}`)
|
||||
}
|
||||
|
||||
const json = await response.json()
|
||||
const result = weatherKitResponseSchema(json)
|
||||
|
||||
if (result instanceof type.errors) {
|
||||
throw new Error(`WeatherKit API response validation failed: ${result.summary}`)
|
||||
}
|
||||
|
||||
return result
|
||||
}
|
||||
}
|
||||
|
||||
export const Severity = {
|
||||
Minor: "minor",
|
||||
Moderate: "moderate",
|
||||
Severe: "severe",
|
||||
Extreme: "extreme",
|
||||
} as const
|
||||
|
||||
export type Severity = (typeof Severity)[keyof typeof Severity]
|
||||
|
||||
export const Urgency = {
|
||||
Immediate: "immediate",
|
||||
Expected: "expected",
|
||||
Future: "future",
|
||||
Past: "past",
|
||||
Unknown: "unknown",
|
||||
} as const
|
||||
|
||||
export type Urgency = (typeof Urgency)[keyof typeof Urgency]
|
||||
|
||||
export const Certainty = {
|
||||
Observed: "observed",
|
||||
Likely: "likely",
|
||||
Possible: "possible",
|
||||
Unlikely: "unlikely",
|
||||
Unknown: "unknown",
|
||||
} as const
|
||||
|
||||
export type Certainty = (typeof Certainty)[keyof typeof Certainty]
|
||||
|
||||
export const PrecipitationType = {
|
||||
Clear: "clear",
|
||||
Precipitation: "precipitation",
|
||||
Rain: "rain",
|
||||
Snow: "snow",
|
||||
Sleet: "sleet",
|
||||
Hail: "hail",
|
||||
Mixed: "mixed",
|
||||
} as const
|
||||
|
||||
export type PrecipitationType = (typeof PrecipitationType)[keyof typeof PrecipitationType]
|
||||
|
||||
export const ConditionCode = {
|
||||
Clear: "Clear",
|
||||
Cloudy: "Cloudy",
|
||||
Dust: "Dust",
|
||||
Fog: "Fog",
|
||||
Haze: "Haze",
|
||||
MostlyClear: "MostlyClear",
|
||||
MostlyCloudy: "MostlyCloudy",
|
||||
PartlyCloudy: "PartlyCloudy",
|
||||
ScatteredThunderstorms: "ScatteredThunderstorms",
|
||||
Smoke: "Smoke",
|
||||
Breezy: "Breezy",
|
||||
Windy: "Windy",
|
||||
Drizzle: "Drizzle",
|
||||
HeavyRain: "HeavyRain",
|
||||
Rain: "Rain",
|
||||
Showers: "Showers",
|
||||
Flurries: "Flurries",
|
||||
HeavySnow: "HeavySnow",
|
||||
MixedRainAndSleet: "MixedRainAndSleet",
|
||||
MixedRainAndSnow: "MixedRainAndSnow",
|
||||
MixedRainfall: "MixedRainfall",
|
||||
MixedSnowAndSleet: "MixedSnowAndSleet",
|
||||
ScatteredShowers: "ScatteredShowers",
|
||||
ScatteredSnowShowers: "ScatteredSnowShowers",
|
||||
Sleet: "Sleet",
|
||||
Snow: "Snow",
|
||||
SnowShowers: "SnowShowers",
|
||||
Blizzard: "Blizzard",
|
||||
BlowingSnow: "BlowingSnow",
|
||||
FreezingDrizzle: "FreezingDrizzle",
|
||||
FreezingRain: "FreezingRain",
|
||||
Frigid: "Frigid",
|
||||
Hail: "Hail",
|
||||
Hot: "Hot",
|
||||
Hurricane: "Hurricane",
|
||||
IsolatedThunderstorms: "IsolatedThunderstorms",
|
||||
SevereThunderstorm: "SevereThunderstorm",
|
||||
Thunderstorm: "Thunderstorm",
|
||||
Tornado: "Tornado",
|
||||
TropicalStorm: "TropicalStorm",
|
||||
} as const
|
||||
|
||||
export type ConditionCode = (typeof ConditionCode)[keyof typeof ConditionCode]
|
||||
|
||||
const WEATHERKIT_API_BASE = "https://weatherkit.apple.com/api/v1"
|
||||
|
||||
const severitySchema = type.enumerated(
|
||||
Severity.Minor,
|
||||
Severity.Moderate,
|
||||
Severity.Severe,
|
||||
Severity.Extreme,
|
||||
)
|
||||
|
||||
const urgencySchema = type.enumerated(
|
||||
Urgency.Immediate,
|
||||
Urgency.Expected,
|
||||
Urgency.Future,
|
||||
Urgency.Past,
|
||||
Urgency.Unknown,
|
||||
)
|
||||
|
||||
const certaintySchema = type.enumerated(
|
||||
Certainty.Observed,
|
||||
Certainty.Likely,
|
||||
Certainty.Possible,
|
||||
Certainty.Unlikely,
|
||||
Certainty.Unknown,
|
||||
)
|
||||
|
||||
const precipitationTypeSchema = type.enumerated(
|
||||
PrecipitationType.Clear,
|
||||
PrecipitationType.Precipitation,
|
||||
PrecipitationType.Rain,
|
||||
PrecipitationType.Snow,
|
||||
PrecipitationType.Sleet,
|
||||
PrecipitationType.Hail,
|
||||
PrecipitationType.Mixed,
|
||||
)
|
||||
|
||||
const conditionCodeSchema = type.enumerated(...Object.values(ConditionCode))
|
||||
|
||||
const pressureTrendSchema = type.enumerated("rising", "falling", "steady")
|
||||
|
||||
const currentWeatherSchema = type({
|
||||
asOf: "string",
|
||||
conditionCode: conditionCodeSchema,
|
||||
daylight: "boolean",
|
||||
humidity: "number",
|
||||
precipitationIntensity: "number",
|
||||
pressure: "number",
|
||||
pressureTrend: pressureTrendSchema,
|
||||
temperature: "number",
|
||||
temperatureApparent: "number",
|
||||
temperatureDewPoint: "number",
|
||||
uvIndex: "number",
|
||||
visibility: "number",
|
||||
windDirection: "number",
|
||||
windGust: "number",
|
||||
windSpeed: "number",
|
||||
})
|
||||
|
||||
export type CurrentWeather = typeof currentWeatherSchema.infer
|
||||
|
||||
const hourlyForecastSchema = type({
|
||||
forecastStart: "string",
|
||||
conditionCode: conditionCodeSchema,
|
||||
daylight: "boolean",
|
||||
humidity: "number",
|
||||
precipitationAmount: "number",
|
||||
precipitationChance: "number",
|
||||
precipitationType: precipitationTypeSchema,
|
||||
pressure: "number",
|
||||
snowfallIntensity: "number",
|
||||
temperature: "number",
|
||||
temperatureApparent: "number",
|
||||
temperatureDewPoint: "number",
|
||||
uvIndex: "number",
|
||||
visibility: "number",
|
||||
windDirection: "number",
|
||||
windGust: "number",
|
||||
windSpeed: "number",
|
||||
})
|
||||
|
||||
export type HourlyForecast = typeof hourlyForecastSchema.infer
|
||||
|
||||
const dayWeatherConditionsSchema = type({
|
||||
conditionCode: conditionCodeSchema,
|
||||
humidity: "number",
|
||||
precipitationAmount: "number",
|
||||
precipitationChance: "number",
|
||||
precipitationType: precipitationTypeSchema,
|
||||
snowfallAmount: "number",
|
||||
temperatureMax: "number",
|
||||
temperatureMin: "number",
|
||||
windDirection: "number",
|
||||
"windGust?": "number",
|
||||
windSpeed: "number",
|
||||
})
|
||||
|
||||
export type DayWeatherConditions = typeof dayWeatherConditionsSchema.infer
|
||||
|
||||
const dailyForecastSchema = type({
|
||||
forecastStart: "string",
|
||||
forecastEnd: "string",
|
||||
conditionCode: conditionCodeSchema,
|
||||
maxUvIndex: "number",
|
||||
moonPhase: "string",
|
||||
"moonrise?": "string",
|
||||
"moonset?": "string",
|
||||
precipitationAmount: "number",
|
||||
precipitationChance: "number",
|
||||
precipitationType: precipitationTypeSchema,
|
||||
snowfallAmount: "number",
|
||||
sunrise: "string",
|
||||
sunriseCivil: "string",
|
||||
sunriseNautical: "string",
|
||||
sunriseAstronomical: "string",
|
||||
sunset: "string",
|
||||
sunsetCivil: "string",
|
||||
sunsetNautical: "string",
|
||||
sunsetAstronomical: "string",
|
||||
temperatureMax: "number",
|
||||
temperatureMin: "number",
|
||||
"daytimeForecast?": dayWeatherConditionsSchema,
|
||||
"overnightForecast?": dayWeatherConditionsSchema,
|
||||
})
|
||||
|
||||
export type DailyForecast = typeof dailyForecastSchema.infer
|
||||
|
||||
const weatherAlertSchema = type({
|
||||
id: "string",
|
||||
areaId: "string",
|
||||
areaName: "string",
|
||||
certainty: certaintySchema,
|
||||
countryCode: "string",
|
||||
description: "string",
|
||||
detailsUrl: "string",
|
||||
effectiveTime: "string",
|
||||
expireTime: "string",
|
||||
issuedTime: "string",
|
||||
responses: "string[]",
|
||||
severity: severitySchema,
|
||||
source: "string",
|
||||
urgency: urgencySchema,
|
||||
})
|
||||
|
||||
export type WeatherAlert = typeof weatherAlertSchema.infer
|
||||
|
||||
const weatherKitResponseSchema = type({
|
||||
"currentWeather?": currentWeatherSchema,
|
||||
"forecastHourly?": type({
|
||||
hours: hourlyForecastSchema.array(),
|
||||
}),
|
||||
"forecastDaily?": type({
|
||||
days: dailyForecastSchema.array(),
|
||||
}),
|
||||
"weatherAlerts?": type({
|
||||
alerts: weatherAlertSchema.array(),
|
||||
}),
|
||||
})
|
||||
|
||||
export type WeatherKitResponse = typeof weatherKitResponseSchema.infer
|
||||
|
||||
async function generateJwt(credentials: WeatherKitCredentials): Promise<string> {
|
||||
const header = {
|
||||
alg: "ES256",
|
||||
kid: credentials.keyId,
|
||||
id: `${credentials.teamId}.${credentials.serviceId}`,
|
||||
}
|
||||
|
||||
const now = Math.floor(Date.now() / 1000)
|
||||
const payload = {
|
||||
iss: credentials.teamId,
|
||||
iat: now,
|
||||
exp: now + 3600,
|
||||
sub: credentials.serviceId,
|
||||
}
|
||||
|
||||
const encoder = new TextEncoder()
|
||||
const headerB64 = btoa(JSON.stringify(header))
|
||||
.replace(/\+/g, "-")
|
||||
.replace(/\//g, "_")
|
||||
.replace(/=+$/, "")
|
||||
const payloadB64 = btoa(JSON.stringify(payload))
|
||||
.replace(/\+/g, "-")
|
||||
.replace(/\//g, "_")
|
||||
.replace(/=+$/, "")
|
||||
|
||||
const signingInput = `${headerB64}.${payloadB64}`
|
||||
|
||||
const pemContents = credentials.privateKey
|
||||
.replace(/-----BEGIN PRIVATE KEY-----/, "")
|
||||
.replace(/-----END PRIVATE KEY-----/, "")
|
||||
.replace(/\s/g, "")
|
||||
|
||||
const binaryKey = Uint8Array.from(atob(pemContents), (c) => c.charCodeAt(0))
|
||||
|
||||
const cryptoKey = await crypto.subtle.importKey(
|
||||
"pkcs8",
|
||||
binaryKey,
|
||||
{ name: "ECDSA", namedCurve: "P-256" },
|
||||
false,
|
||||
["sign"],
|
||||
)
|
||||
|
||||
const signature = await crypto.subtle.sign(
|
||||
{ name: "ECDSA", hash: "SHA-256" },
|
||||
cryptoKey,
|
||||
encoder.encode(signingInput),
|
||||
)
|
||||
|
||||
const signatureB64 = btoa(String.fromCharCode(...new Uint8Array(signature)))
|
||||
.replace(/\+/g, "-")
|
||||
.replace(/\//g, "_")
|
||||
.replace(/=+$/, "")
|
||||
|
||||
return `${signingInput}.${signatureB64}`
|
||||
}
|
||||
Reference in New Issue
Block a user