kennethnym/aris
1
0
Fork 0
mirror of https://github.com/kennethnym/aris.git synced 2026-03-20 09:01:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add actions to FeedSource interface

Browse Source 
Add listActions() and executeAction() to FeedSource for write
operations back to external services. Actions use arktype schemas
for input validation via StandardSchemaV1.

- ActionDefinition type with optional input schema
- FeedEngine routes actions with existence and ID validation
- Source IDs use reverse-domain format (aris.location, aris.tfl)
- LocationSource: update-location action with schema validation
- TflSource: set-lines-of-interest action with lineId validation
- No-op implementations for sources without actions

Co-authored-by: Ona <no-reply@ona.com>
This commit is contained in:
Kenneth
2026-02-15 12:26:23 +00:00
parent 4d6cac7ec8
commit 699155e0d8
29 changed files with 1169 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
packages/aris-core/package.json
View File

@@ -6,5 +6,8 @@
"types": "src/index.ts",
"scripts": {
"test": "bun test ."
},
"dependencies": {
"@standard-schema/spec": "^1.1.0"
}
}

27
packages/aris-core/src/action.ts Normal file
View File

@@ -0,0 +1,27 @@
import type { StandardSchemaV1 } from "@standard-schema/spec"
/**
* Describes an action a source can perform.
*
* Action IDs use descriptive verb-noun kebab-case (e.g., "update-location", "play-track").
* Combined with the source's reverse-domain ID, they form a globally unique identifier:
* `<sourceId>/<actionId>` (e.g., "aris.location/update-location").
*/
export class UnknownActionError extends Error {
readonly actionId: string
constructor(actionId: string) {
super(`Unknown action: ${actionId}`)
this.name = "UnknownActionError"
this.actionId = actionId
}
}
export interface ActionDefinition<TInput = unknown> {
/** Descriptive action name in kebab-case (e.g., "update-location", "play-track") */
readonly id: string
/** Optional longer description */
readonly description?: string
/** Schema for input validation. Accepts any Standard Schema compatible validator (arktype, zod, valibot, etc.). */
readonly input?: StandardSchemaV1<TInput>
}

162
packages/aris-core/src/feed-engine.test.ts
View File

