@swirls/looms 0.0.2 → 0.2.0

package/dist/runtime/worker-effect-dispatch.js

@@ -0,0 +1,126 @@
+import { Effect, Predicate } from 'effect';
+import { createEvent, isPrimitiveEffect, } from '@swirls/looms/core';
+import { RuntimeExecutionError } from './errors.js';
+import { workerTask } from './helpers.js';
+function workerClaims(worker, runId, item) {
+    if (!worker.handles && !worker.canDispatch) {
+        return undefined;
+    }
+    const { handles } = worker;
+    const handled = Predicate.isFunction(handles)
+        ? handles(item.effect.type)
+        : (handles?.includes(item.effect.type) ?? false);
+    return handled || (worker.canDispatch?.(workerTask(runId, item, 0)) ?? false);
+}
+const WORKER_ATTEMPT_STATUSES = new Set([
+    'queued',
+    'dispatched',
+    'started',
+    'heartbeat',
+    'cancel_requested',
+    'timed_out',
+    'ambiguous',
+]);
+/**
+ * Decides where an outstanding effect runs. An attempt already in flight keeps
+ * its durable placement. Otherwise an explicit `execution` wins, then a worker
+ * claim; effects with a local handler run in process and handler-less effects
+ * go to the worker.
+ */
+export function isWorkerEffect(input) {
+    const { item, execution, worker } = input;
+    if (isPrimitiveEffect(item.effect)) {
+        return false;
+    }
+    if (execution?.status === 'running') {
+        return false;
+    }
+    if (execution && WORKER_ATTEMPT_STATUSES.has(execution.status)) {
+        return true;
+    }
+    const definition = input.registry.effects.get(item.effect.type);
+    if (definition?.execution) {
+        return definition.execution === 'worker';
+    }
+    const claim = worker ? workerClaims(worker, input.runId, item) : undefined;
+    if (claim) {
+        return true;
+    }
+    if (definition) {
+        return !definition.hasHandler;
+    }
+    return worker !== undefined && claim !== false;
+}
+export function planWorkerEffects(input) {
+    return input.state.outstandingEffects
+        .filter((item) => {
+        const execution = input.state.effectExecutions[item.effectId];
+        if (!isWorkerEffect({ ...input, item, execution })) {
+            return false;
+        }
+        return (!execution ||
+            execution.status === 'queued' ||
+            (execution.status === 'retry_wait' &&
+                execution.nextAttemptAt !== null &&
+                execution.nextAttemptAt <= input.now + 5));
+    })
+        .map((item) => {
+        const existing = input.state.effectExecutions[item.effectId];
+        const attempt = existing?.status === 'queued' ? existing.attempt : (existing?.attempt ?? 0) + 1;
+        const retry = input.registry.effects.get(item.effect.type)?.retry;
+        return {
+            item,
+            attempt,
+            queuedEvent: existing?.status === 'queued'
+                ? undefined
+                : createEvent(input.runId, {
+                    type: 'runtime.effect.queued',
+                    payload: { effectId: item.effectId, attempt, deadlineAt: null },
+                    threadId: item.threadId,
+                    causationId: item.causingEventId,
+                    origin: { type: 'system' },
+                }),
+            task: workerTask(input.runId, item, attempt),
+            scheduleToStartDeadlineAt: retry?.scheduleToStartTimeoutMs
+                ? input.now + retry.scheduleToStartTimeoutMs
+                : null,
+        };
+    });
+}
+/**
+ * Hand a planned attempt to the worker. A rejected dispatch may still have reached the worker, so
+ * with a schedule-to-start deadline it is recorded as dispatched and recovered by that timeout;
+ * without one it is parked as ambiguous for an operator.
+ */
+export function dispatchWorkerEffect(runId, plan, worker) {
+    const dispatched = createEvent(runId, {
+        type: 'runtime.effect.dispatched',
+        payload: {
+            effectId: plan.item.effectId,
+            attempt: plan.attempt,
+            deadlineAt: plan.scheduleToStartDeadlineAt,
+        },
+        threadId: plan.item.threadId,
+        causationId: plan.item.causingEventId,
+        origin: { type: 'system' },
+    });
+    const ambiguous = (error) => createEvent(runId, {
+        type: 'runtime.effect.ambiguous',
+        payload: { effectId: plan.item.effectId, attempt: plan.attempt, error },
+        threadId: plan.item.threadId,
+        causationId: plan.item.causingEventId,
+        origin: { type: 'system' },
+    });
+    if (!worker) {
+        return Effect.succeed(ambiguous(`no effect worker is configured for "${plan.item.effect.type}"`));
+    }
+    return Effect.tryPromise({
+        try: () => Promise.resolve(worker.dispatch(plan.task)),
+        catch: (cause) => new RuntimeExecutionError(cause instanceof Error ? cause.message : String(cause)),
+    }).pipe(Effect.match({
+        onFailure: (error) => plan.scheduleToStartDeadlineAt === null
+            ? ambiguous(`worker dispatch outcome is ambiguous: ${error.message}`)
+            : dispatched,
+        onSuccess: () => dispatched,
+    }));
+}

