@atolljs/angular 0.1.12 → 0.1.14

package/dist/atollModule.d.ts

@@ -0,0 +1,100 @@
+import { type ModuleWithProviders, type Type } from '@angular/core';
+import { type AtollFeature, type AtollPoolDeclaration, type AtollPoolSpec, type AtollProvideOptions } from './provideAtoll.js';
+/**
+ * A pool whose declaration resolves from injected deps during app init — the
+ * async form of AtollPoolDeclaration. The name stays static so the
+ * `ATOLL_POOL:<name>` injection token can be declared up front.
+ */
+export interface AtollPoolAsyncDecl {
+    /** Registry name — declares the ATOLL_POOL:<name> token before the factory resolves. */
+    name?: string;
+    /** Provider tokens passed to useFactory, in order. */
+    inject?: unknown[];
+    /**
+     * Receives the injected deps; returns a AtollPoolDeclaration or a Promise
+     * of one. A `name` on the result is ignored — the static `name` field owns
+     * the registry slot.
+     */
+    useFactory: (...args: any[]) => AtollPoolDeclaration | Promise<AtollPoolDeclaration>;
+}
+/** AtollModule.forRootAsync options. */
+export interface AtollModuleAsyncOptions {
+    pools?: AtollPoolAsyncDecl[];
+}
+/** AtollModule.registerPoolAsync options — BullModule.registerQueueAsync analog. */
+export interface AtollPoolAsyncOptions {
+    /** Registry name — static so `ATOLL_POOL:<name>` stays injectable while the factory resolves. */
+    name?: string;
+    /**
+     * Kept for Nest-parity/documentation: Angular's ModuleWithProviders has no
+     * `imports` slot, so this only documents where `inject` deps come from —
+     * they resolve through whichever injector imports the module (NgModule
+     * providers flatten into the importing injector). List dep-providing
+     * modules on the consuming @NgModule's `imports`.
+     */
+    imports?: Array<Type<unknown> | ModuleWithProviders<unknown> | unknown[]>;
+    /** Provider tokens passed to useFactory, in order. */
+    inject?: unknown[];
+    /** Receives the injected deps; returns a AtollPoolSpec (no `name` — the static field owns it) or a Promise of one. */
+    useFactory: (...args: any[]) => AtollPoolSpec | Promise<AtollPoolSpec>;
+}
+/**
+ * NgModule form of provideAtoll — the NestJS binding's vocabulary
+ * (forRoot / forRootAsync / registerPool / registerPoolAsync) for apps still
+ * on NgModule bootstrap:
+ *
+ *   @NgModule({
+ *     imports: [
+ *       AtollModule.forRoot(),                  // or forRoot({ pools: [...] })
+ *       IncidentsModule,                       // imports AtollModule.registerPool({ name: 'incidents', client: incidents })
+ *     ],
+ *   })
+ *   export class AppModule {}
+ *
+ * The standalone provider API — `provideAtoll` + `injectAtollPool` — remains
+ * the primary interface (bootstrapApplication providers, route-level pools);
+ * AtollModule exists for codebases that organize DI around NgModules. Both
+ * paths register the same `ATOLL_POOL:<name>` tokens, spawn eagerly, and
+ * terminate pools when the owning injector is destroyed.
+ */
+export declare class AtollModule {
+    /**
+     * Root registration — equivalent providers to `provideAtoll(options,
+     * ...features)`, imported once by the root module.
+     */
+    static forRoot(options?: AtollProvideOptions, ...features: AtollFeature[]): ModuleWithProviders<AtollModule>;
+    /**
+     * Async root registration — each pool's declaration resolves through an
+     * APP_INITIALIZER before bootstrap completes. The `name` field is static
+     * so the `ATOLL_POOL:<name>` token stays injectable.
+     */
+    static forRootAsync(options: AtollModuleAsyncOptions): ModuleWithProviders<AtollModule>;
+    /**
+     * Registers one pool inside whichever module imports it — the
+     * `provideAtoll({ pools: [decl] })` equivalent scoped to the importing
+     * NgModule: pool config lives in the feature module that owns the worker.
+     */
+    static registerPool(decl: AtollPoolDeclaration): ModuleWithProviders<AtollModule>;
+    /**
+     * Async pool registration — the name is static so `ATOLL_POOL:<name>` stays
+     * injectable, while the rest of the spec resolves from injected deps:
+     *
+     *   AtollModule.registerPoolAsync({
+     *     name: 'incidents',
+     *     useFactory: (config: PoolConfig) => Promise.resolve({
+     *       worker: () => new Worker(new URL('./incidents.worker.ts', import.meta.url)),
+     *       sharedMemory: incidentsMemory,
+     *       poolSize: config.poolSize,
+     *     }),
+     *     inject: [PoolConfig],
+     *   })
+     */
+    static registerPoolAsync(options: AtollPoolAsyncOptions): ModuleWithProviders<AtollModule>;
+}
+/**
+ * Constructor-parameter form of injectAtollPool — injects the pool registered
+ * under `name` into an @Injectable() (or component/directive) constructor:
+ *
+ *   constructor(@InjectAtollPool('incidents') private readonly pool: IncidentsClient) {}
+ */
+export declare const InjectAtollPool: (name?: string) => ParameterDecorator;

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { type Signal } from '@angular/core';
+import type { AsyncTask, ObservableValue, PathConnector, SharedMemory, SharedSpec, SpecPath, SliceOptions, TaskSnapshot } from '@atolljs/core';
+/**
+ * Wrap any sdk ObservableValue in a Signal. Call in an injection context
+ * (component field initializer or constructor) so the subscription is
+ * released on destroy; without one the subscription lives forever.
+ */
+export declare function observableSignal<T>(source: ObservableValue<T>): Signal<T>;
+/**
+ * Bind one shared-memory field to a Signal. Stays `undefined` until the
+ * contract is bound and the field written; updates on every write.
+ */
+export declare function sharedValue<S extends SharedSpec, K extends SpecPath<S>>(memory: SharedMemory<S>, key: K): Signal<(PathConnector<S, K> extends {
+    read(): infer T;
+} ? T : never) | undefined>;
+export declare function sharedValue<S extends SharedSpec, K extends SpecPath<S>, Sel>(memory: SharedMemory<S>, key: K, select: (value: PathConnector<S, K> extends {
+    read(): infer T;
+} ? T : never) => Sel, options?: SliceOptions<Sel>): Signal<Sel | undefined>;
+/** Bind an AsyncTask or plain async fn (via toTask): `{ state }` is a Signal of its snapshot; `run`/`runOnce` trigger it. */
+export declare function taskState<R>(source: AsyncTask<void, R> | (() => Promise<R>)): {
+    state: Signal<TaskSnapshot<R>>;
+    run: AsyncTask<void, R>['run'];
+    runOnce: AsyncTask<void, R>['runOnce'];
+};
+export declare function taskState<A, R>(source: AsyncTask<A, R> | ((input: A) => Promise<R>)): {
+    state: Signal<TaskSnapshot<R>>;
+    run: AsyncTask<A, R>['run'];
+    runOnce: AsyncTask<A, R>['runOnce'];
+};
+export { provideAtoll, injectAtollPool, getAtollPoolToken } from './provideAtoll.js';
+export type { AtollPoolDeclaration, AtollPoolSpec, AtollProvideOptions, AtollFeature } from './provideAtoll.js';
+export { AtollModule, InjectAtollPool } from './atollModule.js';
+export type { AtollModuleAsyncOptions, AtollPoolAsyncOptions, AtollPoolAsyncDecl } from './atollModule.js';