@@ -1,9 +1,19 @@
import { describe, expect, test } from "bun:test"
import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
import { FeedEngine } from "./feed-engine"
import { contextKey, contextValue } from "./index"
import { UnknownActionError, contextKey, contextValue } from "./index"
// No-op action methods for test sources
const noActions = {
async listActions(): Promise<Record<string, ActionDefinition>> {
return {}
},
async executeAction(actionId: string): Promise<void> {
throw new UnknownActionError(actionId)
},
}
// =============================================================================
// CONTEXT KEYS
@@ -43,6 +53,7 @@ function createLocationSource(): SimulatedLocationSource {
return {
id: "location",
...noActions,
onContextUpdate(cb) {
callback = cb
@@ -71,6 +82,7 @@ function createWeatherSource(
return {
id: "weather",
dependencies: ["location"],
...noActions,
async fetchContext(context) {
const location = contextValue(context, LocationKey)
@@ -104,6 +116,7 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
return {
id: "alert",
dependencies: ["weather"],
...noActions,
async fetchContext() {
return null
@@ -168,11 +181,12 @@ describe("FeedEngine", () => {
})
describe("graph validation", () => {
test("throws on missing dependency", () => {
test("throws on missing dependency", async () => {
const engine = new FeedEngine()
const orphan: FeedSource = {
id: "orphan",
dependencies: ["nonexistent"],
...noActions,
async fetchContext() {
return null
},
@@ -180,16 +194,17 @@ describe("FeedEngine", () => {
engine.register(orphan)
expect(engine.refresh()).rejects.toThrow(
await expect(engine.refresh()).rejects.toThrow(
'Source "orphan" depends on "nonexistent" which is not registered',
)
})
test("throws on circular dependency", () => {
test("throws on circular dependency", async () => {
const engine = new FeedEngine()
const a: FeedSource = {
id: "a",
dependencies: ["b"],
...noActions,
async fetchContext() {
return null
},
@@ -197,6 +212,7 @@ describe("FeedEngine", () => {
const b: FeedSource = {
id: "b",
dependencies: ["a"],
...noActions,
async fetchContext() {
return null
},
@@ -204,14 +220,15 @@ describe("FeedEngine", () => {
engine.register(a).register(b)
expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
await expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
})
test("throws on longer cycles", () => {
test("throws on longer cycles", async () => {
const engine = new FeedEngine()
const a: FeedSource = {
id: "a",
dependencies: ["c"],
...noActions,
async fetchContext() {
return null
},
@@ -219,6 +236,7 @@ describe("FeedEngine", () => {
const b: FeedSource = {
id: "b",
dependencies: ["a"],
...noActions,
async fetchContext() {
return null
},
@@ -226,6 +244,7 @@ describe("FeedEngine", () => {
const c: FeedSource = {
id: "c",
dependencies: ["b"],
...noActions,
async fetchContext() {
return null
},
@@ -233,7 +252,7 @@ describe("FeedEngine", () => {
engine.register(a).register(b).register(c)
expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
await expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
})
})
@@ -243,6 +262,7 @@ describe("FeedEngine", () => {
const location: FeedSource = {
id: "location",
...noActions,
async fetchContext() {
order.push("location")
return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -252,6 +272,7 @@ describe("FeedEngine", () => {
const weather: FeedSource = {
id: "weather",
dependencies: ["location"],
...noActions,
async fetchContext(ctx) {
order.push("weather")
const loc = contextValue(ctx, LocationKey)
@@ -277,8 +298,14 @@ describe("FeedEngine", () => {
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" })
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 () => {
@@ -318,6 +345,7 @@ describe("FeedEngine", () => {
test("handles missing upstream context gracefully", async () => {
const location: FeedSource = {
id: "location",
...noActions,
async fetchContext() {
return null // No location available
},
@@ -336,6 +364,7 @@ describe("FeedEngine", () => {
test("captures errors from fetchContext", async () => {
const failing: FeedSource = {
id: "failing",
...noActions,
async fetchContext() {
throw new Error("Context fetch failed")
},
@@ -353,6 +382,7 @@ describe("FeedEngine", () => {
test("captures errors from fetchItems", async () => {
const failing: FeedSource = {
id: "failing",
...noActions,
async fetchContext() {
return null
},
@@ -373,6 +403,7 @@ describe("FeedEngine", () => {
test("continues after source error", async () => {
const failing: FeedSource = {
id: "failing",
...noActions,
async fetchContext() {
throw new Error("Failed")
},
@@ -380,6 +411,7 @@ describe("FeedEngine", () => {
const working: FeedSource = {
id: "working",
...noActions,
async fetchContext() {
return null
},
@@ -423,7 +455,10 @@ describe("FeedEngine", () => {
await engine.refresh()
const context = engine.currentContext()
expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
expect(contextValue(context, LocationKey)).toEqual({
lat: 51.5,
lng: -0.1,
})
})
})
@@ -498,4 +533,109 @@ describe("FeedEngine", () => {
engine.stop()
})
})
describe("executeAction", () => {
test("routes action to correct source", async () => {
let receivedAction = ""
let receivedParams: unknown = {}
const source: FeedSource = {
id: "test-source",
async listActions() {
return {
"do-thing": { id: "do-thing" },
}
},
async executeAction(actionId, params) {
receivedAction = actionId
receivedParams = params
},
async fetchContext() {
return null
},
}
const engine = new FeedEngine().register(source)
await engine.executeAction("test-source", "do-thing", { key: "value" })
expect(receivedAction).toBe("do-thing")
expect(receivedParams).toEqual({ key: "value" })
})
test("throws for unknown source", async () => {
const engine = new FeedEngine()
await expect(engine.executeAction("nonexistent", "action", {})).rejects.toThrow(
"Source not found: nonexistent",
)
})
test("throws for unknown action on source", async () => {
const source: FeedSource = {
id: "test-source",
...noActions,
async fetchContext() {
return null
},
}
const engine = new FeedEngine().register(source)
await expect(engine.executeAction("test-source", "nonexistent", {})).rejects.toThrow(
'Action "nonexistent" not found on source "test-source"',
)
})
})
describe("listActions", () => {
test("returns actions for a specific source", async () => {
const source: FeedSource = {
id: "test-source",
async listActions() {
return {
"action-1": { id: "action-1" },
"action-2": { id: "action-2" },
}
},
async executeAction() {},
async fetchContext() {
return null
},
}
const engine = new FeedEngine().register(source)
const actions = await engine.listActions("test-source")
expect(Object.keys(actions)).toEqual(["action-1", "action-2"])
})
test("throws for unknown source", async () => {
const engine = new FeedEngine()
await expect(engine.listActions("nonexistent")).rejects.toThrow(
"Source not found: nonexistent",
)
})
test("throws on mismatched action ID", async () => {
const source: FeedSource = {
id: "bad-source",
async listActions() {
return {
"correct-key": { id: "wrong-id" },
}
},
async executeAction() {},
async fetchContext() {
return null
},
}
const engine = new FeedEngine().register(source)
await expect(engine.listActions("bad-source")).rejects.toThrow(
'Action ID mismatch on source "bad-source"',
)
})
})
})

45
packages/aris-core/src/feed-engine.ts
View File

@@ -1,3 +1,4 @@
import type { ActionDefinition } from "./action"
import type { Context } from "./context"
import type { FeedItem } from "./feed"
import type { FeedSource } from "./feed-source"
@@ -187,6 +188,44 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
return this.context
}
/**
* Execute an action on a registered source.
* Validates the action exists before dispatching.
*
* In pull-only mode (before `start()` is called), the action mutates source
* state but does not automatically refresh dependents. Call `refresh()`
* after to propagate changes. In reactive mode (`start()` called), sources
* that push context updates (e.g., LocationSource) will trigger dependent
* refresh automatically.
*/
async executeAction(sourceId: string, actionId: string, params: unknown): Promise<unknown> {
const actions = await this.listActions(sourceId)
if (!(actionId in actions)) {
throw new Error(`Action "${actionId}" not found on source "${sourceId}"`)
}
return this.sources.get(sourceId)!.executeAction(actionId, params)
}
/**
* List actions available on a specific source.
* Validates that action definition IDs match their record keys.
*/
async listActions(sourceId: string): Promise<Record<string, ActionDefinition>> {
const source = this.sources.get(sourceId)
if (!source) {
throw new Error(`Source not found: ${sourceId}`)
}
const actions = await source.listActions()
for (const [key, definition] of Object.entries(actions)) {
if (key !== definition.id) {
throw new Error(
`Action ID mismatch on source "${sourceId}": key "${key}" !== definition.id "${definition.id}"`,
)
}
}
return actions
}
private ensureGraph(): SourceGraph {
if (!this.graph) {
this.graph = buildGraph(Array.from(this.sources.values()))
@@ -240,7 +279,11 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
items.sort((a, b) => b.priority - a.priority)
this.notifySubscribers({ context: this.context, items: items as TItems[], errors })
this.notifySubscribers({
context: this.context,
items: items as TItems[],
errors,
})
}
private collectDependents(sourceId: string, graph: SourceGraph): string[] {

36
packages/aris-core/src/feed-source.test.ts
View File

@@ -1,8 +1,18 @@
import { describe, expect, test } from "bun:test"
import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
import { contextKey, contextValue } from "./index"
import { UnknownActionError, contextKey, contextValue } from "./index"
// No-op action methods for test sources
const noActions = {
async listActions(): Promise<Record<string, ActionDefinition>> {
return {}
},
async executeAction(actionId: string): Promise<void> {
throw new UnknownActionError(actionId)
},
}
// =============================================================================
// CONTEXT KEYS
@@ -42,6 +52,7 @@ function createLocationSource(): SimulatedLocationSource {
return {
id: "location",
...noActions,
onContextUpdate(cb) {
callback = cb
@@ -70,6 +81,7 @@ function createWeatherSource(
return {
id: "weather",
dependencies: ["location"],
...noActions,
async fetchContext(context) {
const location = contextValue(context, LocationKey)
@@ -103,6 +115,7 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
return {
id: "alert",
dependencies: ["weather"],
...noActions,
async fetchContext() {
return null
@@ -265,6 +278,7 @@ describe("FeedSource", () => {
const orphan: FeedSource = {
id: "orphan",
dependencies: ["nonexistent"],
...noActions,
async fetchContext() {
return null
},
@@ -279,6 +293,7 @@ describe("FeedSource", () => {
const a: FeedSource = {
id: "a",
dependencies: ["b"],
...noActions,
async fetchContext() {
return null
},
@@ -286,6 +301,7 @@ describe("FeedSource", () => {
const b: FeedSource = {
id: "b",
dependencies: ["a"],
...noActions,
async fetchContext() {
return null
},
@@ -298,6 +314,7 @@ describe("FeedSource", () => {
const a: FeedSource = {
id: "a",
dependencies: ["c"],
...noActions,
async fetchContext() {
return null
},
@@ -305,6 +322,7 @@ describe("FeedSource", () => {
const b: FeedSource = {
id: "b",
dependencies: ["a"],
...noActions,
async fetchContext() {
return null
},
@@ -312,6 +330,7 @@ describe("FeedSource", () => {
const c: FeedSource = {
id: "c",
dependencies: ["b"],
...noActions,
async fetchContext() {
return null
},
@@ -350,6 +369,7 @@ describe("FeedSource", () => {
const location: FeedSource = {
id: "location",
...noActions,
async fetchContext() {
order.push("location")
return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -359,6 +379,7 @@ describe("FeedSource", () => {
const weather: FeedSource = {
id: "weather",
dependencies: ["location"],
...noActions,
async fetchContext(ctx) {
order.push("weather")
const loc = contextValue(ctx, LocationKey)
@@ -382,8 +403,14 @@ describe("FeedSource", () => {
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" })
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 () => {
@@ -422,6 +449,7 @@ describe("FeedSource", () => {
// Location source exists but hasn't been updated
const location: FeedSource = {
id: "location",
...noActions,
async fetchContext() {
// Simulate no location available
return null

68
packages/aris-core/src/feed-source.ts
View File

@@ -1,61 +1,60 @@
import type { ActionDefinition } from "./action"
import type { Context } from "./context"
import type { FeedItem } from "./feed"
/**
* Unified interface for sources that provide context and/or feed items.
* Unified interface for sources that provide context, feed items, and actions.
*
* Sources form a dependency graph - a source declares which other sources
* 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
* Source IDs use reverse domain notation. Built-in sources use `aris.<name>`,
* third parties use their own domain (e.g., `com.spotify`).
*
* Every method maps to a protocol operation for remote source support:
* - `id`, `dependencies` → source/describe
* - `listActions()` → source/listActions
* - `executeAction()` → source/executeAction
* - `fetchContext()` → source/fetchContext
* - `fetchItems()` → source/fetchItems
* - `onContextUpdate()` → source/contextUpdated (notification)
* - `onItemsUpdate()` → source/itemsUpdated (notification)
*
* @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)
* },
* }
*
* // TFL source - no context to provide
* const tflSource: FeedSource<TflFeedItem> = {
* id: "tfl",
* fetchContext: async () => null,
* fetchItems: async (ctx) => { ... },
* id: "aris.location",
* async listActions() { return { "update-location": { id: "update-location" } } },
* async executeAction(actionId) { throw new UnknownActionError(actionId) },
* async fetchContext() { ... },
* }
* ```
*/
export interface FeedSource<TItem extends FeedItem = FeedItem> {
/** Unique identifier for this source */
/** Unique identifier for this source in reverse-domain format */
readonly id: string
/** IDs of sources this source depends on */
readonly dependencies?: readonly string[]
/**
* List actions this source supports. Empty record if none.
* Maps to: source/listActions
*/
listActions(): Promise<Record<string, ActionDefinition>>
/**
* Execute an action by ID. Throws on unknown action or invalid input.
* Maps to: source/executeAction
*/
executeAction(actionId: string, params: unknown): Promise<unknown>
/**
* Subscribe to reactive context updates.
* Called when the source can push context changes proactively.
* Returns cleanup function.
* Maps to: source/contextUpdated (notification, source → host)
*/
onContextUpdate?(
callback: (update: Partial<Context>) => void,
@@ -66,6 +65,7 @@ export interface FeedSource<TItem extends FeedItem = FeedItem> {
* Fetch context on-demand.
* Called during manual refresh or initial load.
* Return null if this source cannot provide context.
* Maps to: source/fetchContext
*/
fetchContext(context: Context): Promise<Partial<Context> | null>
@@ -73,12 +73,14 @@ export interface FeedSource<TItem extends FeedItem = FeedItem> {
* Subscribe to reactive feed item updates.
* Called when the source can push item changes proactively.
* Returns cleanup function.
* Maps to: source/itemsUpdated (notification, source → host)
*/
onItemsUpdate?(callback: (items: TItem[]) => void, getContext: () => Context): () => void
/**
* Fetch feed items on-demand.
* Called during manual refresh or when dependencies update.
* Maps to: source/fetchItems
*/
fetchItems?(context: Context): Promise<TItem[]>
}

4
packages/aris-core/src/index.ts
View File

@@ -2,6 +2,10 @@
export type { Context, ContextKey } from "./context"
export { contextKey, contextValue } from "./context"
// Actions
export type { ActionDefinition } from "./action"
export { UnknownActionError } from "./action"
// Feed
export type { FeedItem } from "./feed"