@econ-v1/domain 6.7.0 → 6.10.0

package/{dist → src}/services/revisioned-domain-service.js

@@ -1,18 +1,108 @@
+// @ts-check
+
+/**
+ * @typedef {import("@econ-v1/ports").OutboxRecord} OutboxRecord
+ */
+/**
+ * @typedef {import("@econ-v1/ports").OutboxRepository} OutboxRepository
+ */
+/**
+ * @typedef {import("@econ-v1/ports").RepositoryJsonValue} RepositoryJsonValue
+ */
+/**
+ * @template {JsonValue} TValue
+ * @typedef {import("../models/revisioned.js").RevisionCommand<TValue>} RevisionCommand
+ */
+/**
+ * @template TValue
+ * @typedef {import("../models/revisioned.js").RevisionCommandResult<TValue>} RevisionCommandResult
+ */
+/**
+ * @template TValue
+ * @typedef {import("../models/revisioned.js").RevisionConflict<TValue>} RevisionConflict
+ */
+/**
+ * @template {JsonValue} TValue
+ * @typedef {import("../models/revisioned.js").RevisionConflictRecord<TValue>} RevisionConflictRecord
+ */
+/**
+ * @template {JsonValue} TValue
+ * @typedef {import("../models/revisioned.js").RevisionConflictPayload<TValue>} RevisionConflictPayload
+ */
+/**
+ * @template TValue
+ * @typedef {import("../models/revisioned.js").RevisionEntity<TValue>} RevisionEntity
+ */
+/**
+ * @typedef {import("../models/revisioned.js").RevisionResolution} RevisionResolution
+ */
+/**
+ * @typedef {import("../models/revisioned.js").RevisionedDomain} RevisionedDomain
+ */
+/**
+ * @typedef {import("../models/json.js").JsonValue} JsonValue
+ */
+/**
+ * @template {JsonValue} TValue
+ * @typedef {{ apply(entity: RevisionEntity<TValue>): Promise<void>; command(input: RevisionCommand<TValue>): Promise<RevisionCommandResult<TValue>>; read(id: string): Promise<RevisionEntity<TValue> | undefined>; }} RevisionedDomainRepository
+ */
+/**
+ * @template {JsonValue} TValue
+ * @typedef {{ readonly domain: RevisionedDomain; readonly now?: () => string; readonly outbox: OutboxRepository; readonly repository: RevisionedDomainRepository<TValue>; }} RevisionedDomainServiceOptions
+ */
+/**
+ * @template {JsonValue} TValue
+ * @typedef {| { readonly entity: RevisionEntity<TValue>; readonly status: "accepted" } | { readonly conflict: RevisionConflictRecord<TValue>; readonly status: "conflict" }} RevisionedWriteResult
+ */
+/**
+ * @template {JsonValue} TValue
+ * @typedef {| { readonly entity: RevisionEntity<TValue>; readonly status: "accepted" } | { readonly entity: RevisionEntity<TValue>; readonly status: "discarded" } | { readonly conflict: RevisionConflictRecord<TValue>; readonly status: "conflict" }} RevisionResolutionResult
+ */
+/**
+ * @template {JsonValue} TValue
+ * @typedef {{ readonly baseRev?: number; readonly id: string; readonly idempotencyKey: string; readonly value: TValue; }} RevisionedWriteInput
+ */
 import { DomainError } from "../errors/index.js";
 import { createOutboxIntent } from "../models/outbox.js";
 import { REVISIONED_DOMAINS, } from "../models/revisioned.js";
 import { RevisionMerge } from "./sync/revision-merge.js";
