@lostgradient/weft 0.2.0

package/dist/core/scheduler/duration.js

@@ -0,0 +1,48 @@
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|seconds?|m|minutes?|h|hours?|d|days?)$/i, UNIT_TO_MILLISECONDS = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1000,
+  second: 1000,
+  seconds: 1000,
+  m: 60000,
+  minute: 60000,
+  minutes: 60000,
+  h: 3600000,
+  hour: 3600000,
+  hours: 3600000,
+  d: 86400000,
+  day: 86400000,
+  days: 86400000
+};
+function assertValidDurationMilliseconds(milliseconds, source) {
+  if (!Number.isFinite(milliseconds) || milliseconds < 0)
+    throw RangeError(`Duration must resolve to a finite, non-negative number of milliseconds, got: ${String(source)}`);
+}
+export function normalizeStorageTimestamp(timestamp, fieldName) {
+  if (!Number.isFinite(timestamp) || timestamp < 0)
+    throw RangeError(`${fieldName} must resolve to a finite, non-negative millisecond timestamp, got: ${String(timestamp)}`);
+  const normalizedTimestamp = Math.ceil(timestamp);
+  if (!Number.isSafeInteger(normalizedTimestamp))
+    throw RangeError(`${fieldName} must resolve to a safe integer millisecond timestamp, got: ${String(timestamp)}`);
+  return normalizedTimestamp;
+}
+export function parseDuration(duration) {
+  if (typeof duration === "number") {
+    assertValidDurationMilliseconds(duration, duration);
+    return duration;
+  }
+  const match = DURATION_PATTERN.exec(duration.trim());
+  if (!match)
+    throw Error(`Invalid duration string: "${duration}". Expected a number or a string like "30s", "5 minutes", "1 hour", etc.`);
+  const value = Number.parseFloat(match[1]), unit = match[2].toLowerCase(), multiplier = UNIT_TO_MILLISECONDS[unit];
+  if (multiplier === void 0)
+    throw Error(`Unknown duration unit: "${unit}"`);
+  const milliseconds = value * multiplier;
+  assertValidDurationMilliseconds(milliseconds, duration);
+  return milliseconds;
+}
+export function calculateBackoff(attempt, policy) {
+  const initialMs = parseDuration(policy.initialBackoff), maxMs = parseDuration(policy.maxBackoff), raw = initialMs * Math.pow(policy.backoffMultiplier, attempt - 1);
+  return Math.min(raw, maxMs);
+}

package/dist/core/scheduler/index.d.ts

@@ -0,0 +1,4 @@
+export { calculateBackoff, normalizeStorageTimestamp, parseDuration } from './duration.ts';
+export { Scheduler } from './scheduler-class.ts';
+export type { SchedulerOptions } from './scheduler-class.ts';
+export { buildTimerBatchOperations, isTimerEntry } from './timer-batch.ts';

package/dist/core/scheduler/index.js

@@ -0,0 +1,3 @@
+export { calculateBackoff, normalizeStorageTimestamp, parseDuration } from "./duration.js";
+export { Scheduler } from "./scheduler-class.js";
+export { buildTimerBatchOperations, isTimerEntry } from "./timer-batch.js";

package/dist/core/scheduler/scheduler-class.d.ts

@@ -0,0 +1,52 @@
+import type { Storage } from '../../storage/interface.ts';
+import type { TimerEntry } from '../types.ts';
+export interface SchedulerOptions {
+    storage: Storage;
+    onTimerFired: (entry: TimerEntry) => void | Promise<void>;
+    pollIntervalMs?: number;
+    getNow?: () => number;
+}
+/**
+ * Scheduler manages durable timers and polls for expired deadlines.
+ *
+ * @example
+ * ```ts
+ * import { Scheduler } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const storage = new MemoryStorage();
+ * const scheduler = new Scheduler({
+ *   storage,
+ *   onTimerFired: (entry) => {
+ *     console.log('timer fired:', entry.id, entry.kind);
+ *   },
+ *   pollIntervalMs: 500,
+ * });
+ *
+ * scheduler.start();
+ * // ... use scheduler ...
+ * scheduler.stop();
+ * ```
+ */
+export declare class Scheduler implements Disposable {
+    #private;
+    constructor(options: SchedulerOptions);
+    /** Start the polling loop. */
+    start(): void;
+    /** Stop the polling loop. */
+    stop(): void;
+    /** Schedule a durable timer (writes to storage). */
+    schedule(entry: TimerEntry): Promise<void>;
+    /** Cancel a timer (removes from storage). */
+    cancel(id: string, _workflowId: string): Promise<void>;
+    /** Force an immediate scan for expired timers (for tests). */
+    tick(now?: number): Promise<void>;
+    /** Process all expired timers then stop.
+     *  Works even after stop() has been called — the intent is to drain remaining
+     *  timers before final shutdown. Bypasses the #stopped guard so a
+     *  stop()-then-flush() sequence works without re-enabling suspended interval
+     *  ticks that might race with this drain.
+     */
+    flush(now?: number): Promise<void>;
+    [Symbol.dispose](): void;
+}

