@craft-ts/core 0.7.0-beta.13

package/src/lib/craft-lazy.js

@@ -0,0 +1,83 @@
+import { inject } from './host/craft-compat';
+import { craftException } from './craft-exception';
+import { craftGen } from './craft-gen';
+import { GUARD_AWAIT_REQUEST_MARKER, } from './craft-generator-runtime';
+import { createRetryLazyLoadHelpers, CRAFT_DYNAMIC_IMPORT, CRAFT_LAZY_LOAD_RETRY, INITIAL_LAZY_LOAD_HELPERS, } from './craft-load-retry';
+export const CRAFT_LAZY_LOAD_ERROR_CODE = 'CRAFT_LAZY_LOAD_ERROR';
+/** Builds the `craftException` `craftLazy` returns when an import finally fails. */
+export function createCraftLazyLoadError(cause) {
+    return craftException({ _tag: CRAFT_LAZY_LOAD_ERROR_CODE, scope: 'CraftLazy' }, { cause });
+}
+function guardAwaitPromise(value) {
+    return {
+        [GUARD_AWAIT_REQUEST_MARKER]: true,
+        kind: 'promise',
+        value,
+    };
+}
+/**
+ * Runs a lazy import with the shared retry engine. The first attempt uses the
+ * identity helpers; on failure it re-invokes the loader up to the configured
+ * attempts with cache-busting helpers. Outside an Angular injection context
+ * (e.g. a hand-driven test) it degrades to a single attempt and rethrows.
+ */
+function injectLazyLoad() {
+    let deps;
+    try {
+        deps = {
+            retry: inject(CRAFT_LAZY_LOAD_RETRY),
+            dynamicImport: inject(CRAFT_DYNAMIC_IMPORT),
+        };
+    }
+    catch {
+        // No injection context — keep the loader's original single-attempt semantics.
+    }
+    return async (load) => {
+        try {
+            return await load(INITIAL_LAZY_LOAD_HELPERS);
+        }
+        catch (firstError) {
+            if (!deps)
+                throw firstError;
+            const retryHelpers = createRetryLazyLoadHelpers(deps.dynamicImport);
+            return deps.retry.execute(() => load(retryHelpers), {
+                attempt: 1,
+                error: firstError,
+            });
+        }
+    };
+}
+/**
+ * Lazily imports a module from inside an `asyncProcess` loader, reusing the same
+ * retry/cache-busting engine as route lazy loading (`loadComponent`).
+ *
+ * `craftLazy(load)` is a `craftGen`-built program: `yield*`-composable inside an
+ * async craft loader, `.pipe(...)`-able (so `catchTag('CRAFT_LAZY_LOAD_ERROR', …)`
+ * applies directly), and it awaits the import through the async program pump. On
+ * a final import failure it returns a {@link CraftLazyLoadError} `craftException`,
+ * which `craftGen` surfaces as a short-circuit → the enclosing resource's
+ * `status()` becomes `'exception'`.
+ *
+ * It must run in an async driver (an `asyncProcess` loader); it cannot be
+ * `yield*`-ed from a synchronous `craftMethod`, whose driver throws on the
+ * await-request. A `craftMethod` may only *trigger* the enclosing `asyncProcess`.
+ *
+ * @example
+ * ```ts
+ * const searchProcess = craftUse(asyncProcess({
+ *   method: on$(prefetch$, () => undefined),
+ *   loader: function* () {
+ *     return yield* craftLazy(({ withRetry }) => withRetry(import('./search')));
+ *   },
+ * }));
+ * ```
+ */
+export function craftLazy(load) {
+    const invoke = craftGen(function* () {
+        const runLoad = injectLazyLoad();
+        const settled = runLoad(load).then((value) => value, (cause) => createCraftLazyLoadError(cause));
+        return (yield guardAwaitPromise(settled));
+    });
+    return invoke();
+}
+//# sourceMappingURL=craft-lazy.js.map

