awaitly 2.0.0 → 3.0.0

package/dist/persistence.js

@@ -0,0 +1,499 @@
+// src/core/index.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error, options) {
+  const cause = options?.cause;
+  return { ok: false, error, ...cause !== void 0 ? { cause } : {} };
+}
+
+// src/workflow/guards.ts
+function isResumeState(x) {
+  return typeof x === "object" && x !== null && "steps" in x && x.steps instanceof Map;
+}
+
+// src/persistence.ts
+var SnapshotFormatError = class extends Error {
+  constructor(message, errors = []) {
+    super(message);
+    this.errors = errors;
+    this.name = "SnapshotFormatError";
+  }
+  errors;
+};
+var SnapshotMismatchError = class extends Error {
+  constructor(message, mismatchType, details) {
+    super(message);
+    this.mismatchType = mismatchType;
+    this.details = details;
+    this.name = "SnapshotMismatchError";
+  }
+  mismatchType;
+  details;
+};
+var SnapshotDecodeError = class extends Error {
+  constructor(message, stepId, originalError) {
+    super(message);
+    this.stepId = stepId;
+    this.originalError = originalError;
+    this.name = "SnapshotDecodeError";
+  }
+  stepId;
+  originalError;
+};
+function looksLikeWorkflowSnapshot(obj) {
+  return typeof obj === "object" && obj !== null && "formatVersion" in obj && obj.formatVersion === 1 && "steps" in obj && typeof obj.steps === "object" && obj.steps !== null && "execution" in obj && typeof obj.execution === "object";
+}
+var isWorkflowSnapshot = looksLikeWorkflowSnapshot;
+function validateSnapshot(obj) {
+  const errors = [];
+  if (typeof obj !== "object" || obj === null) {
+    return { valid: false, errors: ["Snapshot must be an object"] };
+  }
+  const snapshot = obj;
+  if (!("formatVersion" in snapshot)) {
+    errors.push("Missing required field: formatVersion");
+  } else if (snapshot.formatVersion !== 1) {
+    errors.push(`Invalid formatVersion: expected 1, got ${snapshot.formatVersion}`);
+  }
+  if (!("steps" in snapshot)) {
+    errors.push("Missing required field: steps");
+  } else if (typeof snapshot.steps !== "object" || snapshot.steps === null) {
+    errors.push("steps must be an object");
+  } else {
+    const steps = snapshot.steps;
+    for (const [stepId, stepResult] of Object.entries(steps)) {
+      if (typeof stepResult !== "object" || stepResult === null) {
+        errors.push(`steps["${stepId}"] must be an object`);
+        continue;
+      }
+      const step = stepResult;
+      if (!("ok" in step)) {
+        errors.push(`steps["${stepId}"] missing required field: ok`);
+      } else if (typeof step.ok !== "boolean") {
+        errors.push(`steps["${stepId}"].ok must be a boolean`);
+      } else if (step.ok === false) {
+        if (!("error" in step)) {
+          errors.push(`steps["${stepId}"] is error result but missing error field`);
+        }
+        if (!("cause" in step)) {
+          errors.push(`steps["${stepId}"] is error result but missing cause field`);
+        }
+      }
+    }
+  }
+  if (!("execution" in snapshot)) {
+    errors.push("Missing required field: execution");
+  } else if (typeof snapshot.execution !== "object" || snapshot.execution === null) {
+    errors.push("execution must be an object");
+  } else {
+    const execution = snapshot.execution;
+    if (!("status" in execution)) {
+      errors.push("execution missing required field: status");
+    } else if (!["running", "completed", "failed"].includes(execution.status)) {
+      errors.push(`execution.status must be one of: running, completed, failed`);
+    }
+    if (!("lastUpdated" in execution)) {
+      errors.push("execution missing required field: lastUpdated");
+    } else if (typeof execution.lastUpdated !== "string") {
+      errors.push("execution.lastUpdated must be a string (ISO timestamp)");
+    }
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return { valid: true, snapshot: obj };
+}
+function assertValidSnapshot(obj) {
+  const result = validateSnapshot(obj);
+  if (!result.valid) {
+    throw new SnapshotFormatError(`Invalid snapshot format: ${result.errors[0]}`, result.errors);
+  }
+  return result.snapshot;
+}
+function mergeSnapshots(base, delta) {
+  const mergedSteps = /* @__PURE__ */ Object.create(null);
+  for (const [key, value] of Object.entries(base.steps)) {
+    if (Object.prototype.hasOwnProperty.call(base.steps, key)) {
+      mergedSteps[key] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(delta.steps)) {
+    if (Object.prototype.hasOwnProperty.call(delta.steps, key)) {
+      mergedSteps[key] = value;
+    }
+  }
+  const mergedMetadata = base.metadata || delta.metadata ? { ...base.metadata, ...delta.metadata } : void 0;
+  const baseWarnings = (base.warnings || []).filter(
+    (w) => !Object.prototype.hasOwnProperty.call(delta.steps, w.stepId)
+  );
+  const mergedWarnings = [...baseWarnings, ...delta.warnings || []];
+  return {
+    formatVersion: 1,
+    steps: mergedSteps,
+    execution: { ...delta.execution },
+    metadata: mergedMetadata,
+    warnings: mergedWarnings.length > 0 ? mergedWarnings : void 0
+  };
+}
+var MAX_STRING_REPRESENTATION_LENGTH = 1e3;
+function serializeError(error) {
+  const serialized = {
+    type: "error",
+    name: error.name,
+    message: error.message
+  };
+  if (error.stack) {
+    serialized.stack = error.stack;
+  }
+  const errorWithCause = error;
+  if (errorWithCause.cause !== void 0) {
+    if (errorWithCause.cause instanceof Error) {
+      serialized.cause = serializeError(errorWithCause.cause);
+    } else {
+      serialized.cause = serializeThrown(errorWithCause.cause);
+    }
+  }
+  return serialized;
+}
+function serializeThrown(value) {
+  let stringRepresentation;
+  let truncated = false;
+  try {
+    stringRepresentation = String(value);
+    if (stringRepresentation.length > MAX_STRING_REPRESENTATION_LENGTH) {
+      stringRepresentation = stringRepresentation.slice(0, MAX_STRING_REPRESENTATION_LENGTH);
+      truncated = true;
+    }
+  } catch {
+    stringRepresentation = "[unable to convert to string]";
+  }
+  const originalType = value === null ? "null" : typeof value === "object" ? value.constructor?.name ?? "Object" : typeof value;
+  let jsonValue;
+  try {
+    const serialized = JSON.stringify(value);
+    if (serialized !== void 0) {
+      jsonValue = JSON.parse(serialized);
+    }
+  } catch {
+  }
+  const result = {
+    type: "thrown",
+    originalType,
+    stringRepresentation
+  };
+  if (jsonValue !== void 0) {
+    result.value = jsonValue;
+  }
+  if (truncated) {
+    result.truncated = true;
+  }
+  return result;
+}
+function deserializeCauseNew(serialized) {
+  if (serialized.type === "error") {
+    const error = new Error(serialized.message);
+    error.name = serialized.name;
+    if (serialized.stack) {
+      error.stack = serialized.stack;
+    }
+    if (serialized.cause) {
+      error.cause = deserializeCauseNew(serialized.cause);
+    }
+    return error;
+  }
+  return serialized.value !== void 0 ? serialized.value : serialized.stringRepresentation;
+}
+function createMemoryCache(options = {}) {
+  const { maxSize, ttl } = options;
+  const cache = /* @__PURE__ */ new Map();
+  const isExpired = (entry) => {
+    const effectiveTtl = entry.entryTtl ?? ttl;
+    if (!effectiveTtl) return false;
+    return Date.now() - entry.timestamp > effectiveTtl;
+  };
+  const evictExpired = () => {
+    for (const [key, entry] of cache) {
+      if (isExpired(entry)) {
+        cache.delete(key);
+      }
+    }
+  };
+  const evictOldest = () => {
+    if (!maxSize || cache.size < maxSize) return;
+    let oldestKey;
+    let oldestTime = Infinity;
+    for (const [key, entry] of cache) {
+      if (entry.timestamp < oldestTime) {
+        oldestTime = entry.timestamp;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey) {
+      cache.delete(oldestKey);
+    }
+  };
+  return {
+    get(key) {
+      evictExpired();
+      const entry = cache.get(key);
+      if (!entry) return void 0;
+      if (isExpired(entry)) {
+        cache.delete(key);
+        return void 0;
+      }
+      return entry.result;
+    },
+    set(key, result, options2) {
+      evictExpired();
+      evictOldest();
+      cache.set(key, { result, timestamp: Date.now(), entryTtl: options2?.ttl });
+    },
+    has(key) {
+      evictExpired();
+      const entry = cache.get(key);
+      if (!entry) return false;
+      if (isExpired(entry)) {
+        cache.delete(key);
+        return false;
+      }
+      return true;
+    },
+    delete(key) {
+      return cache.delete(key);
+    },
+    clear() {
+      cache.clear();
+    }
+  };
+}
+
+// src/workflow/cache-encoding.ts
+function isCachedErrorCause(cause) {
+  return typeof cause === "object" && cause !== null && cause.__cachedMeta === true;
+}
+function encodeCachedError(error, meta, originalCause) {
+  return err(error, {
+    cause: { __cachedMeta: true, originalCause, meta }
+  });
+}
+
+// src/workflow/serialize-resume-state.ts
+function serializeResumeState(state) {
+  const steps = [];
+  for (const [key, entry] of state.steps) {
+    const stepResult = entryToStepResult(entry);
+    steps.push([key, stepResult]);
+  }
+  return { kind: "ResumeState", steps };
+}
+function isSerializedResumeState(x) {
+  return typeof x === "object" && x !== null && x.kind === "ResumeState" && Array.isArray(x.steps);
+}
+function deserializeResumeState(raw) {
+  const steps = /* @__PURE__ */ new Map();
+  for (const [key, stepResult] of raw.steps) {
+    steps.set(key, stepResultToEntry(stepResult));
+  }
+  return { steps };
+}
+function entryToStepResult(entry) {
+  const { result, meta } = entry;
+  if (result.ok) {
+    return { ok: true, value: result.value };
+  }
+  const causeToSerialize = isCachedErrorCause(result.cause) ? result.cause.originalCause : result.cause;
+  const serializedCause = causeToSerialize instanceof Error ? serializeError(causeToSerialize) : serializeThrown(causeToSerialize);
+  const origin = meta?.origin === "throw" ? "throw" : "result";
+  return {
+    ok: false,
+    error: result.error,
+    cause: serializedCause,
+    meta: { origin }
+  };
+}
+function stepResultToEntry(sr) {
+  if (sr.ok) {
+    return { result: ok(sr.value) };
+  }
+  const deserializedCause = deserializeCauseNew(sr.cause);
+  const meta = sr.meta?.origin === "throw" ? { origin: "throw", thrown: deserializedCause } : { origin: "result", resultCause: deserializedCause };
+  const errorResult = encodeCachedError(sr.error, meta, deserializedCause);
+  return { result: errorResult, meta };
+}
+
+// src/workflow/store-contract.ts
+function toResumeState(loaded) {
+  if (loaded === null) return void 0;
+  if (isResumeState(loaded)) return loaded;
+  return void 0;
+}
+
+// src/versioning.ts
+function isMigrationError(error) {
+  return typeof error === "object" && error !== null && error.type === "MIGRATION_ERROR";
+}
+function isVersionIncompatibleError(error) {
+  return typeof error === "object" && error !== null && error.type === "VERSION_INCOMPATIBLE";
+}
+async function migrateState(state, targetVersion, migrations) {
+  let currentState = state.state;
+  let currentVersion = state.version;
+  if (currentVersion > targetVersion) {
+    return err({
+      type: "VERSION_INCOMPATIBLE",
+      stateVersion: currentVersion,
+      currentVersion: targetVersion,
+      reason: "State version is higher than current workflow version. Cannot downgrade."
+    });
+  }
+  if (currentVersion === targetVersion) {
+    return ok({ version: currentVersion, state: currentState });
+  }
+  while (currentVersion < targetVersion) {
+    const migration = migrations[currentVersion];
+    if (!migration) {
+      return err({
+        type: "VERSION_INCOMPATIBLE",
+        stateVersion: state.version,
+        currentVersion: targetVersion,
+        reason: `No migration found for version ${currentVersion} to ${currentVersion + 1}`
+      });
+    }
+    try {
+      currentState = await migration(currentState);
+      currentVersion++;
+    } catch (cause) {
+      return err({
+        type: "MIGRATION_ERROR",
+        fromVersion: currentVersion,
+        toVersion: currentVersion + 1,
+        cause
+      });
+    }
+  }
+  return ok({ version: currentVersion, state: currentState });
+}
+function createVersionedStateLoader(config) {
+  const { version, migrations = {}, strictVersioning = true } = config;
+  return async (versionedState) => {
+    if (!versionedState) {
+      return ok(void 0);
+    }
+    if (strictVersioning && versionedState.version > version) {
+      return err({
+        type: "VERSION_INCOMPATIBLE",
+        stateVersion: versionedState.version,
+        currentVersion: version,
+        reason: "Saved state is from a newer workflow version"
+      });
+    }
+    if (versionedState.version === version) {
+      return ok(versionedState.state);
+    }
+    const result = await migrateState(versionedState, version, migrations);
+    if (!result.ok) {
+      return result;
+    }
+    return ok(result.value.state);
+  };
+}
+function createVersionedState(state, version) {
+  return { version, state };
+}
+function parseVersionedState(json) {
+  if (!json) return null;
+  try {
+    const parsed = typeof json === "string" ? JSON.parse(json) : json;
+    if (typeof parsed !== "object" || parsed === null || !("version" in parsed) || typeof parsed.version !== "number" || !("state" in parsed) || !parsed.state || !Array.isArray(parsed.state.steps)) {
+      return null;
+    }
+    const typedParsed = parsed;
+    const steps = new Map(typedParsed.state.steps);
+    return {
+      version: typedParsed.version,
+      state: { steps }
+    };
+  } catch {
+    return null;
+  }
+}
+function stringifyVersionedState(state) {
+  return JSON.stringify({
+    version: state.version,
+    state: {
+      steps: Array.from(state.state.steps.entries())
+    }
+  });
+}
+function createKeyRenameMigration(renames) {
+  return (state) => {
+    const newSteps = /* @__PURE__ */ new Map();
+    for (const [key, entry] of state.steps) {
+      const newKey = renames[key] ?? key;
+      newSteps.set(newKey, entry);
+    }
+    return { steps: newSteps };
+  };
+}
+function createKeyRemoveMigration(keysToRemove) {
+  const keysSet = new Set(keysToRemove);
+  return (state) => {
+    const newSteps = /* @__PURE__ */ new Map();
+    for (const [key, entry] of state.steps) {
+      if (!keysSet.has(key)) {
+        newSteps.set(key, entry);
+      }
+    }
+    return { steps: newSteps };
+  };
+}
+function createValueTransformMigration(transforms) {
+  return (state) => {
+    const newSteps = /* @__PURE__ */ new Map();
+    for (const [key, entry] of state.steps) {
+      const transform = transforms[key];
+      newSteps.set(key, transform ? transform(entry) : entry);
+    }
+    return { steps: newSteps };
+  };
+}
+function composeMigrations(migrations) {
+  return async (state) => {
+    let currentState = state;
+    for (const migration of migrations) {
+      currentState = await migration(currentState);
+    }
+    return currentState;
+  };
+}
+export {
+  SnapshotDecodeError,
+  SnapshotFormatError,
+  SnapshotMismatchError,
+  assertValidSnapshot,
+  composeMigrations,
+  createKeyRemoveMigration,
+  createKeyRenameMigration,
+  createMemoryCache,
+  createValueTransformMigration,
+  createVersionedState,
+  createVersionedStateLoader,
+  deserializeCauseNew,
+  deserializeResumeState,
+  isMigrationError,
+  isResumeState,
+  isSerializedResumeState,
+  isVersionIncompatibleError,
+  isWorkflowSnapshot,
+  looksLikeWorkflowSnapshot,
+  mergeSnapshots,
+  parseVersionedState,
+  serializeError,
+  serializeResumeState,
+  serializeThrown,
+  stringifyVersionedState,
+  toResumeState,
+  validateSnapshot
+};
+//# sourceMappingURL=persistence.js.map