@craft-ts/core 0.7.0-beta.13

package/src/lib/craft-computed.d.ts.map

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

package/src/lib/craft-computed.js

@@ -0,0 +1,81 @@
+import { assertInInjectionContext, DestroyRef, inject, Injector, runInInjectionContext, } from './host/craft-compat';
+import { takeUntilDestroyed } from './host/craft-compat';
+import { craftComputed as createCraftComputed } from './host/craft-signal';
+import { ɵcreateHostTaggedInjector, ɵHOST_TAG_LIST } from './craft-service';
+import { isGeneratorFunction, runCraftGenerator, } from './craft-generator-runtime';
+import { APP_SNAPSHOT_REGISTRY } from './take-app-snapshot';
+import { createYieldableReactiveValue, REACTIVE_DEPENDENCIES, ɵactiveReactiveReader, } from './reactive-read';
+const createComputedWithOptions = createCraftComputed;
+export function craftComputed(nameOrComputation, hostOrComputation, factoryOrOptions, maybeOptions) {
+    const hasName = typeof nameOrComputation === 'string';
+    const name = hasName ? nameOrComputation : 'computed';
+    // The host form is recognized by its 3rd argument being the factory —
+    // `options` is never a function.
+    const hasHost = hasName && typeof factoryOrOptions === 'function';
+    const host = hasHost ? hostOrComputation : undefined;
+    const computationOrFactory = (hasHost ? factoryOrOptions : hasName ? hostOrComputation : nameOrComputation);
+    const options = (hasHost ? maybeOptions : hasName ? factoryOrOptions : hostOrComputation);
+    assertInInjectionContext(craftComputed);
+    const injector = inject(Injector);
+    const computedInjector = ɵcreateHostTaggedInjector(injector, `computed:${name}`);
+    let evaluate;
+    if (isGeneratorFunction(computationOrFactory)) {
+        evaluate = () => runInInjectionContext(computedInjector, () => {
+            const iterator = computationOrFactory.call(host);
+            return runCraftGenerator({
+                iterator,
+                injector: computedInjector,
+                hostScope: 'function',
+                invalidYieldErrorMessage: 'craftComputed generators can only yield Craft dependencies and reactive read requests; received an unknown yield.',
+                multipleAppStartErrorMessage: 'craftComputed generators cannot declare onAppStart(...) more than once.',
+                onAppStartNotSupportedErrorMessage: 'craftComputed(...) does not support onAppStart(...). Use onAppStart(...) only inside craftService({ appStart: true }, ...) generators.',
+                reactiveReader: ɵactiveReactiveReader() ?? {
+                    name,
+                    computed: name,
+                    path: name,
+                },
+            }).value;
+        });
+    }
+    else {
+        const computation = computationOrFactory;
+        evaluate = hasHost
+            ? () => computation.call(host)
+            : computation;
+    }
+    // One computation, tracked natively. Craft signals ARE the reactive graph
+    // now, so a read inside `evaluate` subscribes this computed on its own —
+    // there is nothing to capture, mirror or re-publish.
+    const result = createComputedWithOptions(evaluate, options);
+    const registry = inject(APP_SNAPSHOT_REGISTRY, { optional: true });
+    if (registry) {
+        const sig = result;
+        const from = computedInjector.get(ɵHOST_TAG_LIST, null) ?? [];
+        const destroyRef = computedInjector.get(DestroyRef, null);
+        if (destroyRef) {
+            registry.triggerSnapshot$
+                .pipe(takeUntilDestroyed(destroyRef))
+                .subscribe(() => {
+                let stateSnapshot;
+                try {
+                    stateSnapshot = sig();
+                }
+                catch (error) {
+                    stateSnapshot = {
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+                registry.allSnapShot$.next({
+                    source: name,
+                    from,
+                    state: stateSnapshot,
+                });
+            });
+        }
+    }
+    return createYieldableReactiveValue(result, name, {
+        computed: name,
+        path: name,
+    });
+}
+//# sourceMappingURL=craft-computed.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"craft-computed.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-computed.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  assertInInjectionContext,\n  DestroyRef,\n  inject,\n  Injector,\n  runInInjectionContext,\n  type CreateComputedOptions,\n  type Signal,\n} from './host/craft-compat';\nimport { takeUntilDestroyed } from './host/craft-compat';\nimport { craftComputed as createCraftComputed } from './host/craft-signal';\nimport type {\n  SERVICE_HELPER_DEPENDENCIES,\n  ServiceDependencyMapFromYielded,\n} from './craft-service';\nimport { ɵcreateHostTaggedInjector, ɵHOST_TAG_LIST } from './craft-service';\nimport {\n  isGeneratorFunction,\n  runCraftGenerator,\n} from './craft-generator-runtime';\nimport type { ExtractCraftGenExceptions } from './craft-gen';\nimport type {\n  CraftSettledBrand,\n  ExtractCraftPendingSources,\n} from './craft-settled';\nimport { APP_SNAPSHOT_REGISTRY } from './take-app-snapshot';\nimport {\n  createYieldableReactiveValue,\n  REACTIVE_DEPENDENCIES,\n  type ReactiveDependencyMapFromYielded,\n  ɵactiveReactiveReader,\n  type YieldableReactiveValue,\n} from './reactive-read';\n\nconst createComputedWithOptions = createCraftComputed as unknown as <T>(\n  computation: () => T,\n  options?: CreateComputedOptions<T>,\n) => Signal<T>;\n\ntype CraftComputedGenerator<This, Yielded, T> = (\n  this: This,\n) => Generator<Yielded, T, unknown>;\n\n/**\n * A computation that read a `settledValue` through `yield* settled(...)` inherits\n * its source's two obligations: the async source must be covered by a\n * `pendingBlock`, and its exceptions by a `catchBlock`. Both travel as the\n * {@link CraftSettledBrand} of the resulting signal, so a template rendering it\n * is checked exactly as if it rendered the `settledValue` itself.\n *\n * Computations with no async dependency keep their previous exact type.\n */\ntype SettledBrandFromYielded<Yielded> = [\n  ExtractCraftPendingSources<Yielded>,\n] extends [never]\n  ? {}\n  : CraftSettledBrand<\n      ExtractCraftPendingSources<Yielded>,\n      ExtractCraftGenExceptions<Yielded>\n    >;\n\ntype TrackedCraftComputed<\n  Name extends string,\n  T,\n  Yielded,\n> = YieldableReactiveValue<T, Name> & {\n  readonly [SERVICE_HELPER_DEPENDENCIES]?: ServiceDependencyMapFromYielded<Yielded>;\n} & ([ReactiveDependencyMapFromYielded<Yielded>] extends [never]\n    ? {}\n    : {\n        readonly [REACTIVE_DEPENDENCIES]?: ReactiveDependencyMapFromYielded<Yielded>;\n      }) &\n  SettledBrandFromYielded<Yielded>;\n\n// Host-bound forms — `craftComputed('name', this, function* () { ... })` — bind\n// `this` inside the factory (and the computation it returns) to the given host,\n// so a class-field initializer can read instance state (mirrors `craftMethod`).\n// Without a host, a `function*` factory is called with `this = undefined`.\n// The generator overloads must come first: a generator function also matches\n// `() => T` (with `T` inferred as the whole `Generator<...>`), so the plain\n// overload would otherwise win and type the signal as `Signal<Generator<...>>`.\nexport function craftComputed<Name extends string, This, Yielded, T>(\n  name: Name,\n  host: This,\n  factory: CraftComputedGenerator<This, Yielded, T>,\n  options?: CreateComputedOptions<T>,\n): TrackedCraftComputed<Name, T, Yielded>;\nexport function craftComputed<Name extends string, Yielded, T>(\n  name: Name,\n  factory: CraftComputedGenerator<void, Yielded, T>,\n  options?: CreateComputedOptions<T>,\n): TrackedCraftComputed<Name, T, Yielded>;\nexport function craftComputed<Name extends string, This, T>(\n  name: Name,\n  host: This,\n  computation: (this: This) => T,\n  options?: CreateComputedOptions<T>,\n): TrackedCraftComputed<Name, T, never>;\nexport function craftComputed<Name extends string, T>(\n  name: Name,\n  computation: () => T,\n  options?: CreateComputedOptions<T>,\n): TrackedCraftComputed<Name, T, never>;\nexport function craftComputed<Yielded, T>(\n  factory: CraftComputedGenerator<void, Yielded, T>,\n  options?: CreateComputedOptions<T>,\n): TrackedCraftComputed<'computed', T, Yielded>;\nexport function craftComputed<T>(\n  computation: () => T,\n  options?: CreateComputedOptions<T>,\n): TrackedCraftComputed<'computed', T, never>;\nexport function craftComputed<T>(\n  nameOrComputation: string | ((...args: never[]) => unknown),\n  hostOrComputation?: unknown,\n  factoryOrOptions?: unknown,\n  maybeOptions?: CreateComputedOptions<T>,\n): TrackedCraftComputed<string, T, unknown> {\n  const hasName = typeof nameOrComputation === 'string';\n  const name = hasName ? nameOrComputation : 'computed';\n  // The host form is recognized by its 3rd argument being the factory —\n  // `options` is never a function.\n  const hasHost = hasName && typeof factoryOrOptions === 'function';\n  const host = hasHost ? hostOrComputation : undefined;\n  const computationOrFactory = (\n    hasHost ? factoryOrOptions : hasName ? hostOrComputation : nameOrComputation\n  ) as ((this: unknown) => T) | CraftComputedGenerator<unknown, unknown, T>;\n  const options = (\n    hasHost ? maybeOptions : hasName ? factoryOrOptions : hostOrComputation\n  ) as CreateComputedOptions<T> | undefined;\n\n  assertInInjectionContext(craftComputed);\n  const injector = inject(Injector);\n  const computedInjector = ɵcreateHostTaggedInjector(\n    injector,\n    `computed:${name}`,\n  );\n\n  let evaluate: () => T;\n  if (isGeneratorFunction(computationOrFactory)) {\n    evaluate = () =>\n      runInInjectionContext(computedInjector, () => {\n        const iterator = (\n          computationOrFactory as CraftComputedGenerator<unknown, unknown, T>\n        ).call(host);\n        return runCraftGenerator({\n          iterator,\n          injector: computedInjector,\n          hostScope: 'function',\n          invalidYieldErrorMessage:\n            'craftComputed generators can only yield Craft dependencies and reactive read requests; received an unknown yield.',\n          multipleAppStartErrorMessage:\n            'craftComputed generators cannot declare onAppStart(...) more than once.',\n          onAppStartNotSupportedErrorMessage:\n            'craftComputed(...) does not support onAppStart(...). Use onAppStart(...) only inside craftService({ appStart: true }, ...) generators.',\n          reactiveReader: ɵactiveReactiveReader() ?? {\n            name,\n            computed: name,\n            path: name,\n          },\n        }).value as T;\n      });\n  } else {\n    const computation = computationOrFactory as (this: unknown) => T;\n    evaluate = hasHost\n      ? () => computation.call(host)\n      : (computation as () => T);\n  }\n\n  // One computation, tracked natively. Craft signals ARE the reactive graph\n  // now, so a read inside `evaluate` subscribes this computed on its own —\n  // there is nothing to capture, mirror or re-publish.\n  const result = createComputedWithOptions(evaluate, options) as Signal<T>;\n\n  const registry = inject(APP_SNAPSHOT_REGISTRY, { optional: true });\n  if (registry) {\n    const sig = result;\n    const from = computedInjector.get(ɵHOST_TAG_LIST, null) ?? [];\n    const destroyRef = computedInjector.get(DestroyRef, null);\n    if (destroyRef) {\n      registry.triggerSnapshot$\n        .pipe(takeUntilDestroyed(destroyRef))\n        .subscribe(() => {\n          let stateSnapshot: unknown;\n          try {\n            stateSnapshot = sig();\n          } catch (error) {\n            stateSnapshot = {\n              error: error instanceof Error ? error.message : String(error),\n            };\n          }\n          registry.allSnapShot$.next({\n            source: name,\n            from,\n            state: stateSnapshot,\n          });\n        });\n    }\n  }\n\n  return createYieldableReactiveValue(result, name, {\n    computed: name,\n    path: name,\n  }) as unknown as TrackedCraftComputed<string, T, unknown>;\n}\n"]}

package/src/lib/craft-control-flow.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns whether `value` is an internal CraftTS control-flow throw.
+ *
+ * These values use JavaScript's exception channel to suspend or short-circuit
+ * a computation until a CraftTS boundary handles them. They are expected
+ * during normal rendering and must not be reported as application failures by
+ * generic logging, snapshot, or error-conversion wrappers.
+ *
+ * An unhandled boundary error such as `CraftUnhandledPendingError` is not
+ * included: it represents a missing template boundary and should remain
+ * observable.
+ */
+export declare function isCraftControlFlow(value: unknown): boolean;
+//# sourceMappingURL=craft-control-flow.d.ts.map

package/src/lib/craft-control-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-control-flow.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-control-flow.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D"}

package/src/lib/craft-control-flow.js

@@ -0,0 +1,18 @@
+import { isCraftGenShortCircuit } from './craft-gen';
+import { isCraftNotSettled } from './craft-settled';
+/**
+ * Returns whether `value` is an internal CraftTS control-flow throw.
+ *
+ * These values use JavaScript's exception channel to suspend or short-circuit
+ * a computation until a CraftTS boundary handles them. They are expected
+ * during normal rendering and must not be reported as application failures by
+ * generic logging, snapshot, or error-conversion wrappers.
+ *
+ * An unhandled boundary error such as `CraftUnhandledPendingError` is not
+ * included: it represents a missing template boundary and should remain
+ * observable.
+ */
+export function isCraftControlFlow(value) {
+    return isCraftGenShortCircuit(value) || isCraftNotSettled(value);
+}
+//# sourceMappingURL=craft-control-flow.js.map

package/src/lib/craft-control-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-control-flow.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-control-flow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,sBAAsB,CAAC,KAAK,CAAC,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC","sourcesContent":["import { isCraftGenShortCircuit } from './craft-gen';\nimport { isCraftNotSettled } from './craft-settled';\n\n/**\n * Returns whether `value` is an internal CraftTS control-flow throw.\n *\n * These values use JavaScript's exception channel to suspend or short-circuit\n * a computation until a CraftTS boundary handles them. They are expected\n * during normal rendering and must not be reported as application failures by\n * generic logging, snapshot, or error-conversion wrappers.\n *\n * An unhandled boundary error such as `CraftUnhandledPendingError` is not\n * included: it represents a missing template boundary and should remain\n * observable.\n */\nexport function isCraftControlFlow(value: unknown): boolean {\n  return isCraftGenShortCircuit(value) || isCraftNotSettled(value);\n}\n"]}

package/src/lib/craft-effect.d.ts

@@ -0,0 +1,13 @@
+import { type CreateEffectOptions, type EffectCleanupRegisterFn, type EffectRef } from './host/craft-compat';
+import type { SERVICE_HELPER_DEPENDENCIES, ServiceDependencyMapFromYielded } from './craft-service';
+type CraftEffectFn = (onCleanup: EffectCleanupRegisterFn) => void;
+type CraftEffectGenerator<This, Yielded> = (this: This) => Generator<Yielded, CraftEffectFn, unknown>;
+type TrackedCraftEffect<E, Yielded> = E & {
+    readonly [SERVICE_HELPER_DEPENDENCIES]?: ServiceDependencyMapFromYielded<Yielded>;
+};
+export declare function craftEffect<Name extends string, This, Yielded>(name: Name, host: This, factory: CraftEffectGenerator<This, Yielded>, options?: CreateEffectOptions): TrackedCraftEffect<EffectRef, Yielded>;
+export declare function craftEffect<Name extends string, Yielded>(name: Name, factory: CraftEffectGenerator<void, Yielded>, options?: CreateEffectOptions): TrackedCraftEffect<EffectRef, Yielded>;
+export declare function craftEffect<Name extends string, This>(name: Name, host: This, effectFn: (this: This, onCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions): EffectRef;
+export declare function craftEffect<Name extends string>(name: Name, effectFn: CraftEffectFn, options?: CreateEffectOptions): EffectRef;
+export {};
+//# sourceMappingURL=craft-effect.d.ts.map

package/src/lib/craft-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-effect.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-effect.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EACV,2BAA2B,EAC3B,+BAA+B,EAChC,MAAM,iBAAiB,CAAC;AAQzB,KAAK,aAAa,GAAG,CAAC,SAAS,EAAE,uBAAuB,KAAK,IAAI,CAAC;AAElE,KAAK,oBAAoB,CAAC,IAAI,EAAE,OAAO,IAAI,CACzC,IAAI,EAAE,IAAI,KACP,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;AAEhD,KAAK,kBAAkB,CAAC,CAAC,EAAE,OAAO,IAAI,CAAC,GAAG;IACxC,QAAQ,CAAC,CAAC,2BAA2B,CAAC,CAAC,EAAE,+BAA+B,CAAC,OAAO,CAAC,CAAC;CACnF,CAAC;AASF,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,OAAO,EAC5D,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,OAAO,CAAC,EAC5C,OAAO,CAAC,EAAE,mBAAmB,GAC5B,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAC1C,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,OAAO,EACtD,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,OAAO,CAAC,EAC5C,OAAO,CAAC,EAAE,mBAAmB,GAC5B,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAC1C,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EACnD,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,uBAAuB,KAAK,IAAI,EAClE,OAAO,CAAC,EAAE,mBAAmB,GAC5B,SAAS,CAAC;AACb,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAC7C,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,SAAS,CAAC"}

package/src/lib/craft-effect.js

@@ -0,0 +1,93 @@
+import { assertInInjectionContext, DestroyRef, effect, inject, Injector, runInInjectionContext, signal, untracked, } from './host/craft-compat';
+import { takeUntilDestroyed } from './host/craft-compat';
+import { ɵcraftInjectorFromHost } from './host/craft-injector-host';
+import { craftWatch } from './host/craft-signal';
+import { ɵcreateHostTaggedInjector, ɵHOST_TAG_LIST } from './craft-service';
+import { isGeneratorFunction, runCraftGenerator, } from './craft-generator-runtime';
+import { APP_SNAPSHOT_REGISTRY } from './take-app-snapshot';
+export function craftEffect(name, hostOrFn, fnOrOptions, maybeOptions) {
+    // The host form is recognized by its 3rd argument being the factory —
+    // `options` is never a function.
+    const hasHost = typeof fnOrOptions === 'function';
+    const host = hasHost ? hostOrFn : undefined;
+    const fnOrFactory = (hasHost ? fnOrOptions : hostOrFn);
+    const options = (hasHost ? maybeOptions : fnOrOptions);
+    assertInInjectionContext(craftEffect);
+    const parentInjector = inject(Injector);
+    const ownerInjector = ɵcraftInjectorFromHost(options?.injector ?? parentInjector);
+    const ownerDestroyRef = ownerInjector.get(DestroyRef);
+    const effectInjector = ɵcreateHostTaggedInjector(ownerInjector, `effect:${name}`);
+    let effectBody;
+    if (isGeneratorFunction(fnOrFactory)) {
+        effectBody = runInInjectionContext(effectInjector, () => {
+            const iterator = fnOrFactory.call(host);
+            return runCraftGenerator({
+                iterator,
+                injector: effectInjector,
+                hostScope: 'function',
+                invalidYieldErrorMessage: 'craftEffect generators can only yield craftService dependencies.',
+                multipleAppStartErrorMessage: 'craftEffect generators cannot declare onAppStart(...) more than once.',
+                onAppStartNotSupportedErrorMessage: 'craftEffect(...) does not support onAppStart(...). Use onAppStart(...) only inside craftService({ appStart: true }, ...) generators.',
+            }).value;
+        });
+    }
+    else {
+        const plainFn = fnOrFactory;
+        effectBody = hasHost
+            ? (onCleanup) => plainFn.call(host, onCleanup)
+            : plainFn;
+    }
+    const craftInvalidation = signal(0);
+    let craftRef;
+    let destroyed = false;
+    const angularRef = effect(() => {
+        craftInvalidation();
+        craftRef?.destroy();
+        let initialRun = true;
+        craftRef = craftWatch(() => {
+            if (initialRun) {
+                const cleanups = [];
+                effectBody((cleanup) => cleanups.push(cleanup));
+                return cleanups.length === 0
+                    ? undefined
+                    : () => {
+                        for (const cleanup of cleanups)
+                            cleanup();
+                    };
+            }
+            untracked(() => craftInvalidation.update((revision) => revision + 1));
+            return undefined;
+        });
+        initialRun = false;
+    }, {
+        ...options,
+        injector: ownerInjector,
+        manualCleanup: true,
+    });
+    const ref = {
+        destroy: () => {
+            if (destroyed)
+                return;
+            destroyed = true;
+            angularRef.destroy();
+            craftRef?.destroy();
+        },
+    };
+    if (!options?.manualCleanup) {
+        ownerDestroyRef.onDestroy(() => ref.destroy());
+    }
+    const registry = ownerInjector.get(APP_SNAPSHOT_REGISTRY, null);
+    if (registry) {
+        const from = effectInjector.get(ɵHOST_TAG_LIST, null) ?? [];
+        registry.triggerSnapshot$
+            .pipe(takeUntilDestroyed(ownerDestroyRef))
+            .subscribe(() => {
+            registry.allActiveEffects$.next({
+                source: `effect:${name}`,
+                from,
+            });
+        });
+    }
+    return ref;
+}
+//# sourceMappingURL=craft-effect.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"craft-effect.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-effect.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  assertInInjectionContext,\n  DestroyRef,\n  effect,\n  inject,\n  Injector,\n  runInInjectionContext,\n  signal,\n  untracked,\n  type CreateEffectOptions,\n  type EffectCleanupRegisterFn,\n  type EffectRef,\n} from './host/craft-compat';\nimport { takeUntilDestroyed } from './host/craft-compat';\nimport { ɵcraftInjectorFromHost } from './host/craft-injector-host';\nimport { craftWatch } from './host/craft-signal';\nimport type {\n  SERVICE_HELPER_DEPENDENCIES,\n  ServiceDependencyMapFromYielded,\n} from './craft-service';\nimport { ɵcreateHostTaggedInjector, ɵHOST_TAG_LIST } from './craft-service';\nimport {\n  isGeneratorFunction,\n  runCraftGenerator,\n} from './craft-generator-runtime';\nimport { APP_SNAPSHOT_REGISTRY } from './take-app-snapshot';\n\ntype CraftEffectFn = (onCleanup: EffectCleanupRegisterFn) => void;\n\ntype CraftEffectGenerator<This, Yielded> = (\n  this: This,\n) => Generator<Yielded, CraftEffectFn, unknown>;\n\ntype TrackedCraftEffect<E, Yielded> = E & {\n  readonly [SERVICE_HELPER_DEPENDENCIES]?: ServiceDependencyMapFromYielded<Yielded>;\n};\n\n// Host-bound forms — `craftEffect('name', this, function* () { ... })` — bind\n// `this` inside the factory (and the effect body it returns) to the given host,\n// so a class-field initializer can read instance state (mirrors `craftMethod`).\n// Without a host, a `function*` factory is called with `this = undefined`.\n// The generator overloads must come first: a generator function is also\n// assignable to `CraftEffectFn` (a `void` return accepts anything), so the\n// plain overload would otherwise win and drop the dependency metadata.\nexport function craftEffect<Name extends string, This, Yielded>(\n  name: Name,\n  host: This,\n  factory: CraftEffectGenerator<This, Yielded>,\n  options?: CreateEffectOptions,\n): TrackedCraftEffect<EffectRef, Yielded>;\nexport function craftEffect<Name extends string, Yielded>(\n  name: Name,\n  factory: CraftEffectGenerator<void, Yielded>,\n  options?: CreateEffectOptions,\n): TrackedCraftEffect<EffectRef, Yielded>;\nexport function craftEffect<Name extends string, This>(\n  name: Name,\n  host: This,\n  effectFn: (this: This, onCleanup: EffectCleanupRegisterFn) => void,\n  options?: CreateEffectOptions,\n): EffectRef;\nexport function craftEffect<Name extends string>(\n  name: Name,\n  effectFn: CraftEffectFn,\n  options?: CreateEffectOptions,\n): EffectRef;\nexport function craftEffect(\n  name: string,\n  hostOrFn: unknown,\n  fnOrOptions?: unknown,\n  maybeOptions?: CreateEffectOptions,\n): EffectRef {\n  // The host form is recognized by its 3rd argument being the factory —\n  // `options` is never a function.\n  const hasHost = typeof fnOrOptions === 'function';\n  const host = hasHost ? hostOrFn : undefined;\n  const fnOrFactory = (hasHost ? fnOrOptions : hostOrFn) as\n    | ((this: unknown, onCleanup: EffectCleanupRegisterFn) => void)\n    | CraftEffectGenerator<unknown, unknown>;\n  const options = (hasHost ? maybeOptions : fnOrOptions) as\n    | CreateEffectOptions\n    | undefined;\n\n  assertInInjectionContext(craftEffect);\n  const parentInjector = inject(Injector);\n  const ownerInjector = ɵcraftInjectorFromHost(\n    options?.injector ?? parentInjector,\n  );\n  const ownerDestroyRef = ownerInjector.get(DestroyRef);\n  const effectInjector = ɵcreateHostTaggedInjector(\n    ownerInjector,\n    `effect:${name}`,\n  );\n\n  let effectBody: CraftEffectFn;\n\n  if (isGeneratorFunction(fnOrFactory)) {\n    effectBody = runInInjectionContext(effectInjector, () => {\n      const iterator = (\n        fnOrFactory as CraftEffectGenerator<unknown, unknown>\n      ).call(host);\n      return runCraftGenerator({\n        iterator,\n        injector: effectInjector,\n        hostScope: 'function',\n        invalidYieldErrorMessage:\n          'craftEffect generators can only yield craftService dependencies.',\n        multipleAppStartErrorMessage:\n          'craftEffect generators cannot declare onAppStart(...) more than once.',\n        onAppStartNotSupportedErrorMessage:\n          'craftEffect(...) does not support onAppStart(...). Use onAppStart(...) only inside craftService({ appStart: true }, ...) generators.',\n      }).value as CraftEffectFn;\n    });\n  } else {\n    const plainFn = fnOrFactory as (\n      this: unknown,\n      onCleanup: EffectCleanupRegisterFn,\n    ) => void;\n    effectBody = hasHost\n      ? (onCleanup) => plainFn.call(host, onCleanup)\n      : (plainFn as CraftEffectFn);\n  }\n\n  const craftInvalidation = signal(0);\n  let craftRef: { destroy(): void } | undefined;\n  let destroyed = false;\n  const angularRef = effect(\n    () => {\n      craftInvalidation();\n      craftRef?.destroy();\n      let initialRun = true;\n      craftRef = craftWatch(() => {\n        if (initialRun) {\n          const cleanups: (() => void)[] = [];\n          effectBody((cleanup) => cleanups.push(cleanup));\n          return cleanups.length === 0\n            ? undefined\n            : () => {\n                for (const cleanup of cleanups) cleanup();\n              };\n        }\n        untracked(() => craftInvalidation.update((revision) => revision + 1));\n        return undefined;\n      });\n      initialRun = false;\n    },\n    {\n      ...options,\n      injector: ownerInjector,\n      manualCleanup: true,\n    },\n  );\n  const ref = {\n    destroy: () => {\n      if (destroyed) return;\n      destroyed = true;\n      angularRef.destroy();\n      craftRef?.destroy();\n    },\n  } as EffectRef;\n  if (!options?.manualCleanup) {\n    ownerDestroyRef.onDestroy(() => ref.destroy());\n  }\n\n  const registry = ownerInjector.get(APP_SNAPSHOT_REGISTRY, null);\n  if (registry) {\n    const from = effectInjector.get(ɵHOST_TAG_LIST, null) ?? [];\n    registry.triggerSnapshot$\n      .pipe(takeUntilDestroyed(ownerDestroyRef))\n      .subscribe(() => {\n        registry.allActiveEffects$.next({\n          source: `effect:${name}`,\n          from,\n        });\n      });\n  }\n\n  return ref;\n}\n"]}

package/src/lib/craft-exception.d.ts

@@ -0,0 +1,40 @@
+export declare const CRAFT_EXCEPTION_SYMBOL: unique symbol;
+export type CraftExceptionMeta<Code extends string = string, Scope extends string | undefined = string | undefined, Identifier extends string | undefined = string | undefined> = {
+    _tag: Code;
+    scope?: Scope;
+    identifier?: Identifier;
+};
+export type CraftExceptionResult<Meta extends CraftExceptionMeta, Payload = unknown> = {
+    readonly [CRAFT_EXCEPTION_SYMBOL]: true;
+    readonly payload: Payload;
+} & Meta & {
+    [key in Meta['_tag']]: Payload;
+};
+export type CraftException<Meta extends CraftExceptionMeta = CraftExceptionMeta, Payload = unknown> = CraftExceptionResult<Meta, Payload>;
+export type AnyCraftException = CraftExceptionResult<CraftExceptionMeta, unknown>;
+export declare function craftException<const Code extends string, Scope extends string | undefined = undefined, Identifier extends string | undefined = undefined, Payload = undefined>(meta: {
+    _tag: Code;
+    scope?: Scope;
+    identifier?: Identifier;
+}, payload?: Payload): CraftExceptionResult<{
+    _tag: Code;
+    scope: Scope;
+    identifier?: Identifier;
+}, Payload>;
+export declare function isCraftException(value: unknown): value is AnyCraftException;
+export type StripCraftException<T> = Exclude<T, AnyCraftException>;
+export type ExtractCraftException<T> = Extract<T, AnyCraftException>;
+export type InsertMetaInCraftExceptionIfExists<Exception, Scope extends string | undefined, Identifier extends string | undefined | unknown> = Exception extends CraftExceptionResult<infer CraftExceptionMeta, infer Payload> ? [unknown] extends [Identifier] ? CraftExceptionResult<{
+    _tag: CraftExceptionMeta['_tag'];
+    scope: Scope;
+}, Payload> : [Identifier] extends [string] ? CraftExceptionResult<{
+    _tag: CraftExceptionMeta['_tag'];
+    scope: Scope;
+    identifier: Identifier;
+}, Payload> : CraftExceptionResult<{
+    _tag: CraftExceptionMeta['_tag'];
+    scope: Scope;
+}, Payload> : Exception;
+export type ExtractCodeFromCraftResultUnion<T> = T extends CraftExceptionResult<infer E, any> ? E['_tag'] : never;
+export type ExcludeByCode<T, C> = T extends CraftExceptionResult<infer E, any> ? E['_tag'] extends C ? never : T : never;
+//# sourceMappingURL=craft-exception.d.ts.map

package/src/lib/craft-exception.d.ts.map

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

package/src/lib/craft-exception.js

@@ -0,0 +1,16 @@
+export const CRAFT_EXCEPTION_SYMBOL = Symbol('CRAFT_EXCEPTION_SYMBOL');
+export function craftException(meta, payload) {
+    const result = {
+        [CRAFT_EXCEPTION_SYMBOL]: true,
+        _tag: meta._tag,
+        scope: meta.scope,
+        ...(meta.identifier !== undefined ? { identifier: meta.identifier } : {}),
+        payload: payload,
+        [meta._tag]: payload,
+    };
+    return result;
+}
+export function isCraftException(value) {
+    return (!!value && typeof value === 'object' && CRAFT_EXCEPTION_SYMBOL in value);
+}
+//# sourceMappingURL=craft-exception.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"craft-exception.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-exception.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;AAgCvE,MAAM,UAAU,cAAc,CAM5B,IAIC,EACD,OAAiB;IASjB,MAAM,MAAM,GAAG;QACb,CAAC,sBAAsB,CAAC,EAAE,IAAa;QACvC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAc;QAC1B,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,OAAO,EAAE,OAAkB;QAC3B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,OAAkB;KAChC,CAAC;IAEF,OAAO,MAON,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,sBAAsB,IAAI,KAAK,CACxE,CAAC;AACJ,CAAC","sourcesContent":["export const CRAFT_EXCEPTION_SYMBOL = Symbol('CRAFT_EXCEPTION_SYMBOL');\n\nexport type CraftExceptionMeta<\n  Code extends string = string,\n  Scope extends string | undefined = string | undefined,\n  Identifier extends string | undefined = string | undefined,\n> = {\n  _tag: Code;\n  scope?: Scope;\n  identifier?: Identifier;\n};\n\nexport type CraftExceptionResult<\n  Meta extends CraftExceptionMeta,\n  Payload = unknown,\n> = {\n  readonly [CRAFT_EXCEPTION_SYMBOL]: true;\n  readonly payload: Payload;\n} & Meta & {\n    [key in Meta['_tag']]: Payload;\n  };\n\nexport type CraftException<\n  Meta extends CraftExceptionMeta = CraftExceptionMeta,\n  Payload = unknown,\n> = CraftExceptionResult<Meta, Payload>;\n\nexport type AnyCraftException = CraftExceptionResult<\n  CraftExceptionMeta,\n  unknown\n>;\n\nexport function craftException<\n  const Code extends string,\n  Scope extends string | undefined = undefined,\n  Identifier extends string | undefined = undefined,\n  Payload = undefined,\n>(\n  meta: {\n    _tag: Code;\n    scope?: Scope;\n    identifier?: Identifier;\n  },\n  payload?: Payload,\n): CraftExceptionResult<\n  {\n    _tag: Code;\n    scope: Scope;\n    identifier?: Identifier;\n  },\n  Payload\n> {\n  const result = {\n    [CRAFT_EXCEPTION_SYMBOL]: true as const,\n    _tag: meta._tag,\n    scope: meta.scope as Scope,\n    ...(meta.identifier !== undefined ? { identifier: meta.identifier } : {}),\n    payload: payload as Payload,\n    [meta._tag]: payload as Payload,\n  };\n\n  return result as CraftExceptionResult<\n    {\n      _tag: Code;\n      scope: Scope;\n      identifier?: Identifier;\n    },\n    Payload\n  >;\n}\n\nexport function isCraftException(value: unknown): value is AnyCraftException {\n  return (\n    !!value && typeof value === 'object' && CRAFT_EXCEPTION_SYMBOL in value\n  );\n}\n\nexport type StripCraftException<T> = Exclude<T, AnyCraftException>;\nexport type ExtractCraftException<T> = Extract<T, AnyCraftException>;\n\nexport type InsertMetaInCraftExceptionIfExists<\n  Exception,\n  Scope extends string | undefined,\n  Identifier extends string | undefined | unknown,\n> =\n  Exception extends CraftExceptionResult<\n    infer CraftExceptionMeta,\n    infer Payload\n  >\n    ? [unknown] extends [Identifier]\n      ? CraftExceptionResult<\n          {\n            _tag: CraftExceptionMeta['_tag'];\n            scope: Scope;\n          },\n          Payload\n        >\n      : [Identifier] extends [string]\n        ? CraftExceptionResult<\n            {\n              _tag: CraftExceptionMeta['_tag'];\n              scope: Scope;\n              identifier: Identifier;\n            },\n            Payload\n          >\n        : CraftExceptionResult<\n            {\n              _tag: CraftExceptionMeta['_tag'];\n              scope: Scope;\n            },\n            Payload\n          >\n    : Exception;\n\nexport type ExtractCodeFromCraftResultUnion<T> =\n  T extends CraftExceptionResult<infer E, any> ? E['_tag'] : never;\n\nexport type ExcludeByCode<T, C> =\n  T extends CraftExceptionResult<infer E, any>\n    ? E['_tag'] extends C\n      ? never\n      : T\n    : never;\n"]}

package/src/lib/craft-gen.d.ts

@@ -0,0 +1,123 @@
+import { type AnyCraftException, type ExtractCraftException, type StripCraftException } from './craft-exception';
+declare const CRAFT_GEN_EXCEPTION_MARKER: unique symbol;
+declare const CRAFT_GEN_SHORT_CIRCUIT: unique symbol;
+declare const CRAFT_PROGRAM_RECREATE: unique symbol;
+/**
+ * Type-level marker surfaced by a {@link craftGen} invocation's `Yielded`. It
+ * carries the union of {@link AnyCraftException} the generator may produce so a
+ * composing generator (and a route's `canActivate`/`canMatch`) can read the
+ * reachable exception codes off its `Yielded`.
+ *
+ * It is **never** yielded at runtime — the short-circuit is a native `throw` of
+ * {@link CraftGenShortCircuit}. The marker is also intentionally NOT a
+ * `ServiceYieldRequest`, so `ServiceDependencyMapFromYielded` / `RouteGuardDepsMap`
+ * ignore it and route provider stripping is unaffected.
+ */
+export interface CraftGenExceptionMarker<Exception> {
+    readonly [CRAFT_GEN_EXCEPTION_MARKER]: Exception;
+}
+/** Extracts the union of exceptions advertised by the markers in `Yielded`. */
+export type ExtractCraftGenExceptions<Yielded> = [
+    Extract<Yielded, CraftGenExceptionMarker<any>>
+] extends [never] ? never : Extract<Yielded, CraftGenExceptionMarker<any>> extends CraftGenExceptionMarker<infer Exception> ? Exception : never;
+type AnyGeneratorFactory = (...args: any[]) => Generator<any, any, any>;
+type GeneratorFactoryArgs<GenFn> = GenFn extends (...args: infer Args) => Generator<any, any, any> ? Args : never;
+type GeneratorFactoryYielded<GenFn> = GenFn extends (...args: any[]) => Generator<infer Yielded, any, any> ? Yielded : never;
+type GeneratorFactoryOutput<GenFn> = GenFn extends (...args: any[]) => Generator<any, infer Output, any> ? Output : never;
+type CraftProgramGen<Yielded, Return> = Generator<Yielded, Return, unknown>;
+/**
+ * The `.pipe(...)` method carried by every craft program (a {@link craftGen}
+ * invocation or the result of a previous `.pipe`). Applies program operators
+ * left-to-right; each operator receives the piped generator and returns a new
+ * one (see `CraftProgramOperator` in craft-program-operators). Arities are
+ * explicit (1..7) to keep inference flat — no recursive conditional types.
+ */
+export interface CraftProgramPipe<Yielded, Return> {
+    <Y1, R1>(op1: (program: CraftProgramGen<Yielded, Return>) => CraftProgramGen<Y1, R1>): CraftPipeableProgram<Y1, R1>;
+    <Y1, R1, Y2, R2>(op1: (program: CraftProgramGen<Yielded, Return>) => CraftProgramGen<Y1, R1>, op2: (program: CraftProgramGen<Y1, R1>) => CraftProgramGen<Y2, R2>): CraftPipeableProgram<Y2, R2>;
+    <Y1, R1, Y2, R2, Y3, R3>(op1: (program: CraftProgramGen<Yielded, Return>) => CraftProgramGen<Y1, R1>, op2: (program: CraftProgramGen<Y1, R1>) => CraftProgramGen<Y2, R2>, op3: (program: CraftProgramGen<Y2, R2>) => CraftProgramGen<Y3, R3>): CraftPipeableProgram<Y3, R3>;
+    <Y1, R1, Y2, R2, Y3, R3, Y4, R4>(op1: (program: CraftProgramGen<Yielded, Return>) => CraftProgramGen<Y1, R1>, op2: (program: CraftProgramGen<Y1, R1>) => CraftProgramGen<Y2, R2>, op3: (program: CraftProgramGen<Y2, R2>) => CraftProgramGen<Y3, R3>, op4: (program: CraftProgramGen<Y3, R3>) => CraftProgramGen<Y4, R4>): CraftPipeableProgram<Y4, R4>;
+    <Y1, R1, Y2, R2, Y3, R3, Y4, R4, Y5, R5>(op1: (program: CraftProgramGen<Yielded, Return>) => CraftProgramGen<Y1, R1>, op2: (program: CraftProgramGen<Y1, R1>) => CraftProgramGen<Y2, R2>, op3: (program: CraftProgramGen<Y2, R2>) => CraftProgramGen<Y3, R3>, op4: (program: CraftProgramGen<Y3, R3>) => CraftProgramGen<Y4, R4>, op5: (program: CraftProgramGen<Y4, R4>) => CraftProgramGen<Y5, R5>): CraftPipeableProgram<Y5, R5>;
+    <Y1, R1, Y2, R2, Y3, R3, Y4, R4, Y5, R5, Y6, R6>(op1: (program: CraftProgramGen<Yielded, Return>) => CraftProgramGen<Y1, R1>, op2: (program: CraftProgramGen<Y1, R1>) => CraftProgramGen<Y2, R2>, op3: (program: CraftProgramGen<Y2, R2>) => CraftProgramGen<Y3, R3>, op4: (program: CraftProgramGen<Y3, R3>) => CraftProgramGen<Y4, R4>, op5: (program: CraftProgramGen<Y4, R4>) => CraftProgramGen<Y5, R5>, op6: (program: CraftProgramGen<Y5, R5>) => CraftProgramGen<Y6, R6>): CraftPipeableProgram<Y6, R6>;
+    <Y1, R1, Y2, R2, Y3, R3, Y4, R4, Y5, R5, Y6, R6, Y7, R7>(op1: (program: CraftProgramGen<Yielded, Return>) => CraftProgramGen<Y1, R1>, op2: (program: CraftProgramGen<Y1, R1>) => CraftProgramGen<Y2, R2>, op3: (program: CraftProgramGen<Y2, R2>) => CraftProgramGen<Y3, R3>, op4: (program: CraftProgramGen<Y3, R3>) => CraftProgramGen<Y4, R4>, op5: (program: CraftProgramGen<Y4, R4>) => CraftProgramGen<Y5, R5>, op6: (program: CraftProgramGen<Y5, R5>) => CraftProgramGen<Y6, R6>, op7: (program: CraftProgramGen<Y6, R6>) => CraftProgramGen<Y7, R7>): CraftPipeableProgram<Y7, R7>;
+}
+/**
+ * A craft program: a `yield*`-composable generator augmented with `.pipe(...)`.
+ * `Yielded` already carries the program's {@link CraftGenExceptionMarker}s.
+ */
+export type CraftPipeableProgram<Yielded, Return> = Generator<Yielded, Return, unknown> & {
+    pipe: CraftProgramPipe<Yielded, Return>;
+};
+/**
+ * The generator returned when a {@link craftGen} factory is invoked. Composable
+ * with `yield*`: it relays the inner generator's dependency yields, advertises
+ * the union of exceptions it may produce through a {@link CraftGenExceptionMarker},
+ * and resolves to the success value (the output with exceptions stripped).
+ * Program operators (`catchTag`, `retry`, …) compose through `.pipe(...)`.
+ */
+export type CraftGenInvocation<Yielded, Output> = CraftPipeableProgram<Yielded | CraftGenExceptionMarker<ExtractCraftException<Output>>, StripCraftException<Output>>;
+export type CraftGenInvoker<Args extends any[], GenFn> = (...args: Args) => CraftGenInvocation<GeneratorFactoryYielded<GenFn>, GeneratorFactoryOutput<GenFn>>;
+/**
+ * Thrown to short-circuit the enclosing generator when a {@link craftGen}
+ * invocation produces a `craftException`. The route chain driver catches it at
+ * the guard/resolve boundary; composing generators simply let it propagate.
+ */
+export declare class CraftGenShortCircuit extends Error {
+    readonly [CRAFT_GEN_SHORT_CIRCUIT]: true;
+    readonly exception: AnyCraftException;
+    constructor(exception: AnyCraftException);
+}
+export declare function isCraftGenShortCircuit(value: unknown): value is CraftGenShortCircuit;
+type AnyProgramGen = Generator<unknown, unknown, unknown>;
+type ProgramFactory = () => AnyProgramGen;
+type AnyProgramOperator = (program: AnyProgramGen) => AnyProgramGen;
+type RuntimeCraftProgram = AnyProgramGen & {
+    [CRAFT_PROGRAM_RECREATE]: ProgramFactory;
+    pipe: (...operators: AnyProgramOperator[]) => RuntimeCraftProgram;
+};
+/**
+ * Returns the factory able to re-invoke `program` from scratch (a fresh
+ * iterator over the same logic and arguments), or `undefined` for a bare
+ * generator that was not built by {@link craftGen}/`.pipe`. Used by `retry` to
+ * replay the whole upstream chain.
+ */
+export declare function ɵgetCraftProgramRecreate(program: AnyProgramGen): ProgramFactory | undefined;
+/**
+ * Wraps a generator factory into a craft *program*: the generator (inert until
+ * `next()`) augmented with `.pipe(...)` and an internal re-invocation marker.
+ *
+ * `.pipe` folds operators left-to-right; each stage is itself a program whose
+ * re-invocation replays the entire upstream chain (`op(recreate-of-previous)`),
+ * so `retry` placed anywhere in the chain can restart from the source without
+ * the other operators having to know about re-invocation.
+ */
+export declare function ɵcreateCraftProgram(makeIterator: ProgramFactory): RuntimeCraftProgram;
+/**
+ * Builds a reusable, parameterised generator factory.
+ *
+ * `craftGen(generatorFn)` returns a factory `(...args) => CraftGenInvocation`
+ * that is composable with `yield*`. The inner generator's dependency yields
+ * (`CraftAuth`, `CraftRouter`, …) flow up to the enclosing driver
+ * unchanged, while the union of `craftException` it may return is tracked on the
+ * invocation's `Yielded` (type-level only).
+ *
+ * When the inner generator returns a `craftException`, the invocation **throws**
+ * {@link CraftGenShortCircuit}, interrupting the enclosing generator at any depth
+ * and propagating the exception to the nearest boundary (typically a route's
+ * `canActivate`/`canMatch` guard). When it returns a non-exception value, that
+ * value is returned from the `yield*`.
+ *
+ * @example
+ * ```ts
+ * export const roleGuard = craftGen(function* (...roles: Role[]) {
+ *   const { user } = yield* CraftAuth(undefined, ({ user }) => ({ user }));
+ *   if (!user()) return craftException({ code: 'NOT_AUTHENTICATED' });
+ *   return roles.includes(user()!.role)
+ *     ? true
+ *     : craftException({ code: 'FORBIDDEN_ROLE' });
+ * });
+ * ```
+ */
+export declare function craftGen<GenFn extends AnyGeneratorFactory>(generatorFn: GenFn): CraftGenInvoker<GeneratorFactoryArgs<GenFn>, GenFn>;
+export {};
+//# sourceMappingURL=craft-gen.d.ts.map

package/src/lib/craft-gen.d.ts.map

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

package/src/lib/craft-gen.js

@@ -0,0 +1,90 @@
+import { isCraftException, } from './craft-exception';
+import { isGenerator } from './craft-generator-runtime';
+const CRAFT_GEN_EXCEPTION_MARKER = Symbol('craft-gen-exception-marker');
+const CRAFT_GEN_SHORT_CIRCUIT = Symbol('craft-gen-short-circuit');
+const CRAFT_PROGRAM_RECREATE = Symbol('craft-program-recreate');
+/**
+ * Thrown to short-circuit the enclosing generator when a {@link craftGen}
+ * invocation produces a `craftException`. The route chain driver catches it at
+ * the guard/resolve boundary; composing generators simply let it propagate.
+ */
+export class CraftGenShortCircuit extends Error {
+    [CRAFT_GEN_SHORT_CIRCUIT] = true;
+    exception;
+    constructor(exception) {
+        super(`craftGen short-circuited with exception "${exception._tag}".`);
+        this.name = 'CraftGenShortCircuit';
+        this.exception = exception;
+    }
+}
+export function isCraftGenShortCircuit(value) {
+    return (!!value && typeof value === 'object' && CRAFT_GEN_SHORT_CIRCUIT in value);
+}
+/**
+ * Returns the factory able to re-invoke `program` from scratch (a fresh
+ * iterator over the same logic and arguments), or `undefined` for a bare
+ * generator that was not built by {@link craftGen}/`.pipe`. Used by `retry` to
+ * replay the whole upstream chain.
+ */
+export function ɵgetCraftProgramRecreate(program) {
+    return program[CRAFT_PROGRAM_RECREATE];
+}
+/**
+ * Wraps a generator factory into a craft *program*: the generator (inert until
+ * `next()`) augmented with `.pipe(...)` and an internal re-invocation marker.
+ *
+ * `.pipe` folds operators left-to-right; each stage is itself a program whose
+ * re-invocation replays the entire upstream chain (`op(recreate-of-previous)`),
+ * so `retry` placed anywhere in the chain can restart from the source without
+ * the other operators having to know about re-invocation.
+ */
+export function ɵcreateCraftProgram(makeIterator) {
+    const program = Object.assign(makeIterator(), {
+        [CRAFT_PROGRAM_RECREATE]: makeIterator,
+        pipe(...operators) {
+            return operators.reduce((previous, operator) => {
+                const recreatePrevious = previous[CRAFT_PROGRAM_RECREATE];
+                return ɵcreateCraftProgram(() => operator(ɵcreateCraftProgram(recreatePrevious)));
+            }, program);
+        },
+    });
+    return program;
+}
+/**
+ * Builds a reusable, parameterised generator factory.
+ *
+ * `craftGen(generatorFn)` returns a factory `(...args) => CraftGenInvocation`
+ * that is composable with `yield*`. The inner generator's dependency yields
+ * (`CraftAuth`, `CraftRouter`, …) flow up to the enclosing driver
+ * unchanged, while the union of `craftException` it may return is tracked on the
+ * invocation's `Yielded` (type-level only).
+ *
+ * When the inner generator returns a `craftException`, the invocation **throws**
+ * {@link CraftGenShortCircuit}, interrupting the enclosing generator at any depth
+ * and propagating the exception to the nearest boundary (typically a route's
+ * `canActivate`/`canMatch` guard). When it returns a non-exception value, that
+ * value is returned from the `yield*`.
+ *
+ * @example
+ * ```ts
+ * export const roleGuard = craftGen(function* (...roles: Role[]) {
+ *   const { user } = yield* CraftAuth(undefined, ({ user }) => ({ user }));
+ *   if (!user()) return craftException({ code: 'NOT_AUTHENTICATED' });
+ *   return roles.includes(user()!.role)
+ *     ? true
+ *     : craftException({ code: 'FORBIDDEN_ROLE' });
+ * });
+ * ```
+ */
+export function craftGen(generatorFn) {
+    const invoker = (...args) => ɵcreateCraftProgram(function* () {
+        const result = generatorFn(...args);
+        const output = isGenerator(result) ? yield* result : result;
+        if (isCraftException(output)) {
+            throw new CraftGenShortCircuit(output);
+        }
+        return output;
+    });
+    return invoker;
+}
+//# sourceMappingURL=craft-gen.js.map