package/dist/index.js

@@ -0,0 +1,193 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/index.ts
+import { DestroyRef as DestroyRef3, inject as inject2, signal } from "@angular/core";
+import { observe, toTask } from "@atolljs/core";
+
+// src/provideAtoll.ts
+import {
+  DestroyRef,
+  ENVIRONMENT_INITIALIZER,
+  inject,
+  InjectionToken,
+  makeEnvironmentProviders
+} from "@angular/core";
+import {
+  WorkerPool
+} from "@atolljs/core";
+var poolTokens = /* @__PURE__ */ new Map();
+function getAtollPoolToken(name = "default") {
+  let token = poolTokens.get(name);
+  if (!token) poolTokens.set(name, token = new InjectionToken(`ATOLL_POOL:${name}`));
+  return token;
+}
+function injectAtollPool(name = "default") {
+  return inject(getAtollPoolToken(name));
+}
+var defaultName = (cfg, i) => cfg.name ?? (i === 0 ? "default" : `pool${i}`);
+function buildAtollPool(cfg) {
+  if ("client" in cfg) return cfg.client;
+  if ("pool" in cfg) return cfg.pool();
+  const { name: _name, worker, sharedMemory, ...rest } = cfg;
+  return new WorkerPool({
+    ...rest,
+    ...sharedMemory ? { sharedMemory } : {},
+    createWorker: worker
+  });
+}
+function atollProviders(pools, features = []) {
+  const named = pools.map((cfg, i) => ({ ...cfg, name: defaultName(cfg, i) }));
+  return [
+    ...named.map(
+      (cfg) => ({
+        provide: getAtollPoolToken(cfg.name),
+        useFactory: () => buildAtollPool(cfg)
+      })
+    ),
+    {
+      provide: ENVIRONMENT_INITIALIZER,
+      multi: true,
+      useValue: () => {
+        const destroyRef = inject(DestroyRef);
+        for (const cfg of named) {
+          const pool = inject(getAtollPoolToken(cfg.name));
+          destroyRef.onDestroy(() => pool.terminate());
+        }
+      }
+    },
+    ...features.flatMap((f) => f.providers)
+  ];
+}
+function provideAtoll(options, ...features) {
+  return makeEnvironmentProviders(atollProviders(options.pools ?? [], features));
+}
+
+// src/atollModule.ts
+import {
+  APP_INITIALIZER,
+  DestroyRef as DestroyRef2,
+  Inject,
+  InjectionToken as InjectionToken2,
+  Injector,
+  NgModule
+} from "@angular/core";
+function asyncPoolProviders(name, options) {
+  const declHolder = new InjectionToken2(`ATOLL_POOL_DECL:${name}`);
+  return [
+    { provide: declHolder, useValue: {} },
+    {
+      provide: getAtollPoolToken(name),
+      useFactory: (holder) => {
+        if (!holder.decl) {
+          throw new Error(
+            `Atoll pool "${name}" injected before its async declaration resolved \u2014 bootstrap blocks on APP_INITIALIZER; under TestBed await ApplicationInitStatus.donePromise first.`
+          );
+        }
+        return buildAtollPool({ ...holder.decl, name });
+      },
+      deps: [declHolder]
+    },
+    {
+      provide: APP_INITIALIZER,
+      multi: true,
+      useFactory: (holder, injector, ...deps) => {
+        const destroyRef = injector.get(DestroyRef2);
+        return async () => {
+          const resolved = await options.useFactory(...deps);
+          holder.decl = { ...resolved, name };
+          const pool = injector.get(getAtollPoolToken(name));
+          destroyRef.onDestroy(() => pool.terminate());
+        };
+      },
+      deps: [declHolder, Injector, ...options.inject ?? []]
+    }
+  ];
+}
+var AtollModule = class {
+  /**
+   * Root registration — equivalent providers to `provideAtoll(options,
+   * ...features)`, imported once by the root module.
+   */
+  static forRoot(options, ...features) {
+    return { ngModule: AtollModule, providers: atollProviders(options?.pools ?? [], features) };
+  }
+  /**
+   * Async root registration — each pool's declaration resolves through an
+   * APP_INITIALIZER before bootstrap completes. The `name` field is static
+   * so the `ATOLL_POOL:<name>` token stays injectable.
+   */
+  static forRootAsync(options) {
+    const providers = (options.pools ?? []).flatMap(
+      (decl, i) => asyncPoolProviders(decl.name ?? (i === 0 ? "default" : `pool${i}`), decl)
+    );
+    return { ngModule: AtollModule, providers };
+  }
+  /**
+   * Registers one pool inside whichever module imports it — the
+   * `provideAtoll({ pools: [decl] })` equivalent scoped to the importing
+   * NgModule: pool config lives in the feature module that owns the worker.
+   */
+  static registerPool(decl) {
+    return { ngModule: AtollModule, providers: atollProviders([decl]) };
+  }
+  /**
+   * Async pool registration — the name is static so `ATOLL_POOL:<name>` stays
+   * injectable, while the rest of the spec resolves from injected deps:
+   *
+   *   AtollModule.registerPoolAsync({
+   *     name: 'incidents',
+   *     useFactory: (config: PoolConfig) => Promise.resolve({
+   *       worker: () => new Worker(new URL('./incidents.worker.ts', import.meta.url)),
+   *       sharedMemory: incidentsMemory,
+   *       poolSize: config.poolSize,
+   *     }),
+   *     inject: [PoolConfig],
+   *   })
+   */
+  static registerPoolAsync(options) {
+    return {
+      ngModule: AtollModule,
+      providers: asyncPoolProviders(options.name ?? "default", options)
+    };
+  }
+};
+AtollModule = __decorateClass([
+  NgModule()
+], AtollModule);
+var InjectAtollPool = (name = "default") => Inject(getAtollPoolToken(name));
+
+// src/index.ts
+function unhook(stop) {
+  inject2(DestroyRef3, { optional: true })?.onDestroy(stop);
+}
+function observableSignal(source) {
+  const value = signal(source.get());
+  unhook(source.subscribe((v) => value.set(v)));
+  return value.asReadonly();
+}
+function sharedValue(memory, key, select, options) {
+  return observableSignal(observe(memory, key, select, options));
+}
+function taskState(source) {
+  const task = toTask(source);
+  return { state: observableSignal(task), run: task.run, runOnce: task.runOnce };
+}
+export {
+  AtollModule,
+  InjectAtollPool,
+  getAtollPoolToken,
+  injectAtollPool,
+  observableSignal,
+  provideAtoll,
+  sharedValue,
+  taskState
+};

