@swirls/looms 0.0.1

package/dist/projectors/sqlite.js

@@ -0,0 +1,103 @@
+import { Database } from 'bun:sqlite';
+import { createIndexProjector, } from './index-model.js';
+import { SQLITE_SCHEMA_SQL } from './schema.js';
+export { SQLITE_SCHEMA_SQL } from './schema.js';
+function hasDb(options) {
+    return 'db' in options;
+}
+function applyOp(db, op) {
+    switch (op.type) {
+        case 'upsertActor':
+            db.run(`INSERT INTO looms_actors (actor_id, kind, status, definition_name, parent_actor_id, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT (actor_id) DO UPDATE SET
+           kind = excluded.kind,
+           status = excluded.status,
+           definition_name = excluded.definition_name,
+           parent_actor_id = excluded.parent_actor_id,
+           updated_at = excluded.updated_at`, [op.actorId, op.kind, op.status, op.definitionName, op.parentActorId, op.updatedAt]);
+            return;
+        case 'setActorStatus':
+            db.run(`INSERT INTO looms_actors (actor_id, status, updated_at)
+         VALUES (?, ?, ?)
+         ON CONFLICT (actor_id) DO UPDATE SET
+           status = excluded.status,
+           updated_at = excluded.updated_at`, [op.actorId, op.status, op.updatedAt]);
+            return;
+        case 'upsertReview':
+            db.run(`INSERT INTO looms_reviews (review_id, actor_id, status, title, updated_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT (review_id) DO UPDATE SET
+           status = excluded.status,
+           updated_at = excluded.updated_at`, [op.reviewId, op.actorId, op.status, op.title, op.updatedAt]);
+            return;
+        case 'setReviewStatus':
+            db.run(`UPDATE looms_reviews SET status = ?, updated_at = ? WHERE review_id = ?`, [
+                op.status,
+                op.updatedAt,
+                op.reviewId,
+            ]);
+            return;
+        default: {
+            const exhaustiveCheck = op;
+            return exhaustiveCheck;
+        }
+    }
+}
+export function sqlite(options = {}) {
+    const createdDb = !hasDb(options);
+    const db = hasDb(options) ? options.db : new Database(options.path ?? ':memory:');
+    const backend = {
+        init: async () => {
+            db.exec(SQLITE_SCHEMA_SQL);
+        },
+        applyOps: async (ops) => {
+            const apply = db.transaction((batch) => {
+                for (const op of batch) {
+                    applyOp(db, op);
+                }
+            });
+            apply(ops);
+        },
+        getActor: async (actorId) => {
+            const row = db
+                .query(`SELECT actor_id, kind, status, definition_name, parent_actor_id, updated_at
+           FROM looms_actors WHERE actor_id = ?`)
+                .get(actorId);
+            if (!row) {
+                return null;
+            }
+            return {
+                actorId: row.actor_id,
+                kind: row.kind,
+                status: row.status,
+                definitionName: row.definition_name,
+                parentActorId: row.parent_actor_id,
+                updatedAt: row.updated_at,
+            };
+        },
+        listReviews: async (actorId) => {
+            const rows = actorId
+                ? db
+                    .query(`SELECT review_id, actor_id, status, title, updated_at
+               FROM looms_reviews WHERE actor_id = ?`)
+                    .all(actorId)
+                : db
+                    .query(`SELECT review_id, actor_id, status, title, updated_at FROM looms_reviews`)
+                    .all();
+            return rows.map((row) => ({
+                reviewId: row.review_id,
+                actorId: row.actor_id,
+                status: row.status,
+                title: row.title,
+                updatedAt: row.updated_at,
+            }));
+        },
+        dispose: async () => {
+            if (createdDb) {
+                db.close();
+            }
+        },
+    };
+    return createIndexProjector('sqlite', backend);
+}

package/dist/projectors/with-projectors.d.ts

@@ -0,0 +1,17 @@
+import { Layer } from 'effect';
+import { EventStoreTag, type EventStore, type EventEnvelope } from '@swirls/looms/core';
+import type { Projector, ProjectorErrorHandler } from './projector';
+export interface WithProjectorsOptions {
+    onError?: ProjectorErrorHandler;
+}
+/**
+ * Wrap an EventStore so every successful append is also projected.
+ * Projection failures are isolated so the primary log stays authoritative.
+ */
+export declare function withProjectors(store: EventStore, projectors: ReadonlyArray<Projector>, options?: WithProjectorsOptions): EventStore;
+/** Project events after the fact (e.g. from a runtime hook). */
+export declare function projectEvents(projectors: ReadonlyArray<Projector>, events: readonly EventEnvelope[]): Promise<void>;
+/**
+ * Layer that decorates a base EventStore with projection.
+ */
+export declare function ProjectorsStoreLive(base: EventStore, projectors: ReadonlyArray<Projector>, options?: WithProjectorsOptions): Layer.Layer<EventStoreTag>;