package/dist/core/scheduler/scheduler-class.js

@@ -0,0 +1,167 @@
+import { KEYS, resolvePrefixRangeEnd } from "../../storage/interface.js";
+import { decode } from "../codec.js";
+import { buildTimerBatchOperations } from "./timer-batch.js";
+import {
+  advanceTimerSource,
+  readNextScannedTimerEntry,
+  readNextTerminalCleanupTimerEntry,
+  selectNextTimerSource,
+  shouldDeleteTimerIndexWithoutLookup
+} from "./timer-sources.js";
+
+export class Scheduler {
+  #storage;
+  #onTimerFired;
+  #pollIntervalMs;
+  #getNow;
+  #intervalHandle = null;
+  #stopped = !1;
+  constructor(options) {
+    this.#storage = options.storage;
+    this.#onTimerFired = options.onTimerFired;
+    this.#pollIntervalMs = options.pollIntervalMs ?? 1000;
+    this.#getNow = options.getNow ?? Date.now;
+  }
+  start() {
+    if (this.#intervalHandle !== null)
+      return;
+    this.#stopped = !1;
+    this.#intervalHandle = setInterval(() => {
+      this.tick();
+    }, this.#pollIntervalMs);
+  }
+  stop() {
+    this.#stopped = !0;
+    if (this.#intervalHandle !== null) {
+      clearInterval(this.#intervalHandle);
+      this.#intervalHandle = null;
+    }
+  }
+  async schedule(entry) {
+    await this.#storage.batch(buildTimerBatchOperations(entry));
+  }
+  async cancel(id, _workflowId) {
+    const indexKey = `timer-idx:${id}`, indexValue = await this.#storage.get(indexKey);
+    if (indexValue === null)
+      return;
+    const decoded = decode(indexValue);
+    if (typeof decoded !== "string") {
+      console.error(`Corrupted timer index for ${id}: expected string, got ${typeof decoded}`);
+      await this.#storage.delete(indexKey);
+      return;
+    }
+    const deadlineKey = decoded;
+    await this.#storage.batch([
+      { type: "delete", key: deadlineKey },
+      { type: "delete", key: indexKey }
+    ]);
+  }
+  async tick(now) {
+    if (this.#stopped)
+      return;
+    await this.#processExpiredTimers(now, { respectStopped: !0 });
+  }
+  async flush(now) {
+    await this.#processExpiredTimers(now, { respectStopped: !1 });
+    this.stop();
+  }
+  async#processExpiredTimers(now, { respectStopped }) {
+    const currentTime = now ?? this.#getNow(), timerSources = this.#createTimerSources(this.#scanExpiredTimers(currentTime));
+    for (const timerSource of timerSources)
+      await advanceTimerSource(timerSource, this.#storage);
+    while (this.#hasPendingTimer(timerSources)) {
+      const selectedSource = selectNextTimerSource(timerSources), nextEntry = selectedSource?.next;
+      if (!nextEntry || !selectedSource)
+        break;
+      if (respectStopped && this.#stopped)
+        return;
+      if (await this.#processSelectedTimer(nextEntry) === "retry") {
+        await advanceTimerSource(selectedSource, this.#storage);
+        continue;
+      }
+      await advanceTimerSource(selectedSource, this.#storage);
+    }
+  }
+  #scanExpiredTimers(currentTime) {
+    return {
+      deadline: this.#storage.scan("wf-deadline:", {
+        lt: resolvePrefixRangeEnd(KEYS.deadline(currentTime, ""))
+      }),
+      delayedStart: this.#storage.scan("wf-delayed:", {
+        lt: resolvePrefixRangeEnd(KEYS.delayedStart(currentTime, ""))
+      }),
+      schedule: this.#storage.scan("schedule-due:", {
+        lt: resolvePrefixRangeEnd(KEYS.scheduleTick(currentTime, ""))
+      }),
+      terminalCleanup: this.#storage.scan("wf-cleanup:", {
+        lt: resolvePrefixRangeEnd(KEYS.terminalCleanup(currentTime, ""))
+      })
+    };
+  }
+  #createTimerSources(iterators) {
+    return [
+      {
+        iterator: iterators.deadline[Symbol.asyncIterator](),
+        next: null,
+        readNext: readNextScannedTimerEntry
+      },
+      {
+        iterator: iterators.delayedStart[Symbol.asyncIterator](),
+        next: null,
+        readNext: readNextScannedTimerEntry
+      },
+      {
+        iterator: iterators.schedule[Symbol.asyncIterator](),
+        next: null,
+        readNext: readNextScannedTimerEntry
+      },
+      {
+        iterator: iterators.terminalCleanup[Symbol.asyncIterator](),
+        next: null,
+        readNext: readNextTerminalCleanupTimerEntry
+      }
+    ];
+  }
+  #hasPendingTimer(timerSources) {
+    return timerSources.some((timerSource) => timerSource.next !== null);
+  }
+  async#processSelectedTimer(nextEntry) {
+    try {
+      await this.#onTimerFired(nextEntry.entry);
+    } catch (error) {
+      console.error(`Timer callback failed for timer ${nextEntry.entry.id}:`, error);
+      return "retry";
+    }
+    await this.#deleteTimerKeysAfterCallback(nextEntry);
+    return "processed";
+  }
+  async#deleteTimerKeysAfterCallback(nextEntry) {
+    try {
+      await this.#storage.batch(await this.#buildTimerCleanupOperations(nextEntry));
+    } catch (deleteError) {
+      console.error(`Failed to delete timer keys for ${nextEntry.entry.id}:`, deleteError);
+    }
+  }
+  async#buildTimerCleanupOperations(nextEntry) {
+    const cleanupOperations = [{ type: "delete", key: nextEntry.key }], indexDeleteOperation = await this.#buildTimerIndexDeleteOperation(nextEntry);
+    if (indexDeleteOperation)
+      cleanupOperations.push(indexDeleteOperation);
+    return cleanupOperations;
+  }
+  async#buildTimerIndexDeleteOperation(nextEntry) {
+    const indexKey = `timer-idx:${nextEntry.entry.id}`;
+    if (nextEntry.entry.kind === "schedule")
+      return this.#buildScheduleTimerIndexDeleteOperation(nextEntry, indexKey);
+    return shouldDeleteTimerIndexWithoutLookup(nextEntry.entry) ? { type: "delete", key: indexKey } : null;
+  }
+  async#buildScheduleTimerIndexDeleteOperation(nextEntry, indexKey) {
+    const indexValue = await this.#storage.get(indexKey);
+    if (indexValue === null)
+      return null;
+    const decodedIndexValue = decode(indexValue);
+    return typeof decodedIndexValue !== "string" || decodedIndexValue === nextEntry.key ? { type: "delete", key: indexKey } : null;
+  }
+  [Symbol.dispose]() {
+    this.stop();
+  }
+}