package/src/lib/craft-lazy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-lazy.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-lazy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAA2B,MAAM,aAAa,CAAC;AAChE,OAAO,EACL,0BAA0B,GAE3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,GAG1B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,0BAA0B,GAAG,uBAAgC,CAAC;AAM3E,oFAAoF;AACpF,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,cAAc,CACnB,EAAE,IAAI,EAAE,0BAA0B,EAAE,KAAK,EAAE,WAAW,EAAE,EACxD,EAAE,KAAK,EAAsC,CAC9C,CAAC;AACJ,CAAC;AAID,SAAS,iBAAiB,CAAC,KAA2B;IACpD,OAAO;QACL,CAAC,0BAA0B,CAAC,EAAE,IAAI;QAClC,IAAI,EAAE,SAAS;QACf,KAAK;KACsB,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc;IAGrB,IAAI,IAES,CAAC;IACd,IAAI,CAAC;QACH,IAAI,GAAG;YACL,KAAK,EAAE,MAAM,CAAC,qBAAqB,CAAC;YACpC,aAAa,EAAE,MAAM,CAAC,oBAAoB,CAAC;SAC5C,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,8EAA8E;IAChF,CAAC;IAED,OAAO,KAAK,EAAK,IAAmD,EAAE,EAAE;QACtE,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,yBAAyB,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI;gBAAE,MAAM,UAAU,CAAC;YAE5B,MAAM,YAAY,GAAG,0BAA0B,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YACpE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE;gBAClD,OAAO,EAAE,CAAC;gBACV,KAAK,EAAE,UAAU;aAClB,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,SAAS,CACvB,IAAmD;IAEnD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAK/B,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;QACjC,MAAM,OAAO,GAAoC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CACjE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAChB,CAAC,KAAK,EAAE,EAAE,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAC3C,CAAC;QAEF,OAAO,CAAC,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAA2B,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,EAAkE,CAAC;AAClF,CAAC","sourcesContent":["import { inject } from './host/craft-compat';\nimport { craftException } from './craft-exception';\nimport { craftGen, type CraftGenInvocation } from './craft-gen';\nimport {\n  GUARD_AWAIT_REQUEST_MARKER,\n  type RuntimeGuardAwaitRequest,\n} from './craft-generator-runtime';\nimport {\n  createRetryLazyLoadHelpers,\n  CRAFT_DYNAMIC_IMPORT,\n  CRAFT_LAZY_LOAD_RETRY,\n  INITIAL_LAZY_LOAD_HELPERS,\n  type CraftLazyLoadHelpers,\n  type CraftLoadRetry,\n} from './craft-load-retry';\n\nexport const CRAFT_LAZY_LOAD_ERROR_CODE = 'CRAFT_LAZY_LOAD_ERROR' as const;\n\nexport interface CraftLazyLoadErrorPayload {\n  readonly cause: unknown;\n}\n\n/** Builds the `craftException` `craftLazy` returns when an import finally fails. */\nexport function createCraftLazyLoadError(cause: unknown) {\n  return craftException(\n    { _tag: CRAFT_LAZY_LOAD_ERROR_CODE, scope: 'CraftLazy' },\n    { cause } satisfies CraftLazyLoadErrorPayload,\n  );\n}\n\nexport type CraftLazyLoadError = ReturnType<typeof createCraftLazyLoadError>;\n\nfunction guardAwaitPromise(value: PromiseLike<unknown>): RuntimeGuardAwaitRequest {\n  return {\n    [GUARD_AWAIT_REQUEST_MARKER]: true,\n    kind: 'promise',\n    value,\n  } as RuntimeGuardAwaitRequest;\n}\n\n/**\n * Runs a lazy import with the shared retry engine. The first attempt uses the\n * identity helpers; on failure it re-invokes the loader up to the configured\n * attempts with cache-busting helpers. Outside an Angular injection context\n * (e.g. a hand-driven test) it degrades to a single attempt and rethrows.\n */\nfunction injectLazyLoad(): <T>(\n  load: (helpers: CraftLazyLoadHelpers) => Promise<T>,\n) => Promise<T> {\n  let deps:\n    | { retry: CraftLoadRetry; dynamicImport: (url: string) => Promise<unknown> }\n    | undefined;\n  try {\n    deps = {\n      retry: inject(CRAFT_LAZY_LOAD_RETRY),\n      dynamicImport: inject(CRAFT_DYNAMIC_IMPORT),\n    };\n  } catch {\n    // No injection context — keep the loader's original single-attempt semantics.\n  }\n\n  return async <T>(load: (helpers: CraftLazyLoadHelpers) => Promise<T>) => {\n    try {\n      return await load(INITIAL_LAZY_LOAD_HELPERS);\n    } catch (firstError) {\n      if (!deps) throw firstError;\n\n      const retryHelpers = createRetryLazyLoadHelpers(deps.dynamicImport);\n      return deps.retry.execute(() => load(retryHelpers), {\n        attempt: 1,\n        error: firstError,\n      });\n    }\n  };\n}\n\n/**\n * Lazily imports a module from inside an `asyncProcess` loader, reusing the same\n * retry/cache-busting engine as route lazy loading (`loadComponent`).\n *\n * `craftLazy(load)` is a `craftGen`-built program: `yield*`-composable inside an\n * async craft loader, `.pipe(...)`-able (so `catchTag('CRAFT_LAZY_LOAD_ERROR', …)`\n * applies directly), and it awaits the import through the async program pump. On\n * a final import failure it returns a {@link CraftLazyLoadError} `craftException`,\n * which `craftGen` surfaces as a short-circuit → the enclosing resource's\n * `status()` becomes `'exception'`.\n *\n * It must run in an async driver (an `asyncProcess` loader); it cannot be\n * `yield*`-ed from a synchronous `craftMethod`, whose driver throws on the\n * await-request. A `craftMethod` may only *trigger* the enclosing `asyncProcess`.\n *\n * @example\n * ```ts\n * const searchProcess = craftUse(asyncProcess({\n *   method: on$(prefetch$, () => undefined),\n *   loader: function* () {\n *     return yield* craftLazy(({ withRetry }) => withRetry(import('./search')));\n *   },\n * }));\n * ```\n */\nexport function craftLazy<T>(\n  load: (helpers: CraftLazyLoadHelpers) => Promise<T>,\n): CraftGenInvocation<never, T | CraftLazyLoadError> {\n  const invoke = craftGen(function* (): Generator<\n    RuntimeGuardAwaitRequest,\n    T | CraftLazyLoadError,\n    unknown\n  > {\n    const runLoad = injectLazyLoad();\n    const settled: Promise<T | CraftLazyLoadError> = runLoad(load).then(\n      (value) => value,\n      (cause) => createCraftLazyLoadError(cause),\n    );\n\n    return (yield guardAwaitPromise(settled)) as T | CraftLazyLoadError;\n  });\n\n  return invoke() as unknown as CraftGenInvocation<never, T | CraftLazyLoadError>;\n}\n"]}

package/src/lib/craft-load-retry.d.ts

@@ -0,0 +1,76 @@
+import { InjectionToken, type Type } from './host/craft-compat';
+import { type CraftTemporalRuntime } from './temporal-runtime';
+/**
+ * The `{ withRetry }` helpers handed to a lazy loader callback. `withRetry`
+ * wraps a dynamic `import(...)` so a chunk whose hashed URL went stale after a
+ * redeploy is re-fetched with a cache-busting query param. On the very first
+ * attempt it is the identity function; the retry engine swaps in the
+ * cache-busting variant for subsequent attempts.
+ */
+export interface CraftLazyLoadHelpers {
+    withRetry<T>(moduleImport: Promise<T>): Promise<T>;
+}
+/**
+ * The injectable dynamic `import(url)`. Overridable in tests to observe the
+ * cache-busting URL {@link retryFailedDynamicImport} computes.
+ */
+export declare const CRAFT_DYNAMIC_IMPORT: InjectionToken<(url: string) => Promise<unknown>>;
+/** The base fields the retry loop itself reads and advances on every attempt. */
+export interface CraftLoadRetryContextBase {
+    readonly attempt: number;
+    readonly error: unknown;
+}
+export interface CraftLoadRetry<Context extends CraftLoadRetryContextBase = CraftLoadRetryContextBase> {
+    execute<T>(loader: () => Promise<T>, context: Context): Promise<T>;
+}
+export interface CraftLoadRetryOptions<Context extends CraftLoadRetryContextBase = CraftLoadRetryContextBase> {
+    readonly attempts?: number;
+    readonly delayMs?: number | ((error: unknown, context: Context) => number);
+    readonly shouldRetry?: (error: unknown, context: Context) => boolean | Promise<boolean>;
+    /** Optional clock seam, primarily useful for deterministic tests. */
+    readonly temporalRuntime?: CraftTemporalRuntime;
+}
+export type CraftLoadRetryConfig<Context extends CraftLoadRetryContextBase = CraftLoadRetryContextBase> = CraftLoadRetry<Context> | Type<CraftLoadRetry<Context>> | CraftLoadRetryOptions<Context>;
+export declare const DEFAULT_CRAFT_LOAD_RETRY_OPTIONS: {
+    attempts: number;
+    delayMs: number;
+};
+/**
+ * Builds the attempts/delay/shouldRetry loop shared by every craft lazy load.
+ * `execute` re-invokes `loader` up to `attempts` times, threading the caller's
+ * `Context` (only `attempt` and `error` are advanced by the engine — the rest is
+ * spread through unchanged) into the `delayMs`/`shouldRetry` callbacks. On final
+ * exhaustion it rethrows the last raw failure (callers wrap it into a domain
+ * `craftException` — a route load error or a `craftLazy` load error).
+ */
+export declare function createCraftLoadRetry<Context extends CraftLoadRetryContextBase = CraftLoadRetryContextBase>(options?: CraftLoadRetryOptions<Context>): CraftLoadRetry<Context>;
+/**
+ * The retry policy `craftLazy` applies to an imperative lazy import. Defaults to
+ * the shared attempts/delay loop; override it to tune attempts, back-off, or
+ * `shouldRetry` for `craftLazy` loads specifically.
+ */
+export declare const CRAFT_LAZY_LOAD_RETRY: InjectionToken<CraftLoadRetry<CraftLoadRetryContextBase>>;
+export declare function provideCraftLazyLoadRetry(retry: CraftLoadRetryConfig): {
+    provide: typeof CRAFT_LAZY_LOAD_RETRY;
+    useValue: CraftLoadRetry;
+} | {
+    provide: typeof CRAFT_LAZY_LOAD_RETRY;
+    useClass: Type<CraftLoadRetry>;
+};
+export declare function isCraftLoadRetry<Context extends CraftLoadRetryContextBase>(value: CraftLoadRetryConfig<Context>): value is CraftLoadRetry<Context>;
+export declare function isCraftLoadRetryType<Context extends CraftLoadRetryContextBase>(value: CraftLoadRetryConfig<Context>): value is Type<CraftLoadRetry<Context>>;
+/** The identity helpers used for the first (un-busted) load attempt. */
+export declare const INITIAL_LAZY_LOAD_HELPERS: CraftLazyLoadHelpers;
+/**
+ * Helpers whose `withRetry` re-fetches a failed chunk with a cache-busting
+ * query param, used for every attempt after the first.
+ */
+export declare function createRetryLazyLoadHelpers(dynamicImport: (url: string) => Promise<unknown>, retryParam?: string): CraftLazyLoadHelpers;
+/**
+ * Awaits `moduleImport`; if it fails because a dynamically-imported chunk could
+ * not be fetched (a stale hashed URL after a redeploy), re-imports the same URL
+ * with an incrementing cache-busting query param. Concurrent retries of the same
+ * URL share a single in-flight import.
+ */
+export declare function retryFailedDynamicImport<T>(moduleImport: Promise<T>, dynamicImport: (url: string) => Promise<unknown>, retryParam?: string): Promise<T>;
+//# sourceMappingURL=craft-load-retry.d.ts.map

package/src/lib/craft-load-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-load-retry.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-load-retry.ts"],"names":[],"mappings":"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"}

package/src/lib/craft-load-retry.js

@@ -0,0 +1,160 @@
+import { inject, InjectionToken } from './host/craft-compat';
+import { CRAFT_TEMPORAL_RUNTIME, RealCraftTemporalRuntime, } from './temporal-runtime';
+/**
+ * The injectable dynamic `import(url)`. Overridable in tests to observe the
+ * cache-busting URL {@link retryFailedDynamicImport} computes.
+ */
+export const CRAFT_DYNAMIC_IMPORT = new InjectionToken('CRAFT_DYNAMIC_IMPORT', {
+    providedIn: 'root',
+    factory: () => (url) => import(/* @vite-ignore */ url),
+});
+export const DEFAULT_CRAFT_LOAD_RETRY_OPTIONS = {
+    attempts: 1,
+    delayMs: 250,
+};
+/**
+ * Builds the attempts/delay/shouldRetry loop shared by every craft lazy load.
+ * `execute` re-invokes `loader` up to `attempts` times, threading the caller's
+ * `Context` (only `attempt` and `error` are advanced by the engine — the rest is
+ * spread through unchanged) into the `delayMs`/`shouldRetry` callbacks. On final
+ * exhaustion it rethrows the last raw failure (callers wrap it into a domain
+ * `craftException` — a route load error or a `craftLazy` load error).
+ */
+export function createCraftLoadRetry(options = {}) {
+    const attempts = Math.max(1, Math.floor(options.attempts ?? DEFAULT_CRAFT_LOAD_RETRY_OPTIONS.attempts));
+    const delayMs = options.delayMs ?? DEFAULT_CRAFT_LOAD_RETRY_OPTIONS.delayMs;
+    const temporalRuntime = options.temporalRuntime ??
+        tryInjectTemporalRuntime() ??
+        new RealCraftTemporalRuntime();
+    return {
+        async execute(loader, baseContext) {
+            let lastError;
+            let previousError = baseContext.error;
+            for (let index = 0; index < attempts; index++) {
+                const context = {
+                    ...baseContext,
+                    attempt: baseContext.attempt + index + 1,
+                    error: previousError,
+                };
+                const shouldRetry = options.shouldRetry?.(previousError, context) ?? true;
+                if (!(await shouldRetry))
+                    throw previousError;
+                const resolvedDelayMs = Math.max(0, typeof delayMs === 'function'
+                    ? delayMs(previousError, context)
+                    : delayMs);
+                if (resolvedDelayMs > 0) {
+                    await temporalRuntime.sleep(resolvedDelayMs, {
+                        kind: 'retry',
+                        owner: 'craft-load-retry',
+                    });
+                }
+                try {
+                    return await loader();
+                }
+                catch (error) {
+                    lastError = error;
+                    previousError = error;
+                }
+            }
+            throw lastError;
+        },
+    };
+}
+function tryInjectTemporalRuntime() {
+    try {
+        return inject(CRAFT_TEMPORAL_RUNTIME, { optional: true }) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The retry policy `craftLazy` applies to an imperative lazy import. Defaults to
+ * the shared attempts/delay loop; override it to tune attempts, back-off, or
+ * `shouldRetry` for `craftLazy` loads specifically.
+ */
+export const CRAFT_LAZY_LOAD_RETRY = new InjectionToken('CRAFT_LAZY_LOAD_RETRY', { providedIn: 'root', factory: () => createCraftLoadRetry() });
+export function provideCraftLazyLoadRetry(retry) {
+    if (isCraftLoadRetryType(retry)) {
+        return { provide: CRAFT_LAZY_LOAD_RETRY, useClass: retry };
+    }
+    return {
+        provide: CRAFT_LAZY_LOAD_RETRY,
+        useValue: isCraftLoadRetry(retry) ? retry : createCraftLoadRetry(retry),
+    };
+}
+export function isCraftLoadRetry(value) {
+    return typeof value.execute === 'function';
+}
+export function isCraftLoadRetryType(value) {
+    return typeof value === 'function';
+}
+/** The identity helpers used for the first (un-busted) load attempt. */
+export const INITIAL_LAZY_LOAD_HELPERS = {
+    withRetry: (moduleImport) => moduleImport,
+};
+/**
+ * Helpers whose `withRetry` re-fetches a failed chunk with a cache-busting
+ * query param, used for every attempt after the first.
+ */
+export function createRetryLazyLoadHelpers(dynamicImport, retryParam = DEFAULT_RETRY_PARAM) {
+    return {
+        withRetry: (moduleImport) => retryFailedDynamicImport(moduleImport, dynamicImport, retryParam),
+    };
+}
+const DEFAULT_RETRY_PARAM = '__craft_retry';
+const successfulRetriedImports = new Map();
+const retryImportAttempts = new Map();
+/**
+ * Awaits `moduleImport`; if it fails because a dynamically-imported chunk could
+ * not be fetched (a stale hashed URL after a redeploy), re-imports the same URL
+ * with an incrementing cache-busting query param. Concurrent retries of the same
+ * URL share a single in-flight import.
+ */
+export async function retryFailedDynamicImport(moduleImport, dynamicImport, retryParam = DEFAULT_RETRY_PARAM) {
+    try {
+        return await moduleImport;
+    }
+    catch (error) {
+        const failedUrl = failedDynamicImportUrl(error);
+        if (!failedUrl)
+            throw error;
+        const baseUrl = failedUrl.href;
+        const cachedRetry = successfulRetriedImports.get(baseUrl);
+        if (cachedRetry)
+            return cachedRetry;
+        const attempt = (retryImportAttempts.get(baseUrl) ?? 0) + 1;
+        retryImportAttempts.set(baseUrl, attempt);
+        failedUrl.searchParams.set(retryParam, String(attempt));
+        const retriedImport = dynamicImport(failedUrl.href);
+        successfulRetriedImports.set(baseUrl, retriedImport);
+        try {
+            return await retriedImport;
+        }
+        catch (retryError) {
+            successfulRetriedImports.delete(baseUrl);
+            throw retryError;
+        }
+    }
+}
+function failedDynamicImportUrl(error) {
+    if (!(error instanceof Error))
+        return undefined;
+    const prefix = 'Failed to fetch dynamically imported module:';
+    const prefixIndex = error.message.indexOf(prefix);
+    if (prefixIndex === -1)
+        return undefined;
+    try {
+        const url = new URL(error.message.slice(prefixIndex + prefix.length).trim());
+        const currentOrigin = globalThis.location?.origin;
+        if (currentOrigin && url.origin !== currentOrigin)
+            return undefined;
+        if (!url.pathname.endsWith('.js'))
+            return undefined;
+        return url;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=craft-load-retry.js.map

package/src/lib/craft-load-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-load-retry.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-load-retry.ts"],"names":[],"mappings":"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","sourcesContent":["import { inject, InjectionToken, type Type } from './host/craft-compat';\nimport {\n  CRAFT_TEMPORAL_RUNTIME,\n  RealCraftTemporalRuntime,\n  type CraftTemporalRuntime,\n} from './temporal-runtime';\n\n// ---------------------------------------------------------------------------\n// Generic lazy-load retry engine.\n//\n// Powers both route lazy loading (`loadComponent`/`loadChildren`, see\n// craft-route-load-error.ts) and imperative service lazy loading (`craftLazy`,\n// see craft-lazy.ts). It provides:\n//\n// - `CRAFT_DYNAMIC_IMPORT` — the injectable `import(url)` used for cache-busting\n//   a chunk whose first fetch failed (a stale hashed URL after a redeploy).\n// - `retryFailedDynamicImport` — re-imports a failed chunk with a cache-busting\n//   query param, deduplicating concurrent retries of the same URL.\n// - `createCraftLoadRetry` — the attempts/delay/shouldRetry loop, generic over\n//   the retry context the caller threads through its callbacks.\n// - `CraftLazyLoadHelpers` — the `{ withRetry }` object handed to a loader\n//   callback, plus the identity/retry-flavoured factories that build it.\n// ---------------------------------------------------------------------------\n\n/**\n * The `{ withRetry }` helpers handed to a lazy loader callback. `withRetry`\n * wraps a dynamic `import(...)` so a chunk whose hashed URL went stale after a\n * redeploy is re-fetched with a cache-busting query param. On the very first\n * attempt it is the identity function; the retry engine swaps in the\n * cache-busting variant for subsequent attempts.\n */\nexport interface CraftLazyLoadHelpers {\n  withRetry<T>(moduleImport: Promise<T>): Promise<T>;\n}\n\n/**\n * The injectable dynamic `import(url)`. Overridable in tests to observe the\n * cache-busting URL {@link retryFailedDynamicImport} computes.\n */\nexport const CRAFT_DYNAMIC_IMPORT = new InjectionToken<\n  (url: string) => Promise<unknown>\n>('CRAFT_DYNAMIC_IMPORT', {\n  providedIn: 'root',\n  factory: () => (url) => import(/* @vite-ignore */ url),\n});\n\n/** The base fields the retry loop itself reads and advances on every attempt. */\nexport interface CraftLoadRetryContextBase {\n  readonly attempt: number;\n  readonly error: unknown;\n}\n\nexport interface CraftLoadRetry<\n  Context extends CraftLoadRetryContextBase = CraftLoadRetryContextBase,\n> {\n  execute<T>(loader: () => Promise<T>, context: Context): Promise<T>;\n}\n\nexport interface CraftLoadRetryOptions<\n  Context extends CraftLoadRetryContextBase = CraftLoadRetryContextBase,\n> {\n  readonly attempts?: number;\n  readonly delayMs?: number | ((error: unknown, context: Context) => number);\n  readonly shouldRetry?: (\n    error: unknown,\n    context: Context,\n  ) => boolean | Promise<boolean>;\n  /** Optional clock seam, primarily useful for deterministic tests. */\n  readonly temporalRuntime?: CraftTemporalRuntime;\n}\n\nexport type CraftLoadRetryConfig<\n  Context extends CraftLoadRetryContextBase = CraftLoadRetryContextBase,\n> =\n  | CraftLoadRetry<Context>\n  | Type<CraftLoadRetry<Context>>\n  | CraftLoadRetryOptions<Context>;\n\nexport const DEFAULT_CRAFT_LOAD_RETRY_OPTIONS = {\n  attempts: 1,\n  delayMs: 250,\n} satisfies Required<Pick<CraftLoadRetryOptions, 'attempts' | 'delayMs'>>;\n\n/**\n * Builds the attempts/delay/shouldRetry loop shared by every craft lazy load.\n * `execute` re-invokes `loader` up to `attempts` times, threading the caller's\n * `Context` (only `attempt` and `error` are advanced by the engine — the rest is\n * spread through unchanged) into the `delayMs`/`shouldRetry` callbacks. On final\n * exhaustion it rethrows the last raw failure (callers wrap it into a domain\n * `craftException` — a route load error or a `craftLazy` load error).\n */\nexport function createCraftLoadRetry<\n  Context extends CraftLoadRetryContextBase = CraftLoadRetryContextBase,\n>(options: CraftLoadRetryOptions<Context> = {}): CraftLoadRetry<Context> {\n  const attempts = Math.max(\n    1,\n    Math.floor(options.attempts ?? DEFAULT_CRAFT_LOAD_RETRY_OPTIONS.attempts),\n  );\n  const delayMs = options.delayMs ?? DEFAULT_CRAFT_LOAD_RETRY_OPTIONS.delayMs;\n  const temporalRuntime =\n    options.temporalRuntime ??\n    tryInjectTemporalRuntime() ??\n    new RealCraftTemporalRuntime();\n\n  return {\n    async execute<T>(\n      loader: () => Promise<T>,\n      baseContext: Context,\n    ): Promise<T> {\n      let lastError: unknown;\n      let previousError = baseContext.error;\n      for (let index = 0; index < attempts; index++) {\n        const context = {\n          ...baseContext,\n          attempt: baseContext.attempt + index + 1,\n          error: previousError,\n        } as Context;\n        const shouldRetry =\n          options.shouldRetry?.(previousError, context) ?? true;\n        if (!(await shouldRetry)) throw previousError;\n\n        const resolvedDelayMs = Math.max(\n          0,\n          typeof delayMs === 'function'\n            ? delayMs(previousError, context)\n            : delayMs,\n        );\n        if (resolvedDelayMs > 0) {\n          await temporalRuntime.sleep(resolvedDelayMs, {\n            kind: 'retry',\n            owner: 'craft-load-retry',\n          });\n        }\n\n        try {\n          return await loader();\n        } catch (error) {\n          lastError = error;\n          previousError = error;\n        }\n      }\n      throw lastError;\n    },\n  };\n}\n\nfunction tryInjectTemporalRuntime(): CraftTemporalRuntime | undefined {\n  try {\n    return inject(CRAFT_TEMPORAL_RUNTIME, { optional: true }) ?? undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * The retry policy `craftLazy` applies to an imperative lazy import. Defaults to\n * the shared attempts/delay loop; override it to tune attempts, back-off, or\n * `shouldRetry` for `craftLazy` loads specifically.\n */\nexport const CRAFT_LAZY_LOAD_RETRY = new InjectionToken<CraftLoadRetry>(\n  'CRAFT_LAZY_LOAD_RETRY',\n  { providedIn: 'root', factory: () => createCraftLoadRetry() },\n);\n\nexport function provideCraftLazyLoadRetry(\n  retry: CraftLoadRetryConfig,\n):\n  | { provide: typeof CRAFT_LAZY_LOAD_RETRY; useValue: CraftLoadRetry }\n  | { provide: typeof CRAFT_LAZY_LOAD_RETRY; useClass: Type<CraftLoadRetry> } {\n  if (isCraftLoadRetryType(retry)) {\n    return { provide: CRAFT_LAZY_LOAD_RETRY, useClass: retry };\n  }\n  return {\n    provide: CRAFT_LAZY_LOAD_RETRY,\n    useValue: isCraftLoadRetry(retry) ? retry : createCraftLoadRetry(retry),\n  };\n}\n\nexport function isCraftLoadRetry<Context extends CraftLoadRetryContextBase>(\n  value: CraftLoadRetryConfig<Context>,\n): value is CraftLoadRetry<Context> {\n  return typeof (value as CraftLoadRetry<Context>).execute === 'function';\n}\n\nexport function isCraftLoadRetryType<Context extends CraftLoadRetryContextBase>(\n  value: CraftLoadRetryConfig<Context>,\n): value is Type<CraftLoadRetry<Context>> {\n  return typeof value === 'function';\n}\n\n/** The identity helpers used for the first (un-busted) load attempt. */\nexport const INITIAL_LAZY_LOAD_HELPERS: CraftLazyLoadHelpers = {\n  withRetry: <T>(moduleImport: Promise<T>) => moduleImport,\n};\n\n/**\n * Helpers whose `withRetry` re-fetches a failed chunk with a cache-busting\n * query param, used for every attempt after the first.\n */\nexport function createRetryLazyLoadHelpers(\n  dynamicImport: (url: string) => Promise<unknown>,\n  retryParam = DEFAULT_RETRY_PARAM,\n): CraftLazyLoadHelpers {\n  return {\n    withRetry: <T>(moduleImport: Promise<T>) =>\n      retryFailedDynamicImport(moduleImport, dynamicImport, retryParam),\n  };\n}\n\nconst DEFAULT_RETRY_PARAM = '__craft_retry';\n\nconst successfulRetriedImports = new Map<string, Promise<unknown>>();\nconst retryImportAttempts = new Map<string, number>();\n\n/**\n * Awaits `moduleImport`; if it fails because a dynamically-imported chunk could\n * not be fetched (a stale hashed URL after a redeploy), re-imports the same URL\n * with an incrementing cache-busting query param. Concurrent retries of the same\n * URL share a single in-flight import.\n */\nexport async function retryFailedDynamicImport<T>(\n  moduleImport: Promise<T>,\n  dynamicImport: (url: string) => Promise<unknown>,\n  retryParam = DEFAULT_RETRY_PARAM,\n): Promise<T> {\n  try {\n    return await moduleImport;\n  } catch (error) {\n    const failedUrl = failedDynamicImportUrl(error);\n    if (!failedUrl) throw error;\n\n    const baseUrl = failedUrl.href;\n    const cachedRetry = successfulRetriedImports.get(baseUrl);\n    if (cachedRetry) return cachedRetry as Promise<T>;\n\n    const attempt = (retryImportAttempts.get(baseUrl) ?? 0) + 1;\n    retryImportAttempts.set(baseUrl, attempt);\n    failedUrl.searchParams.set(retryParam, String(attempt));\n\n    const retriedImport = dynamicImport(failedUrl.href) as Promise<T>;\n    successfulRetriedImports.set(baseUrl, retriedImport);\n\n    try {\n      return await retriedImport;\n    } catch (retryError) {\n      successfulRetriedImports.delete(baseUrl);\n      throw retryError;\n    }\n  }\n}\n\nfunction failedDynamicImportUrl(error: unknown): URL | undefined {\n  if (!(error instanceof Error)) return undefined;\n\n  const prefix = 'Failed to fetch dynamically imported module:';\n  const prefixIndex = error.message.indexOf(prefix);\n  if (prefixIndex === -1) return undefined;\n\n  try {\n    const url = new URL(\n      error.message.slice(prefixIndex + prefix.length).trim(),\n    );\n    const currentOrigin = globalThis.location?.origin;\n    if (currentOrigin && url.origin !== currentOrigin) return undefined;\n    if (!url.pathname.endsWith('.js')) return undefined;\n    return url;\n  } catch {\n    return undefined;\n  }\n}\n"]}

package/src/lib/craft-machine-history.d.ts

@@ -0,0 +1,145 @@
+import { StorageService } from './browser-boundaries';
+import type { CraftUnique } from './craft-unique';
+import type { GetServiceYields } from './craft-service';
+import { type CraftPrimitiveSnapshot } from './craft-primitive-registry';
+import { type YieldableReactiveValue } from './reactive-read';
+import type { CraftMachineControls, CraftMachineInsertionContext } from './craft-state-machine';
+/**
+ * One recorded moment of a machine: the transition that produced it, and the
+ * value of every primitive the machine owns at that point.
+ *
+ * The step and the values are captured AFTER the transition was applied, so
+ * restoring an entry restores the state the machine was in once it had moved.
+ *
+ * Snapshot keys are RELATIVE to the machine, not absolute registry addresses.
+ * An absolute address starts with the host chain of the component that happens
+ * to hold the machine, and that prefix carries a creation ordinal which means
+ * nothing after a reload. Below the machine everything is deterministic — the
+ * same code creates the same primitives in the same order — so a relative key
+ * survives, and re-anchors onto whichever instance is restoring it.
+ */
+export type CraftHistoryEntry<Steps extends string = string> = Readonly<{
+    step: Steps;
+    from: Steps | undefined;
+    event: unknown;
+    at: number;
+    snapshot: CraftPrimitiveSnapshot;
+}>;
+/**
+ * What a history feature composed into {@link withStateMachineHistory} receives. It is
+ * deliberately narrow: a feature navigates the recorded entries, it does not
+ * decide what gets recorded.
+ */
+export type CraftHistoryFeatureContext<Steps extends string = string> = Readonly<{
+    entries: YieldableReactiveValue<readonly CraftHistoryEntry<Steps>[], 'entries'>;
+    /** Index of the entry the machine currently sits on. */
+    cursor: YieldableReactiveValue<number, 'cursor'>;
+    /**
+     * Restores the recorded entry at `index`. Returns `false` when the index
+     * is out of range. Guards are NOT consulted: a recorded state was already
+     * accepted once, and replaying it must not depend on today's permissions.
+     */
+    goTo(index: number): boolean;
+    controls: CraftMachineControls<Steps>;
+}>;
+export type CraftHistoryFeature<Output extends object> = (context: CraftHistoryFeatureContext<any>) => Output;
+type HistoryOptions = Readonly<{
+    /**
+     * How many entries to keep. The oldest are dropped first. `Infinity` keeps
+     * everything, which is fine for a debug session and not for production.
+     */
+    limit?: number;
+    /**
+     * Primitives declared OUTSIDE the machine that belong to the story being
+     * recorded. A machine captures what it owns by itself; anything else has to
+     * be named, so a replay stays reproducible instead of depending on whatever
+     * happened to be in the injector.
+     *
+     * ```ts
+     * withStateMachineHistory({ include: [sharedFilters] }, withBackNavigation())
+     * ```
+     */
+    include?: readonly unknown[];
+    /**
+     * Keeps the history across a reload, under an anchor the application names.
+     *
+     * Only the ANCHOR needs a stable identity: everything the machine owns is
+     * addressed relative to it, and those keys are deterministic. `key` may be a
+     * function when the anchor comes from data — a row of a list anchors on the
+     * entity it edits, not on the order it happened to be created in.
+     *
+     * ```ts
+     * withStateMachineHistory(
+     *   { persist: craftUnique({ storeName: 'app', key: 'book-editor' }) },
+     *   withBackNavigation(),
+     * )
+     * ```
+     */
+    persist?: CraftUnique<CraftHistoryPersistenceStatic> | CraftHistoryPersistenceDynamic;
+}>;
+export type CraftHistoryPersistenceStatic = Readonly<{
+    storeName: string;
+    key: string;
+}>;
+/** A data-dependent anchor cannot be verified as a static unique identity. */
+export type CraftHistoryPersistenceDynamic = Readonly<{
+    storeName: string;
+    /** Resolved once, when the machine is built. */
+    key: () => string;
+}>;
+export type CraftHistoryPersistence = CraftHistoryPersistenceStatic | CraftHistoryPersistenceDynamic;
+type HistoryOutput<Steps extends string> = {
+    readonly history: YieldableReactiveValue<readonly CraftHistoryEntry<Steps>[], 'history'>;
+    readonly historyCursor: YieldableReactiveValue<number, 'historyCursor'>;
+};
+/** What `withStateMachineHistory(...)` resolves to: an insertion for `craftStateMachine`. */
+type HistoryInsertion<Steps extends string, Features> = (context: CraftMachineInsertionContext<any, Steps, any>) => Generator<GetServiceYields<typeof StorageService>, HistoryOutput<Steps> & Features, unknown>;
+/**
+ * Records the machine's history, and composes features on top of it.
+ *
+ * History is not part of the machine core — it is an insertion, exactly like
+ * the derived values and step flags beside it:
+ *
+ * ```ts
+ * craftStateMachine(
+ *   contextFactory,
+ *   transitions,
+ *   stepContexts,
+ *   withStateMachineHistory(withBackNavigation()),
+ * );
+ * ```
+ *
+ * Every accepted transition appends an entry holding the new step and a
+ * snapshot of every primitive the machine owns, read through
+ * `CRAFT_PRIMITIVE_REGISTRY` and scoped to the machine's host chain. A
+ * primitive declared OUTSIDE the machine is not captured: pass it explicitly
+ * through `include` when it belongs to the story being replayed.
+ */
+export declare function withStateMachineHistory<Steps extends string = string>(): HistoryInsertion<Steps, object>;
+export declare function withStateMachineHistory<Feature1 extends object, Steps extends string = string>(feature1: CraftHistoryFeature<Feature1>): HistoryInsertion<Steps, Feature1>;
+export declare function withStateMachineHistory<Feature1 extends object, Feature2 extends object, Steps extends string = string>(feature1: CraftHistoryFeature<Feature1>, feature2: CraftHistoryFeature<Feature2>): HistoryInsertion<Steps, Feature1 & Feature2>;
+export declare function withStateMachineHistory<Feature1 extends object, Feature2 extends object, Feature3 extends object, Steps extends string = string>(feature1: CraftHistoryFeature<Feature1>, feature2: CraftHistoryFeature<Feature2>, feature3: CraftHistoryFeature<Feature3>): HistoryInsertion<Steps, Feature1 & Feature2 & Feature3>;
+export declare function withStateMachineHistory<Steps extends string = string>(options: HistoryOptions): HistoryInsertion<Steps, object>;
+export declare function withStateMachineHistory<Feature1 extends object, Steps extends string = string>(options: HistoryOptions, feature1: CraftHistoryFeature<Feature1>): HistoryInsertion<Steps, Feature1>;
+export declare function withStateMachineHistory<Feature1 extends object, Feature2 extends object, Steps extends string = string>(options: HistoryOptions, feature1: CraftHistoryFeature<Feature1>, feature2: CraftHistoryFeature<Feature2>): HistoryInsertion<Steps, Feature1 & Feature2>;
+export declare function withStateMachineHistory<Feature1 extends object, Feature2 extends object, Feature3 extends object, Steps extends string = string>(options: HistoryOptions, feature1: CraftHistoryFeature<Feature1>, feature2: CraftHistoryFeature<Feature2>, feature3: CraftHistoryFeature<Feature3>): HistoryInsertion<Steps, Feature1 & Feature2 & Feature3>;
+type BackNavigationOutput = {
+    readonly canGoBack: YieldableReactiveValue<boolean, 'canGoBack'>;
+    readonly canGoForward: YieldableReactiveValue<boolean, 'canGoForward'>;
+    readonly back: () => boolean;
+    readonly forward: () => boolean;
+};
+/**
+ * Step-by-step navigation through a machine's history. Composes into
+ * {@link withStateMachineHistory}, which owns the entries it walks:
+ *
+ * ```ts
+ * withStateMachineHistory(withBackNavigation())
+ * ```
+ *
+ * `back()` and `forward()` restore a recorded moment without asking the
+ * guards: that state was accepted once already.
+ */
+export declare function withBackNavigation(): CraftHistoryFeature<BackNavigationOutput>;
+export {};
+//# sourceMappingURL=craft-machine-history.d.ts.map

package/src/lib/craft-machine-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-machine-history.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-machine-history.ts"],"names":[],"mappings":"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"}