package/dist/projectors/with-projectors.js

@@ -0,0 +1,55 @@
+import { Effect, Layer } from 'effect';
+import { EventStoreTag, snapshotStoreOf, withSnapshotStore, } from '@swirls/looms/core';
+function defaultOnError(error, projector) {
+    console.warn(`[@swirls/looms/projectors] ${projector.name} failed to project: ${error.message}`);
+}
+/**
+ * Wrap an EventStore so every successful append is also projected.
+ * Projection failures are isolated so the primary log stays authoritative.
+ */
+export function withProjectors(store, projectors, options) {
+    const onError = options?.onError ?? defaultOnError;
+    const wrapped = {
+        append: (runId, events, appendOptions) => Effect.gen(function* () {
+            const result = yield* store.append(runId, events, appendOptions);
+            const fromSeq = result.sequences[0];
+            if (fromSeq !== undefined && projectors.length > 0) {
+                const written = yield* store.read(runId, {
+                    fromSeq,
+                    limit: result.sequences.length,
+                });
+                yield* Effect.promise(async () => {
+                    for (const projector of projectors) {
+                        try {
+                            await projector.project(written);
+                        }
+                        catch (cause) {
+                            onError(cause instanceof Error ? cause : new Error(String(cause)), projector, written);
+                        }
+                    }
+                });
+            }
+            return result;
+        }),
+        read: (runId, readOptions) => store.read(runId, readOptions),
+        tail: (runId) => store.tail(runId),
+        bounds: store.bounds ? (runId) => store.bounds(runId) : undefined,
+        trim: store.trim ? (runId, beforeSeq) => store.trim(runId, beforeSeq) : undefined,
+        subscribe: (runId, subscribeOptions) => store.subscribe(runId, subscribeOptions),
+        listRuns: () => store.listRuns(),
+    };
+    const snapshots = snapshotStoreOf(store);
+    return snapshots ? withSnapshotStore(wrapped, snapshots) : wrapped;
+}
+/** Project events after the fact (e.g. from a runtime hook). */
+export async function projectEvents(projectors, events) {
+    for (const projector of projectors) {
+        await projector.project(events);
+    }
+}
+/**
+ * Layer that decorates a base EventStore with projection.
+ */
+export function ProjectorsStoreLive(base, projectors, options) {
+    return Layer.succeed(EventStoreTag, withProjectors(base, projectors, options));
+}

package/dist/react/derived.d.ts

@@ -0,0 +1,19 @@
+import { type EventEnvelope, type ProjectionDefinition } from '@swirls/looms/core';
+import type { AnyEventEnvelope, RegisteredEvent } from './register';
+export type { AnyEventEnvelope } from './register';
+export { EventIndex, eventThreadKey } from '@swirls/looms/core';
+export interface EventFoldDefinition<S, TEvent extends AnyEventEnvelope = RegisteredEvent> {
+    readonly name?: string;
+    readonly initialState: S;
+    reduce(state: S, event: TEvent): S;
+    readonly includeEphemeral?: boolean;
+}
+export declare function createFold<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(def: EventFoldDefinition<S, TEvent>): EventFoldDefinition<S, TEvent>;
+export declare function foldEvents<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(definition: EventFoldDefinition<S, TEvent>, events: readonly TEvent[], from?: S): S;
+export declare class ProjectionCache {
+    private projectionCache;
+    private foldCache;
+    project<S>(definition: ProjectionDefinition<S>, events: readonly EventEnvelope[]): S;
+    fold<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(definition: EventFoldDefinition<S, TEvent>, events: readonly TEvent[]): S;
+    clear(): void;
+}

package/dist/react/derived.js