package/dist/provideAtoll.d.ts

@@ -0,0 +1,117 @@
+import { InjectionToken, type EnvironmentProviders, type Provider } from '@angular/core';
+import { WorkerPool, type SharedMemory, type SharedSpec, type TaskMap, type WorkerPoolConfig, type WorkerRunner } from '@atolljs/core';
+/**
+ * The lifecycle surface every connectWorker client exposes. Declared
+ * structurally rather than as `WorkerClient<any, any>` — instantiating
+ * WorkerClient's generics with `any` collapses its method map to an index
+ * signature no concrete client satisfies.
+ */
+type AnyWorkerClient = {
+    start(): void;
+    terminate(): void;
+    readonly pool: WorkerRunner<any> | null;
+    readonly sharedMemory: unknown;
+};
+/**
+ * One pool's shape minus its registry name — also the return type of the
+ * async pool factories AtollModule.forRootAsync/registerPoolAsync accept.
+ * Three forms:
+ *
+ *   // inline: the worker factory keeps the bundler-detectable literal so the
+ *   // TS source is the reference
+ *   { worker: () => new Worker(new URL('./x.worker.ts', import.meta.url)), sharedMemory, tasks }
+ *
+ *   // existing: a domain package's already-configured pool factory — the
+ *   // same instance task helpers resolve, registered for DI + lifecycle
+ *   { pool: getIncidentsPool }
+ *
+ *   // typed client: a domain package's connectWorker client — registered
+ *   // for DI + lifecycle (terminate() on destroy; it re-spawns lazily)
+ *   { client: incidents }
+ */
+export type AtollPoolSpec<S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap> = (Omit<WorkerPoolConfig<S, T>, 'workerUrl' | 'createWorker' | 'sharedMemory'> & {
+    /** Spawns one pool worker — usually `() => new Worker(new URL('./x.worker.ts', import.meta.url))`. */
+    worker: () => Worker;
+    /**
+     * The contract this pool shares with its workers. Typed as SharedMemory<S>
+     * (not the config field's intersection) so declarations for heterogeneous
+     * specs coexist — access fields through the contract const, not the pool.
+     * Omit for message-only pools.
+     */
+    sharedMemory?: SharedMemory<S>;
+}) | {
+    /**
+     * An already-configured pool — e.g. a domain package's singleton the
+     * task helpers dispatch through. Registered for DI + lifecycle; the
+     * same instance is what injectAtollPool returns.
+     */
+    pool: () => WorkerPool<any, any>;
+} | {
+    /**
+     * An already-built connectWorker client — the provider value is the
+     * client itself, so injectAtollPool returns the typed call surface.
+     * Terminated on injector destroy; the lazy client re-spawns on the
+     * next call.
+     */
+    client: AnyWorkerClient;
+};
+/**
+ * One pool's declaration inside provideAtoll — a named AtollPoolSpec. The name
+ * selects the injection token (`ATOLL_POOL:<name>`); the first pool defaults
+ * to "default".
+ */
+export type AtollPoolDeclaration<S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap> = {
+    name?: string;
+} & AtollPoolSpec<S, T>;
+/** provideAtoll / AtollModule.forRoot options. */
+export interface AtollProvideOptions {
+    pools?: AtollPoolDeclaration[];
+}
+/**
+ * Composable feature for provideAtoll — the withX pattern. Reserved for
+ * cross-cutting additions (logging, timeouts); carries extra providers.
+ */
+export interface AtollFeature {
+    kind: string;
+    providers: Provider[];
+}
+/** InjectionToken for the pool registered under `name` — ATOLL_POOL:<name>. */
+export declare function getAtollPoolToken(name?: string): InjectionToken<WorkerPool>;
+/**
+ * Injects the WorkerPool registered under `name` by provideAtoll — call in an
+ * injection context (field initializer / constructor / factory). Pass the
+ * domain pool type to keep its task methods typed; override the provider in
+ * TestBed to stub the pool.
+ */
+export declare function injectAtollPool<T = WorkerPool>(name?: string): T;
+type NamedPoolDeclaration = AtollPoolDeclaration & {
+    name: string;
+};
+/** @internal Instantiate whatever a declaration describes — client / existing pool / inline config. */
+export declare function buildAtollPool(cfg: NamedPoolDeclaration): WorkerPool;
+/**
+ * @internal The provider list both provideAtoll and AtollModule's statics are
+ * built from — keeps the declaration-union handling in one place. Appends an
+ * ENVIRONMENT_INITIALIZER that eagerly spawns each pool and terminates it
+ * when the owning injector is destroyed (app teardown / HMR).
+ */
+export declare function atollProviders(pools: AtollPoolDeclaration[], features?: AtollFeature[]): Provider[];
+/**
+ * Registers atoll worker pools as Angular providers — the provideHttpClient
+ * analog:
+ *
+ *   bootstrapApplication(AppComponent, {
+ *     providers: [
+ *       provideAtoll({ pools: [{ name: 'incidents', client: incidents }] }),
+ *     ],
+ *   });
+ *
+ *   // anywhere DI runs:
+ *   private readonly incidents = injectAtollPool<IncidentsClient>('incidents');
+ *
+ * Pools spawn eagerly and terminate when the environment injector is
+ * destroyed (app teardown / HMR). Also usable at route level via
+ * `Route.providers` for lazily-scoped pools.
+ */
+export declare function provideAtoll(options: AtollProvideOptions, ...features: AtollFeature[]): EnvironmentProviders;
+export {};

package/package.json

@@ -1,21 +1,28 @@
 {
   "name": "@atolljs/angular",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Angular bindings — observableSignal, sharedValue, taskState",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "files": [
-    "src"
+    "src",
+    "dist"
   ],
+  "scripts": {
+    "build": "node ../../scripts/build-lib.mjs"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.12",
+    "@atolljs/core": "^0.1.14",
     "@angular/core": "^22.2.0"
   },
   "repository": {