package/dist/core/scheduler/timer-batch.d.ts

@@ -0,0 +1,10 @@
+import type { BatchOperation } from '../../storage/interface.ts';
+import type { TimerEntry } from '../types.ts';
+/** Runtime type guard for decoded timer entries. */
+export declare function isTimerEntry(value: unknown): value is TimerEntry;
+/**
+ * Build the batch operations needed to persist a durable timer entry.
+ * Shared between `Scheduler.schedule()` and `Engine.#buildStartBatchOperations()`
+ * so the key format stays in one place.
+ */
+export declare function buildTimerBatchOperations(entry: TimerEntry): BatchOperation[];

package/dist/core/scheduler/timer-batch.js

@@ -0,0 +1,42 @@
+import { KEYS } from "../../storage/interface.js";
+import { encode } from "../codec.js";
+import { normalizeStorageTimestamp } from "./duration.js";
+function isTimerEntryKind(value) {
+  return value === "sleep" || value === "visibility-timeout" || value === "execution-deadline" || value === "delayed-start" || value === "schedule" || value === "terminal-cleanup";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function hasStringProperty(value, property) {
+  return typeof value[property] === "string";
+}
+function hasFiniteNumberProperty(value, property) {
+  const propertyValue = value[property];
+  return typeof propertyValue === "number" && Number.isFinite(propertyValue);
+}
+export function isTimerEntry(value) {
+  return isRecord(value) && hasStringProperty(value, "id") && hasStringProperty(value, "workflowId") && hasFiniteNumberProperty(value, "fireAt") && isTimerEntryKind(value.kind);
+}
+export function buildTimerBatchOperations(entry) {
+  const normalizedEntry = {
+    ...entry,
+    fireAt: normalizeStorageTimestamp(entry.fireAt, "Timer fireAt")
+  };
+  if (normalizedEntry.kind === "terminal-cleanup")
+    return [
+      {
+        type: "put",
+        key: KEYS.terminalCleanup(normalizedEntry.fireAt, normalizedEntry.id),
+        value: encode(normalizedEntry.workflowId)
+      }
+    ];
+  const deadlineKey = normalizedEntry.kind === "delayed-start" ? KEYS.delayedStart(normalizedEntry.fireAt, normalizedEntry.workflowId) : normalizedEntry.kind === "schedule" ? KEYS.scheduleTick(normalizedEntry.fireAt, normalizedEntry.workflowId) : KEYS.deadline(normalizedEntry.fireAt, normalizedEntry.id), operations = [
+    { type: "put", key: deadlineKey, value: encode(normalizedEntry) }
+  ];
+  operations.push({
+    type: "put",
+    key: `timer-idx:${normalizedEntry.id}`,
+    value: encode(deadlineKey)
+  });
+  return operations;
+}

package/dist/core/scheduler/timer-sources.d.ts

@@ -0,0 +1,17 @@
+import type { Storage } from '../../storage/interface.ts';
+import type { TimerEntry } from '../types.ts';
+export type ScannedTimerEntry = {
+    key: string;
+    entry: TimerEntry;
+};
+export type TimerSource = {
+    iterator: AsyncIterator<[string, Uint8Array]>;
+    next: ScannedTimerEntry | null;
+    readNext: (iterator: AsyncIterator<[string, Uint8Array]>, storage: Storage) => Promise<ScannedTimerEntry | null>;
+};
+export declare function compareScannedTimerEntries(left: ScannedTimerEntry, right: ScannedTimerEntry): number;
+export declare function readNextScannedTimerEntry(iterator: AsyncIterator<[string, Uint8Array]>, storage: Storage): Promise<ScannedTimerEntry | null>;
+export declare function readNextTerminalCleanupTimerEntry(iterator: AsyncIterator<[string, Uint8Array]>, storage: Storage): Promise<ScannedTimerEntry | null>;
+export declare function advanceTimerSource(timerSource: TimerSource, storage: Storage): Promise<void>;
+export declare function selectNextTimerSource(timerSources: TimerSource[]): TimerSource | undefined;
+export declare function shouldDeleteTimerIndexWithoutLookup(entry: TimerEntry): boolean;

package/dist/core/scheduler/timer-sources.js

@@ -0,0 +1,61 @@
+import { tryDecodeStorageKeyComponent } from "../../storage/interface.js";
+import { decode } from "../codec.js";
+import { isTimerEntry } from "./timer-batch.js";
+export function compareScannedTimerEntries(left, right) {
+  if (left.entry.fireAt !== right.entry.fireAt)
+    return left.entry.fireAt - right.entry.fireAt;
+  return left.key.localeCompare(right.key);
+}
+export async function readNextScannedTimerEntry(iterator, storage) {
+  while (!0) {
+    const next = await iterator.next();
+    if (next.done)
+      return null;
+    const [key, value] = next.value, decoded = decode(value);
+    if (!isTimerEntry(decoded)) {
+      console.error(`Corrupted timer entry at ${key}: removing`);
+      await storage.delete(key);
+      continue;
+    }
+    return { key, entry: decoded };
+  }
+}
+export async function readNextTerminalCleanupTimerEntry(iterator, storage) {
+  const prefix = "wf-cleanup:";
+  while (!0) {
+    const next = await iterator.next();
+    if (next.done)
+      return null;
+    const [key, value] = next.value, separatorIndex = key.indexOf(":", prefix.length), fireAtValue = separatorIndex === -1 ? Number.NaN : Number(key.slice(prefix.length, separatorIndex)), timerId = separatorIndex === -1 ? null : tryDecodeStorageKeyComponent(key.slice(separatorIndex + 1)), decodedWorkflowId = decode(value);
+    if (!Number.isSafeInteger(fireAtValue) || fireAtValue < 0 || timerId === null || typeof decodedWorkflowId !== "string") {
+      console.error(`Corrupted terminal cleanup entry at ${key}: removing`);
+      await storage.delete(key);
+      continue;
+    }
+    return {
+      key,
+      entry: {
+        id: timerId,
+        workflowId: decodedWorkflowId,
+        fireAt: fireAtValue,
+        kind: "terminal-cleanup"
+      }
+    };
+  }
+}
+export async function advanceTimerSource(timerSource, storage) {
+  timerSource.next = await timerSource.readNext(timerSource.iterator, storage);
+}
+export function selectNextTimerSource(timerSources) {
+  let selectedSource;
+  for (const timerSource of timerSources) {
+    if (timerSource.next === null)
+      continue;
+    if (selectedSource === void 0 || compareScannedTimerEntries(timerSource.next, selectedSource.next) < 0)
+      selectedSource = timerSource;
+  }
+  return selectedSource;
+}
+export function shouldDeleteTimerIndexWithoutLookup(entry) {
+  return entry.kind !== "schedule" && entry.kind !== "terminal-cleanup";
+}

package/dist/core/scheduler.d.ts

@@ -0,0 +1 @@
+export * from './scheduler/index.ts';

package/dist/core/scheduler.js

@@ -0,0 +1 @@
+export * from "./scheduler/index.js";

package/dist/core/search-attributes.d.ts

@@ -0,0 +1,67 @@
+import type { BatchOperation } from '../storage/interface.ts';
+import type { SearchAttributeDefinition, SearchAttributeValue } from './types.ts';
+export { searchAttribute, searchAttributeName } from './types.ts';
+/**
+ * Maximum size in bytes for an encoded attribute value. Values exceeding this
+ * limit produce storage keys that may blow past backend size constraints.
+ */
+export declare const MAX_ENCODED_VALUE_BYTES = 1024;
+/**
+ * Encode a search attribute value to a sortable string for index keys.
+ *
+ * @example
+ * ```ts
+ * import { encodeAttributeValue } from '@lostgradient/weft';
+ *
+ * console.log(encodeAttributeValue('acme'));        // 's:acme'
+ * console.log(encodeAttributeValue(42));            // 'n:...' (sortable hex)
+ * console.log(encodeAttributeValue(true));          // 'b:1'
+ * console.log(encodeAttributeValue(new Date('2026-01-01'))); // 'd:2026-01-01T00:00:00.000Z'
+ * ```
+ */
+export declare function encodeAttributeValue(value: SearchAttributeValue): string;
+/**
+ * Validate that an encoded attribute value does not exceed the storage key size limit.
+ * Call this in the attribute-setting path, NOT in the general-purpose encoder — the encoder
+ * is also used to reconstruct old keys for deletion, and throwing there would prevent
+ * cleanup of pre-existing oversized values.
+ */
+export declare function validateEncodedValueSize(encoded: string, attributeName: string): void;
+/**
+ * Decode an encoded attribute value back to its original type.
+ *
+ * @example
+ * ```ts
+ * import { encodeAttributeValue, decodeAttributeValue } from '@lostgradient/weft';
+ *
+ * const encoded = encodeAttributeValue('acme');
+ * const decoded = decodeAttributeValue(encoded, 'string');
+ * console.log(decoded); // 'acme'
+ *
+ * const num = encodeAttributeValue(42);
+ * console.log(decodeAttributeValue(num, 'number')); // 42
+ * ```
+ */
+export declare function decodeAttributeValue(encoded: string, type: string): SearchAttributeValue;
+/**
+ * Validate that a value's runtime type matches the declared schema type.
+ * Throws a descriptive error on mismatch.
+ */
+export declare function validateAttributeType(attributeName: string, value: SearchAttributeValue, definition: SearchAttributeDefinition): void;
+/**
+ * Compute the diff between old and new attributes, returning BatchOperations for index updates.
+ *
+ * @example
+ * ```ts
+ * import { buildIndexOperations } from '@lostgradient/weft';
+ *
+ * const ops = buildIndexOperations(
+ *   'wf-123',
+ *   { status: 'pending' },
+ *   { status: 'completed', customerId: 'acme' },
+ * );
+ * // ops: delete old 'status' index key, put new 'status' key, put 'customerId' key
+ * console.log(ops.length > 0); // true
+ * ```
+ */
+export declare function buildIndexOperations(workflowId: string, previous: Record<string, SearchAttributeValue>, current: Record<string, SearchAttributeValue>): BatchOperation[];