@@ -0,0 +1,50 @@
+import { project } from '@swirls/looms/core';
+export { EventIndex, eventThreadKey } from '@swirls/looms/core';
+export function createFold(def) {
+    return def;
+}
+export function foldEvents(definition, events, from) {
+    let state = from !== undefined ? from : definition.initialState;
+    const includeEphemeral = definition.includeEphemeral ?? false;
+    for (const event of events) {
+        if (event.ephemeral && !includeEphemeral) {
+            continue;
+        }
+        state = definition.reduce(state, event);
+    }
+    return state;
+}
+function advanceCache(cache, definition, events, compute) {
+    const total = events.length;
+    const cached = cache.get(definition);
+    if (!cached) {
+        const state = compute(definition, events);
+        cache.set(definition, { state, upTo: total });
+        return state;
+    }
+    if (cached.upTo === total) {
+        return cached.state;
+    }
+    if (cached.upTo < total) {
+        const state = compute(definition, events.slice(cached.upTo), cached.state);
+        cache.set(definition, { state, upTo: total });
+        return state;
+    }
+    const state = compute(definition, events);
+    cache.set(definition, { state, upTo: total });
+    return state;
+}
+export class ProjectionCache {
+    projectionCache = new WeakMap();
+    foldCache = new WeakMap();
+    project(definition, events) {
+        return advanceCache(this.projectionCache, definition, events, project);
+    }
+    fold(definition, events) {
+        return advanceCache(this.foldCache, definition, events, foldEvents);
+    }
+    clear() {
+        this.projectionCache = new WeakMap();
+        this.foldCache = new WeakMap();
+    }
+}

package/dist/react/index.d.ts

@@ -0,0 +1,6 @@
+export { createLoomsStore, type LoomsClientStore, type LoomsClientStoreOptions, type LoomsConnectionStatus, type LoomsStoreQuery, type CoalesceOption, type StoreListener, } from './store';
+export { createFold, foldEvents, EventIndex, eventThreadKey, type EventFoldDefinition, } from './derived';
+export { materializeEvents } from './materialize';
+export { emptyTables, type MaterializedTables, type RunRow, type ThreadRow } from './tables';
+export type { LoomsRegister, RegisteredEvent, AnyEventEnvelope } from './register';
+export { LoomsProvider, useRunStore, useProjection, useRunSelector, useRunSummary, useRunEvents, useThreadTree, useEventCounts, useEventBySeq, useLatestEvent, useEventFold, type LoomsProviderProps, type UseRunStoreOptions, type RunSummary, } from './react';

package/dist/react/index.js

@@ -0,0 +1,5 @@
+export { createLoomsStore, } from './store.js';
+export { createFold, foldEvents, EventIndex, eventThreadKey, } from './derived.js';
+export { materializeEvents } from './materialize.js';
+export { emptyTables } from './tables.js';
+export { LoomsProvider, useRunStore, useProjection, useRunSelector, useRunSummary, useRunEvents, useThreadTree, useEventCounts, useEventBySeq, useLatestEvent, useEventFold, } from './react.js';

package/dist/react/materialize.d.ts

@@ -0,0 +1,3 @@
+import { type EventEnvelope } from '@swirls/looms/core';
+import { type MaterializedTables } from './tables';
+export declare function materializeEvents(events: readonly EventEnvelope[], from?: MaterializedTables): MaterializedTables;

package/dist/react/materialize.js