package/dist/s2/config.d.ts

@@ -14,7 +14,7 @@ export declare const S2ConfigSchema: Schema.Struct<{
     }>]>>;
     readonly streamConfig: Schema.optional<Schema.Struct<{
         readonly retentionPolicy: Schema.optional<Schema.Union<readonly [Schema.Struct<{
-            readonly ageSecs: Schema.Number;
+            readonly ageSecs: Schema.Finite;
         }>, Schema.Struct<{
             readonly infinite: Schema.Struct<{}>;
         }>]>>;

package/dist/s2/config.js

@@ -17,7 +17,7 @@ export const S2ConfigSchema = Schema.Struct({
     ])),
     streamConfig: Schema.optional(Schema.Struct({
         retentionPolicy: Schema.optional(Schema.Union([
-            Schema.Struct({ ageSecs: Schema.Number }),
+            Schema.Struct({ ageSecs: Schema.Finite }),
             Schema.Struct({ infinite: Schema.Struct({}) }),
         ])),
         storageClass: Schema.optional(Schema.Literals(['standard', 'express'])),

package/dist/s2/lite.js

@@ -3,7 +3,14 @@ import * as fs from 'node:fs';
 import * as net from 'node:net';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { Clock, Data, Effect } from 'effect';
 import { s2 } from './store.js';
+class S2LiteError extends Data.TaggedError('S2LiteError') {
+    constructor(message, cause) {
+        super({ cause, message });
+        this.name = 'S2LiteError';
+    }
+}
 export function findS2Binary(env) {
     // 1. Check PATH
     const pathDirs = (env.PATH ?? '').split(path.delimiter);
@@ -48,103 +55,84 @@ export function findS2Binary(env) {
     return undefined;
 }
 export function isPortOpen(port, host = '127.0.0.1') {
-    return new Promise((resolve) => {
+    return Effect.runPromise(Effect.callback((resume) => {
         const socket = new net.Socket();
-        socket.setTimeout(200);
-        socket.once('connect', () => {
-            socket.destroy();
-            resolve(true);
-        });
-        socket.once('timeout', () => {
-            socket.destroy();
-            resolve(false);
-        });
-        socket.once('error', () => {
+        const complete = (open) => {
             socket.destroy();
-            resolve(false);
-        });
+            resume(Effect.succeed(open));
+        };
+        socket.setTimeout(200);
+        socket.once('connect', () => complete(true));
+        socket.once('timeout', () => complete(false));
+        socket.once('error', () => complete(false));
         socket.connect(port, host);
-    });
+        return Effect.sync(() => socket.destroy());
+    }));
 }
 let activeProcess = null;
-export async function startS2Lite(options = {}) {
-    const port = options.port ?? 8080;
-    const endpoint = `http://127.0.0.1:${port}`;
-    // 1. Check if an s2-lite instance is already responding on this port.
-    const alreadyRunning = await isPortOpen(port);
-    if (alreadyRunning) {
-        return {
-            port,
-            endpoint,
-            stop: () => {
-                // Did not spawn this process, no-op stop.
-            },
-        };
-    }
-    // 2. Locate the s2 binary.
-    const binaryPath = options.binaryPath ?? findS2Binary(options.env ?? {});
-    if (!binaryPath) {
-        throw new Error(`s2 CLI binary not found on PATH or in standard locations.
+export function startS2Lite(options = {}) {
+    return Effect.runPromise(Effect.gen(function* () {
+        const port = options.port ?? 8080;
+        const endpoint = `http://127.0.0.1:${port}`;
+        if (yield* Effect.promise(() => isPortOpen(port))) {
+            return { port, endpoint, stop: () => undefined };
+        }
+        const binaryPath = options.binaryPath ?? findS2Binary(options.env ?? {});
+        if (!binaryPath) {
+            return yield* new S2LiteError(`s2 CLI binary not found on PATH or in standard locations.
 To install s2-lite for local development:
   flox activate          # installs into $FLOX_ENV_CACHE/s2 (preferred)
   bun run setup:s2       # scripts/install-s2-cli.sh
   https://s2.dev/docs/cli/installation`);
-    }
-    // 3. Spawn s2 lite.
-    // SAFETY: child_process.spawn returns child process matching S2ChildProcess.
-    const child = childProcess.spawn(binaryPath, ['lite', '--port', String(port)], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-        detached: false,
-    });
-    activeProcess = child;
-    const cleanup = () => {
-        if (activeProcess === child) {
-            activeProcess = null;
         }
-        try {
-            child.kill('SIGTERM');
-        }
-        catch {
-            // Process may already have exited.
-        }
-    };
-    process.once('exit', cleanup);
-    process.once('SIGINT', cleanup);
-    process.once('SIGTERM', cleanup);
-    let stderrOutput = '';
-    child.stderr?.on('data', (chunk) => {
-        stderrOutput += chunk.toString();
-    });
-    // 4. Poll until the port responds or the process exits unexpectedly.
-    const deadline = Date.now() + 5000;
-    while (Date.now() < deadline) {
-        if (child.exitCode !== null) {
-            throw new Error(`s2 lite process exited with code ${child.exitCode} before becoming ready: ${stderrOutput}`);
-        }
-        const ready = await isPortOpen(port);
-        if (ready) {
-            return {
-                port,
-                endpoint,
-                stop: cleanup,
-            };
+        const child = yield* Effect.try({
+            try: () => childProcess.spawn(binaryPath, ['lite', '--port', String(port)], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                detached: false,
+            }),
+            catch: (cause) => new S2LiteError('Failed to start s2 lite', cause),
+        });
+        activeProcess = child;
+        const cleanup = () => {
+            if (activeProcess === child) {
+                activeProcess = null;
+            }
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // The process may already have exited.
+            }
+        };
+        process.once('exit', cleanup);
+        process.once('SIGINT', cleanup);
+        process.once('SIGTERM', cleanup);
+        let stderrOutput = '';
+        child.stderr?.on('data', (chunk) => {
+            stderrOutput += chunk.toString();
+        });
+        const deadline = (yield* Clock.currentTimeMillis) + 5_000;
+        while ((yield* Clock.currentTimeMillis) < deadline) {
+            if (child.exitCode !== null) {
+                return yield* new S2LiteError(`s2 lite process exited with code ${child.exitCode} before becoming ready: ${stderrOutput}`);
+            }
+            if (yield* Effect.promise(() => isPortOpen(port))) {
+                return { port, endpoint, stop: cleanup };
+            }
+            yield* Effect.sleep(50);
         }
-        await new Promise((r) => setTimeout(r, 50));
-    }
-    cleanup();
-    throw new Error(`Timed out waiting for s2 lite to start on port ${port}: ${stderrOutput}`);
+        cleanup();
+        return yield* new S2LiteError(`Timed out waiting for s2 lite to start on port ${port}: ${stderrOutput}`);
+    }));
 }
 /**
  * Returns a factory function for createLooms that automatically starts local s2-lite
  * and connects an S2 EventStore to it.
  */
 export function s2Lite(options = {}) {
-    return async () => {
-        const started = await startS2Lite(options);
-        return s2({
-            basin: options.basin ?? 'looms-demo',
-            accessToken: options.accessToken ?? 's2_local',
-            endpoint: started.endpoint,
-        });
-    };
+    return () => startS2Lite(options).then((started) => s2({
+        basin: options.basin ?? 'looms-demo',
+        accessToken: options.accessToken ?? 's2_local',
+        endpoint: started.endpoint,
+    }));
 }

package/dist/s2/pagination.d.ts

@@ -0,0 +1,15 @@
+import { Effect, Stream } from 'effect';
+export interface S2ReadBatchLike<T> {
+    readonly records: ReadonlyArray<T>;
+    readonly tail?: {
+        readonly seqNum: number;
+    } | null;
+}
+export interface ReadAllPagesOptions {
+    readonly fromSeq?: number;
+    readonly limit?: number;
+    readonly maxPageSize?: number;
+}
+export declare function paginateS2Stream<T extends {
+    readonly seqNum: number;
+}, E>(fetchPage: (cursor: number, count: number) => Effect.Effect<S2ReadBatchLike<T> | null, E>, options?: ReadAllPagesOptions): Stream.Stream<T, E>;

package/dist/s2/pagination.js

@@ -0,0 +1,36 @@
+import { Effect, Option, Stream } from 'effect';
+export function paginateS2Stream(fetchPage, options) {
+    const fromSeq = options?.fromSeq ?? 0;
+    const userLimit = options?.limit;
+    const maxPageSize = options?.maxPageSize ?? 1000;
+    if (userLimit !== undefined && userLimit <= 0) {
+        return Stream.empty;
+    }
+    const baseStream = Stream.paginate({ cursor: fromSeq, remaining: userLimit }, (state) => Effect.gen(function* () {
+        if (state.remaining !== undefined && state.remaining <= 0) {
+            return [[], Option.none()];
+        }
+        const count = state.remaining !== undefined ? Math.min(maxPageSize, state.remaining) : maxPageSize;
+        const page = yield* fetchPage(state.cursor, count);
+        if (!page || page.records.length === 0) {
+            return [[], Option.none()];
+        }
+        const records = page.records.filter((record) => record.seqNum >= fromSeq);
+        const nextRemaining = state.remaining !== undefined ? state.remaining - records.length : undefined;
+        const lastRecord = page.records[page.records.length - 1];
+        if (!lastRecord || (nextRemaining !== undefined && nextRemaining <= 0)) {
+            return [records, Option.none()];
+        }
+        const nextCursor = Math.max(state.cursor + 1, lastRecord.seqNum + 1);
+        if (nextCursor <= state.cursor) {
+            return [records, Option.none()];
+        }
+        // Byte-capped pages can be shorter than requested while more records remain.
+        const shortPage = page.records.length < count;
+        const reachedTail = !shortPage && page.tail?.seqNum !== undefined && nextCursor >= page.tail.seqNum;
+        return reachedTail
+            ? [records, Option.none()]
+            : [records, Option.some({ cursor: nextCursor, remaining: nextRemaining })];
+    }));
+    return userLimit !== undefined ? baseStream.pipe(Stream.take(userLimit)) : baseStream;
+}

package/dist/s2/projector.js

@@ -10,9 +10,10 @@ export function s2Projector(config) {
     const store = s2(config);
     return {
         name: 's2',
-        project: async (events) => {
+        version: '1',
+        project: (events) => {
             if (events.length === 0) {
-                return;
+                return Promise.resolve();
             }
             const byRun = new Map();
             for (const event of events) {
@@ -20,9 +21,9 @@ export function s2Projector(config) {
                 batch.push(event);
                 byRun.set(event.runId, batch);
             }
-            for (const [runId, batch] of byRun) {
-                await Effect.runPromise(store.append(runId, batch));
-            }
+            return Effect.runPromise(Effect.forEach(byRun, ([runId, batch]) => store.append(runId, batch), {
+                discard: true,
+            }));
         },
     };
 }