+/**
+ * @template {JsonValue} TValue
+ */
 export class RevisionedDomainService {
+    /**
+   * @readonly
+   * @type {RevisionedDomain}
+   */
     #domain;
+    /**
+   * @readonly
+   * @type {() => string}
+   */
     #now;
+    /**
+   * @readonly
+   * @type {OutboxRepository}
+   */
     #outbox;
+    /**
+   * @readonly
+   * @type {RevisionedDomainRepository<TValue>}
+   */
     #repository;
+    /**
+   * @param {RevisionedDomainServiceOptions<TValue>} options
+   */
     constructor(options) {
         this.#domain = options.domain;
         this.#now = options.now ?? (() => new Date().toISOString());
         this.#outbox = options.outbox;
         this.#repository = options.repository;
     }
+    /**
+   * @param {RevisionedWriteInput<TValue>} input
+   * @returns {Promise<RevisionedWriteResult<TValue>>}
+   */
     async update(input) {
         validateWriteInput(this.#domain, input);
         const merge = this.#merge(input.idempotencyKey);
@@ -28,17 +118,30 @@ export class RevisionedDomainService {
             throw new Error("Revision conflict was not persisted");
         return { conflict, status: "conflict" };
     }
+    /**
+   * @returns {Promise<readonly RevisionConflictRecord<TValue>[]>}
+   */
     async listConflicts() {
         const records = await this.#outbox.list({ domain: this.#outboxDomain(), state: "conflict" });
-        return records.map((record) => parseRevisionConflictRecord(record.payload, this.#domain));
+        return records.map((record) =>
+            /** @type {RevisionConflictRecord<TValue>} */ (
+                parseRevisionConflictRecord(record.payload, this.#domain)
+            ));
     }
+    /**
+   * @param {string} conflictIdValue
+   * @param {RevisionResolution} resolution
+   * @returns {Promise<RevisionResolutionResult<TValue>>}
+   */
     async resolveConflict(conflictIdValue, resolution) {
         if (conflictIdValue.trim() === "")
             throw invalid("conflict id");
         const stored = await this.#outbox.read(conflictIdValue);
         if (stored === undefined)
             throw new DomainError({ code: "not_found", message: "Revision conflict was not found" });
-        const conflict = parseRevisionConflictRecord(stored.payload, this.#domain);
+        const conflict = /** @type {RevisionConflictRecord<TValue>} */ (
+            parseRevisionConflictRecord(stored.payload, this.#domain)
+        );
         if (resolution === "theirs") {
             await this.#repository.apply(conflict.theirs);
             await this.#outbox.delete(stored.id);
@@ -66,6 +169,10 @@ export class RevisionedDomainService {
         await this.#outbox.delete(stored.id);
         return { conflict: replacement, status: "conflict" };
     }
+    /**
+   * @param {string} idempotencyKey
+   * @returns {RevisionMerge<TValue>}
+   */
     #merge(idempotencyKey) {
         return new RevisionMerge({
             parkConflict: async (conflict) => {
@@ -75,11 +182,18 @@ export class RevisionedDomainService {
             write: async (entity) => await this.#repository.apply(entity),
         });
     }
+    /**
+   * @param {RevisionConflict<TValue> & { readonly idempotencyKey: string }} conflict
+   * @returns {Promise<RevisionConflictRecord<TValue>>}
+   */
     async #persistConflict(conflict) {
         const id = conflictId(this.#domain, conflict.id, conflict.idempotencyKey);
         const existing = await this.#outbox.read(id);
         if (existing !== undefined)
-            return parseRevisionConflictRecord(existing.payload, this.#domain);
+            return /** @type {RevisionConflictRecord<TValue>} */ (
+                parseRevisionConflictRecord(existing.payload, this.#domain)
+            );
+        /** @type {RevisionConflictPayload<TValue>} */
         const record = {
             ...conflict,
             conflictId: id,
@@ -87,6 +201,7 @@ export class RevisionedDomainService {
             domain: this.#domain,
             kind: "revision-conflict.v1",
         };
+        /** @type {OutboxRecord} */
         const entry = {
             ...createOutboxIntent({
                 authority: "eventual",
@@ -94,7 +209,7 @@ export class RevisionedDomainService {
                 domain: this.#outboxDomain(),
                 id,
                 idempotencyKey: `conflict:${id}`,
-                payload: record,
+                payload: /** @type {RepositoryJsonValue} */ (record),
                 state: "conflict",
                 updatedAt: record.createdAt,
             }),
@@ -103,14 +218,31 @@ export class RevisionedDomainService {
         await this.#outbox.create(entry);
         return record;
     }
+    /**
+   * @param {string} id
+   * @returns {Promise<RevisionConflictRecord<TValue> | undefined>}
+   */
     async #readConflict(id) {
         const record = await this.#outbox.read(id);
-        return record === undefined ? undefined : parseRevisionConflictRecord(record.payload, this.#domain);
+        return record === undefined
+            ? undefined
+            : /** @type {RevisionConflictRecord<TValue>} */ (
+                parseRevisionConflictRecord(record.payload, this.#domain)
+            );
     }
+    /**
+   * @returns {string}
+   */
     #outboxDomain() {
         return `revision:${this.#domain}`;
     }
 }
+/**
+ * @template {JsonValue} TValue
+ * @param {unknown} value
+ * @param {RevisionedDomain} [expectedDomain]
+ * @returns {RevisionConflictRecord<TValue>}
+ */
 export function parseRevisionConflictRecord(value, expectedDomain) {
     if (!isRecord(value) || value.kind !== "revision-conflict.v1")
         throw invalid("revision conflict payload");
@@ -131,10 +263,16 @@ export function parseRevisionConflictRecord(value, expectedDomain) {
         domain,
         id: value.id,
         idempotencyKey: value.idempotencyKey,
-        mine: value.mine,
-        theirs: value.theirs,
+        mine: /** @type {TValue} */ (value.mine),
+        theirs: /** @type {RevisionEntity<TValue>} */ (value.theirs),
     };
 }
+/**
+ * @template {JsonValue} TValue
+ * @param {RevisionedDomain} domain
+ * @param {RevisionedWriteInput<TValue>} input
+ * @returns {void}
+ */
 function validateWriteInput(domain, input) {
     if (!nonEmptyString(input.id) || !nonEmptyString(input.idempotencyKey))
         throw invalid("revision write identity");
@@ -150,6 +288,10 @@ function validateWriteInput(domain, input) {
     if (domain === "graph")
         validateGraph(input.value);
 }
+/**
+ * @param {JsonValue} value
+ * @returns {void}
+ */
 function validateGraph(value) {
     if (!isRecord(value) || !Array.isArray(value.nodes) || !Array.isArray(value.edges))
         throw invalid("graph shape");
@@ -165,12 +307,25 @@ function validateGraph(value) {
             throw invalid("graph edge");
     }
 }
+/**
+ * @param {unknown} value
+ * @returns {value is RevisionEntity<JsonValue>}
+ */
 function isRevisionEntity(value) {
     return isRecord(value) && nonEmptyString(value.id) && isNonNegativeInteger(value.rev) && isJsonValue(value.value);
 }
+/**
+ * @param {unknown} value
+ * @returns {value is RevisionedDomain}
+ */
 function isRevisionedDomain(value) {
-    return REVISIONED_DOMAINS.includes(value);
+    return typeof value === "string" &&
+        REVISIONED_DOMAINS.includes(/** @type {RevisionedDomain} */ (value));
 }
+/**
+ * @param {unknown} value
+ * @returns {value is JsonValue}
+ */
 function isJsonValue(value) {
     if (value === null || typeof value === "string" || typeof value === "boolean")
         return true;
@@ -182,24 +337,49 @@ function isJsonValue(value) {
         return false;
     return Object.values(value).every(isJsonValue);
 }
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
 function isNonNegativeInteger(value) {
     return typeof value === "number" && Number.isInteger(value) && value >= 0;
 }
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+/**
+ * @param {unknown} value
+ * @returns {value is string}
+ */
 function nonEmptyString(value) {
     return typeof value === "string" && value.trim() !== "";
 }
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
 function requiredTimestamp(value) {
     if (!nonEmptyString(value) || !Number.isFinite(Date.parse(value)))
         throw invalid("revision conflict timestamp");
     return value;
 }
+/**
+ * @param {string} field
+ * @returns {DomainError}
+ */
 function invalid(field) {
     return new DomainError({ code: "validation_failed", message: `Invalid ${field}` });
 }
+/**
+ * @param {RevisionedDomain} domain
+ * @param {string} id
+ * @param {string} idempotencyKey
+ * @returns {string}
+ */
 function conflictId(domain, id, idempotencyKey) {
     return `${domain}:${id}:${idempotencyKey}`;
 }
-//# sourceMappingURL=revisioned-domain-service.js.map

package/src/services/runtime-globals.js

@@ -0,0 +1,174 @@
+// @ts-check
+
+/** @typedef {import("./abort-signal.js").AbortSignalPort} AbortSignalPort */
+
+/** @typedef {{ abort(): void, readonly signal: AbortSignalPort }} RuntimeAbortController */
+/** @typedef {{ readonly hostname: string, readonly origin: string, readonly password: string, readonly protocol: string, readonly username: string }} RuntimeUrl */
+/** @typedef {new () => unknown} NoArgumentConstructor */
+/** @typedef {new (input: string) => unknown} StringArgumentConstructor */
+
+/**
+ * @returns {RuntimeAbortController}
+ */
+export function createRuntimeAbortController() {
+  const Constructor = runtimeGlobal("AbortController");
+  if (!isNoArgumentConstructor(Constructor)) {
+    throw new Error("AbortController is unavailable");
+  }
+  const controller = new Constructor();
+  if (!isRuntimeAbortController(controller)) {
+    throw new TypeError("AbortController has an invalid runtime shape");
+  }
+  return controller;
+}
+
+/**
+ * @param {string} value
+ * @returns {RuntimeUrl}
+ */
+export function parseRuntimeUrl(value) {
+  const Constructor = runtimeGlobal("URL");
+  if (!isStringArgumentConstructor(Constructor)) {
+    throw new Error("URL is unavailable");
+  }
+  const url = new Constructor(value);
+  if (!isRuntimeUrl(url)) {
+    throw new TypeError("URL has an invalid runtime shape");
+  }
+  return url;
+}
+
+/**
+ * @param {string} value
+ * @returns {Uint8Array}
+ */
+export function encodeUtf8(value) {
+  const Constructor = runtimeGlobal("TextEncoder");
+  if (!isNoArgumentConstructor(Constructor)) {
+    throw new Error("TextEncoder is unavailable");
+  }
+  const encoder = new Constructor();
+  if (!isTextEncoder(encoder)) {
+    throw new TypeError("TextEncoder has an invalid runtime shape");
+  }
+  return encoder.encode(value);
+}
+
+/**
+ * @param {Uint8Array} value
+ * @returns {string}
+ */
+export function decodeUtf8(value) {
+  const Constructor = runtimeGlobal("TextDecoder");
+  if (!isNoArgumentConstructor(Constructor)) {
+    throw new Error("TextDecoder is unavailable");
+  }
+  const decoder = new Constructor();
+  if (!isTextDecoder(decoder)) {
+    throw new TypeError("TextDecoder has an invalid runtime shape");
+  }
+  return decoder.decode(value);
+}
+
+/**
+ * Confine the reflection library's unsound return value here and require a
+ * runtime guard before every use.
+ *
+ * @param {string} name
+ * @returns {unknown}
+ */
+function runtimeGlobal(name) {
+  return /** @type {unknown} */ (Reflect.get(globalThis, name));
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is NoArgumentConstructor}
+ */
+function isNoArgumentConstructor(value) {
+  return isConstructable(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is StringArgumentConstructor}
+ */
+function isStringArgumentConstructor(value) {
+  return isConstructable(value);
+}
+
+/**
+ * Test the ECMAScript [[Construct]] capability directly. Bound constructors
+ * deliberately have no own `prototype` property but remain constructable.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isConstructable(value) {
+  if (typeof value !== "function") return false;
+  try {
+    Reflect.construct(Object, [], value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is RuntimeAbortController}
+ */
+function isRuntimeAbortController(value) {
+  return isRecord(value) && typeof value.abort === "function" && isAbortSignal(value.signal);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is AbortSignalPort}
+ */
+function isAbortSignal(value) {
+  return isRecord(value) &&
+    typeof value.aborted === "boolean" &&
+    typeof value.addEventListener === "function" &&
+    typeof value.dispatchEvent === "function" &&
+    typeof value.removeEventListener === "function" &&
+    typeof value.throwIfAborted === "function" &&
+    "reason" in value;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is RuntimeUrl}
+ */
+function isRuntimeUrl(value) {
+  return isRecord(value) &&
+    typeof value.hostname === "string" &&
+    typeof value.origin === "string" &&
+    typeof value.password === "string" &&
+    typeof value.protocol === "string" &&
+    typeof value.username === "string";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is { encode(input?: string): Uint8Array }}
+ */
+function isTextEncoder(value) {
+  return isRecord(value) && typeof value.encode === "function";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is { decode(input?: Uint8Array): string }}
+ */
+function isTextDecoder(value) {
+  return isRecord(value) && typeof value.decode === "function";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}

package/src/services/session-service.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+/**
+ * @typedef {import("@econ-v1/ports").DeviceDelegation} DeviceDelegation
+ */
+/**
+ * @typedef {import("@econ-v1/ports").DeviceIdentity} DeviceIdentity
+ */
+/**
+ * @typedef {import("@econ-v1/ports").IdentityDiagnostics} IdentityDiagnostics
+ */
+/**
+ * @typedef {import("@econ-v1/ports").IdentityPort} IdentityPort
+ */
+import { normalizeDelegation } from "../models/delegation.js";
+export class SessionService {
+    /** @readonly @type {IdentityPort} */
+    identity;
+    /**
+   * @param {IdentityPort} identity
+   */
+    constructor(identity) {
+        this.identity = identity;
+    }
+    /**
+   * @returns {Promise<DeviceIdentity>}
+   */
+    async initialize() {
+        return await this.identity.generate();
+    }
+    /**
+   * @param {DeviceDelegation} delegation
+   * @returns {Promise<void>}
+   */
+    async acceptDelegation(delegation) {
+        await this.identity.storeDelegation(normalizeDelegation(delegation));
+    }
+    /**
+   * @returns {Promise<void>}
+   */
+    async revoke() {
+        await this.identity.clear();
+    }
+    /**
+   * @returns {Promise<IdentityDiagnostics>}
+   */
+    async diagnostics() {
+        return await this.identity.diagnostics();
+    }
+}

package/{dist → src}/services/sync/authoritative-mirror.js

@@ -1,19 +1,87 @@
+// @ts-check
+
+/**
+ * @template TPayload
+ * @typedef {import("../../models/sync.js").AuthoritativeCommand<TPayload>} AuthoritativeCommand
+ */
+/**
+ * @template TValue
+ * @typedef {import("../../models/sync.js").AuthoritativeSnapshot<TValue>} AuthoritativeSnapshot
+ */
+/**
+ * @typedef {import("../../models/sync.js").SyncApplyResult} SyncApplyResult
+ */
+/**
+ * @template TPayload
+ * @typedef {import("../../models/sync.js").SyncDelta<TPayload>} SyncDelta
+ */
+/**
+ * @typedef {import("../../models/sync.js").SyncDeltaContext} SyncDeltaContext
+ */
+/**
+ * @template TPayload
+ * @typedef {import("../../models/sync.js").SyncStrategy<TPayload>} SyncStrategy
+ */
+/**
+ * @template TValue
+ * @template TCommand
+ * @template TResult
+ * @typedef {{ readonly apply: (snapshot: AuthoritativeSnapshot<TValue>, delta: SyncDelta<TValue>) => Promise<void>; readonly execute: (command: AuthoritativeCommand<TCommand>) => Promise<TResult>; readonly staleAfterMs: number; }} AuthoritativeMirrorOptions
+ */
+/**
+ * @typedef {{ readonly now: string; readonly revalidate?: () => Promise<boolean>; }} AuthoritativeCommandOptions
+ */
+/**
+ * @extends {Error}
+ */
 export class AuthoritativeRevalidationRequiredError extends Error {
+    /**
+   * @readonly
+   * @type {string}
+   */
     idempotencyKey;
+    /**
+   * @param {string} idempotencyKey
+   */
     constructor(idempotencyKey) {
         super(`Authoritative command ${idempotencyKey} requires fresh state revalidation`);
         this.name = "AuthoritativeRevalidationRequiredError";
         this.idempotencyKey = idempotencyKey;
     }
 }
+/**
+ * @template TValue
+ * @template TCommand
+ * @template TResult
+ * @implements {SyncStrategy<TValue>}
+ */
 export class AuthoritativeMirror {
+    /** @readonly @type {"authoritative-mirror"} */
     kind = "authoritative-mirror";
+    /**
+   * @readonly
+   * @type {AuthoritativeMirrorOptions<TValue, TCommand, TResult>["apply"]}
+   */
     #apply;
+    /**
+   * @readonly
+   * @type {AuthoritativeMirrorOptions<TValue, TCommand, TResult>["execute"]}
+   */
     #execute;
+    /**
+   * @readonly
+   * @type {number}
+   */
     #staleAfterMs;
     #applied = new Set();
     #commands = new Map();
+    /**
+   * @type {AuthoritativeSnapshot<TValue> | undefined}
+   */
     #snapshot;
+    /**
+   * @param {AuthoritativeMirrorOptions<TValue, TCommand, TResult>} options
+   */
     constructor(options) {
         if (!Number.isInteger(options.staleAfterMs) || options.staleAfterMs <= 0) {
             throw new RangeError("Authoritative mirror staleAfterMs must be a positive integer");
@@ -22,6 +90,11 @@ export class AuthoritativeMirror {
         this.#execute = options.execute;
         this.#staleAfterMs = options.staleAfterMs;
     }
+    /**
+   * @param {SyncDelta<TValue>} delta
+   * @param {SyncDeltaContext} context
+   * @returns {Promise<SyncApplyResult>}
+   */
     async applyDelta(delta, context) {
         if (this.#applied.has(delta.id))
             return { applied: false };
@@ -36,12 +109,24 @@ export class AuthoritativeMirror {
         this.#applied.add(delta.id);
         return { applied: true };
     }
+    /**
+   * @returns {AuthoritativeSnapshot<TValue> | undefined}
+   */
     snapshot() {
         return this.#snapshot;
     }
+    /**
+   * @param {string} now
+   * @returns {boolean}
+   */
     isStale(now) {
         return this.#snapshot === undefined || parseDate(now, "current time") >= Date.parse(this.#snapshot.staleAt);
     }
+    /**
+   * @param {AuthoritativeCommand<TCommand>} command
+   * @param {AuthoritativeCommandOptions} options
+   * @returns {Promise<TResult>}
+   */
     async runCommand(command, options) {
         const existing = this.#commands.get(command.idempotencyKey);
         if (existing !== undefined)
@@ -62,10 +147,14 @@ export class AuthoritativeMirror {
         }
     }
 }
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {number}
+ */
 function parseDate(value, label) {
     const parsed = Date.parse(value);
     if (!Number.isFinite(parsed))
         throw new RangeError(`Invalid ${label}`);
     return parsed;
 }
-//# sourceMappingURL=authoritative-mirror.js.map