@@ -0,0 +1,86 @@
+import { isJsonObject, isJsonString } from '@swirls/looms/core';
+import { emptyTables } from './tables.js';
+function payloadObject(event) {
+    return isJsonObject(event.payload) ? event.payload : {};
+}
+function readString(obj, key) {
+    const value = obj[key];
+    return isJsonString(value) ? value : undefined;
+}
+export function materializeEvents(events, from = emptyTables()) {
+    const tables = {
+        runs: from.runs,
+        threads: from.threads,
+    };
+    for (const event of events) {
+        const payload = payloadObject(event);
+        switch (event.type) {
+            case 'runtime.run.started': {
+                const existing = tables.runs.get(event.runId);
+                const rootThreadId = readString(payload, 'rootThreadId') ?? existing?.rootThreadId ?? null;
+                const next = {
+                    runId: event.runId,
+                    status: 'running',
+                    rootThreadId,
+                    kind: readString(payload, 'kind') ?? existing?.kind ?? null,
+                    definitionName: readString(payload, 'definitionName') ?? existing?.definitionName ?? null,
+                };
+                tables.runs.set(event.runId, next);
+                break;
+            }
+            case 'runtime.run.completed': {
+                const existing = tables.runs.get(event.runId);
+                tables.runs.set(event.runId, {
+                    runId: event.runId,
+                    status: readString(payload, 'error') ? 'failed' : 'completed',
+                    rootThreadId: existing?.rootThreadId ?? null,
+                    kind: existing?.kind ?? null,
+                    definitionName: existing?.definitionName ?? null,
+                });
+                break;
+            }
+            case 'runtime.thread.started': {
+                const threadId = readString(payload, 'threadId') ?? event.threadId;
+                const kind = readString(payload, 'kind');
+                const definitionName = readString(payload, 'definitionName');
+                if (!threadId || !kind || !definitionName) {
+                    break;
+                }
+                const parent = payload.parentThreadId;
+                const parentThreadId = parent === null || isJsonString(parent) ? parent : null;
+                const row = {
+                    threadId,
+                    runId: event.runId,
+                    kind,
+                    definitionName,
+                    parentThreadId,
+                    status: 'running',
+                };
+                tables.threads.set(threadId, row);
+                break;
+            }
+            case 'runtime.thread.completed':
+            case 'runtime.thread.failed':
+            case 'runtime.thread.cancelled': {
+                const threadId = readString(payload, 'threadId') ?? event.threadId;
+                if (!threadId) {
+                    break;
+                }
+                const existing = tables.threads.get(threadId);
+                if (!existing) {
+                    break;
+                }
+                const status = event.type === 'runtime.thread.completed'
+                    ? 'completed'
+                    : event.type === 'runtime.thread.failed'
+                        ? 'failed'
+                        : 'cancelled';
+                tables.threads.set(threadId, { ...existing, status });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return tables;
+}

package/dist/react/notify.d.ts

@@ -0,0 +1,18 @@
+/**
+ * How store→subscriber notifications are scheduled after events land.
+ *
+ * - `adaptive` (default): notify on the next macrotask when the stream is
+ *   quiet so UI can tick +1; under burst, coalesce to an animation frame.
+ * - `frame`: always at most one notify per animation frame.
+ * - `immediate`: notify synchronously on every apply (max granularity).
+ * - `{ delayMs }`: debounce-style timer coalesce.
+ */
+export type CoalesceOption = 'adaptive' | 'frame' | 'immediate' | {
+    delayMs: number;
+};
+export interface NotifyScheduler {
+    schedule: () => void;
+    flush: () => void;
+    cancel: () => void;
+}
+export declare function createNotifyScheduler(coalesce: CoalesceOption, onNotify: () => void): NotifyScheduler;

package/dist/react/notify.js

@@ -0,0 +1,80 @@
+import { Predicate } from 'effect';
+/** Quiet→burst threshold for `adaptive` coalesce (ms since last notify). */
+const ADAPTIVE_BURST_WINDOW_MS = 8;
+function nowMs() {
+    const perf = globalThis.performance;
+    return perf === undefined ? Date.now() : perf.now();
+}
+export function createNotifyScheduler(coalesce, onNotify) {
+    let notifyScheduled = false;
+    let notifyTimer;
+    let notifyRaf;
+    let lastNotifyAt = Number.NEGATIVE_INFINITY;
+    const fire = () => {
+        notifyScheduled = false;
+        notifyTimer = undefined;
+        notifyRaf = undefined;
+        lastNotifyAt = nowMs();
+        onNotify();
+    };
+    const scheduleFrame = () => {
+        if (Predicate.isFunction(globalThis.requestAnimationFrame)) {
+            notifyRaf = requestAnimationFrame(fire);
+        }
+        else {
+            notifyTimer = setTimeout(fire, 0);
+        }
+    };
+    const cancel = () => {
+        if (!notifyScheduled) {
+            return;
+        }
+        notifyScheduled = false;
+        if (notifyTimer !== undefined) {
+            clearTimeout(notifyTimer);
+            notifyTimer = undefined;
+        }
+        if (notifyRaf !== undefined && Predicate.isFunction(globalThis.cancelAnimationFrame)) {
+            cancelAnimationFrame(notifyRaf);
+            notifyRaf = undefined;
+        }
+    };
+    const schedule = () => {
+        if (coalesce === 'immediate') {
+            fire();
+            return;
+        }
+        if (notifyScheduled) {
+            return;
+        }
+        notifyScheduled = true;
+        if (coalesce === 'adaptive') {
+            const inBurst = nowMs() - lastNotifyAt < ADAPTIVE_BURST_WINDOW_MS;
+            if (inBurst) {
+                scheduleFrame();
+            }
+            else {
+                notifyTimer = setTimeout(fire, 0);
+            }
+            return;
+        }
+        if (coalesce === 'frame') {
+            scheduleFrame();
+            return;
+        }
+        if (Predicate.isObject(coalesce) && 'delayMs' in coalesce) {
+            const delayMs = Predicate.isNumber(coalesce.delayMs) ? Math.max(0, coalesce.delayMs) : 0;
+            notifyTimer = setTimeout(fire, delayMs);
+            return;
+        }
+        const _exhaustive = coalesce;
+        void _exhaustive;
+    };
+    const flush = () => {
+        if (notifyScheduled) {
+            cancel();
+            fire();
+        }
+    };
+    return { schedule, flush, cancel };
+}

package/dist/react/react.d.ts

@@ -0,0 +1,61 @@
+import { type ReactNode } from 'react';
+import { type ProjectionDefinition, type ThreadTree } from '@swirls/looms/core';
+import { createFold, foldEvents, type EventFoldDefinition } from './derived';
+import type { AnyEventEnvelope, RegisteredEvent } from './register';
+import { createLoomsStore, type CoalesceOption, type LoomsClientStore, type LoomsConnectionStatus } from './store';
+export interface LoomsProviderProps {
+    children: ReactNode;
+    endpoint?: string;
+    coalesce?: CoalesceOption;
+}
+interface ProviderContextValue {
+    endpoint: string;
+    coalesce?: CoalesceOption;
+}
+/** Root provider that supplies the Looms host endpoint to run stores. */
+export declare function LoomsProvider({ children, endpoint, coalesce }: LoomsProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<ProviderContextValue>>;
+export interface UseRunStoreOptions {
+    endpoint?: string;
+    reconnectDelayMs?: number;
+    coalesce?: CoalesceOption;
+}
+/**
+ * Acquires a non-subscribing handle to the run store.
+ * Retains the store in memory while mounted; does NOT trigger component re-renders.
+ * Use data hooks (`useRunEvents`, `useProjection`, `useRunSummary`, etc.) to subscribe.
+ */
+export declare function useRunStore<TEvent extends AnyEventEnvelope = RegisteredEvent>(runId: string, options?: UseRunStoreOptions): LoomsClientStore<TEvent>;
+/** Subscribe to incremental projection state, with optional slice selector. */
+export declare function useProjection<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, definition: ProjectionDefinition<S>): S;
+export declare function useProjection<S, Selected, TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, definition: ProjectionDefinition<S>, selector: (state: S) => Selected, isEqual?: (a: Selected, b: Selected) => boolean): Selected;
+/** Subscribe to arbitrary store derivations with an equality check. */
+export declare function useRunSelector<Selected, TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, selector: (store: LoomsClientStore<TEvent>) => Selected, isEqual?: (a: Selected, b: Selected) => boolean): Selected;
+export interface RunSummary {
+    readonly status: string;
+    readonly kind: string | undefined;
+    readonly definitionName: string | undefined;
+    readonly rootThreadId: string | undefined;
+    readonly startedAt: number | undefined;
+    readonly connection: LoomsConnectionStatus;
+}
+/** Lightweight subscription to top-level run metadata and connection status. */
+export declare function useRunSummary<TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>): RunSummary;
+/** Subscribe to the event log, optionally scoped to a single thread. */
+export declare function useRunEvents<TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, options?: {
+    threadId?: string;
+}): readonly TEvent[];
+/** Subscribe to the thread hierarchy tree. */
+export declare function useThreadTree<TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>): ThreadTree;
+/** Subscribe to event count per thread. */
+export declare function useEventCounts<TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>): ReadonlyMap<string, number>;
+/** Subscribe to a single event by its sequence number. */
+export declare function useEventBySeq<TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, seq: number | undefined): TEvent | undefined;
+/** Subscribe to the latest event of a given type. */
+export declare function useLatestEvent<TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, type: string): TEvent | undefined;
+/** Subscribe to a custom incremental fold. */
+export declare function useEventFold<S, TEvent extends AnyEventEnvelope = RegisteredEvent>(store: LoomsClientStore<TEvent>, fold: EventFoldDefinition<S, TEvent>): S;
+export { createLoomsStore };
+export { createFold, foldEvents };
+export type { LoomsClientStore, LoomsClientStoreOptions, LoomsConnectionStatus, LoomsStoreQuery, CoalesceOption, StoreListener, } from './store';
+export type { EventFoldDefinition } from './derived';
+export type { LoomsRegister, RegisteredEvent, AnyEventEnvelope } from './register';