@atolljs/angular 0.1.0

package/README.md

@@ -0,0 +1,11 @@
+# @atolljs/angular
+
+Angular bindings for `@atolljs/core` — framework adapter only, no domain code.
+Signal-based; call in an injection context (field initializer or constructor)
+so subscriptions are released on destroy.
+
+- `observableSignal(source)` — any `ObservableValue` as a `Signal`.
+- `sharedValue(memory, key)` — a shared-memory field as a `Signal`.
+- `taskState(task)` — `{ state }` Signal of the task snapshot plus `run`/`runOnce`.
+
+The consuming app composes these with its own contracts and tasks.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@atolljs/angular",
+  "version": "0.1.0",
+  "description": "Angular bindings — observableSignal, sharedValue, taskState",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@atolljs/core": "0.1.0",
+    "@angular/core": "^22.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jwhenry3/atolljs",
+    "directory": "packages/angular"
+  }
+}

package/src/atollModule.ts

@@ -0,0 +1,199 @@
+import {
+  APP_INITIALIZER,
+  DestroyRef,
+  Inject,
+  InjectionToken,
+  Injector,
+  NgModule,
+  type ModuleWithProviders,
+  type Provider,
+  type Type,
+} from '@angular/core';
+import {
+  buildAtollPool,
+  getAtollPoolToken,
+  atollProviders,
+  type AtollFeature,
+  type AtollPoolDeclaration,
+  type AtollPoolSpec,
+  type AtollProvideOptions,
+} from './provideAtoll';
+
+/**
+ * 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>;
+}
+
+/**
+ * Mutable slot an async initializer fills before bootstrap completes — the
+ * pool factory reads it lazily, after APP_INITIALIZER has resolved.
+ */
+interface AsyncDeclHolder {
+  decl?: AtollPoolDeclaration;
+}
+
+/**
+ * Two-stage async pool. Angular provider factories can't await, so an
+ * APP_INITIALIZER (multi:true) resolves useFactory into the holder during
+ * bootstrap — `inject` deps arrive through that record's factory signature.
+ * The initializer then forces the spawn itself and hooks terminate() on the
+ * injector's DestroyRef, because the sync path's ENVIRONMENT_INITIALIZER runs
+ * at injector creation — too early to await anything.
+ */
+function asyncPoolProviders(
+  name: string,
+  options: { inject?: unknown[]; useFactory: (...args: any[]) => unknown },
+): Provider[] {
+  const declHolder = new InjectionToken<AsyncDeclHolder>(`ATOLL_POOL_DECL:${name}`);
+  return [
+    { provide: declHolder, useValue: {} satisfies AsyncDeclHolder },
+    {
+      provide: getAtollPoolToken(name),
+      useFactory: (holder: AsyncDeclHolder) => {
+        if (!holder.decl) {
+          throw new Error(
+            `Atoll pool "${name}" injected before its async declaration resolved — ` +
+              '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: AsyncDeclHolder, injector: Injector, ...deps: unknown[]) => {
+        const destroyRef = injector.get(DestroyRef);
+        return async () => {
+          const resolved = (await options.useFactory(...deps)) as AtollPoolDeclaration;
+          holder.decl = { ...resolved, name };
+          const pool = injector.get(getAtollPoolToken(name)); // eager spawn once resolved
+          destroyRef.onDestroy(() => pool.terminate());
+        };
+      },
+      deps: [declHolder, Injector, ...(options.inject ?? [])],
+    },
+  ];
+}
+
+/**
+ * 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.
+ */
+@NgModule()
+export class AtollModule {
+  /**
+   * Root registration — equivalent providers to `provideAtoll(options,
+   * ...features)`, imported once by the root module.
+   */
+  static forRoot(
+    options?: AtollProvideOptions,
+    ...features: AtollFeature[]
+  ): ModuleWithProviders<AtollModule> {
+    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: AtollModuleAsyncOptions): ModuleWithProviders<AtollModule> {
+    const providers: Provider[] = (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: AtollPoolDeclaration): ModuleWithProviders<AtollModule> {
+    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: AtollPoolAsyncOptions): ModuleWithProviders<AtollModule> {
+    return {
+      ngModule: AtollModule,
+      providers: asyncPoolProviders(options.name ?? 'default', options),
+    };
+  }
+}
+
+/**
+ * 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 const InjectAtollPool = (name = 'default'): ParameterDecorator =>
+  Inject(getAtollPoolToken(name));

package/src/index.ts

@@ -0,0 +1,51 @@
+import { DestroyRef, inject, signal, type Signal } from '@angular/core';
+import { observe, toTask } from '@atolljs/core';
+import type { AsyncTask, ObservableValue, PathConnector, SharedMemory, SharedSpec, SpecPath, SliceOptions, TaskSnapshot } from '@atolljs/core';
+
+function unhook(stop: () => void) {
+  inject(DestroyRef, { optional: true })?.onDestroy(stop);
+}
+
+/**
+ * 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 function observableSignal<T>(source: ObservableValue<T>): Signal<T> {
+  const value = signal<T>(source.get());
+  unhook(source.subscribe((v) => value.set(v)));
+  return value.asReadonly();
+}
+
+/**
+ * Bind one shared-memory field to a Signal. Stays `undefined` until the
+ * contract is bound and the field written; updates on every write.
+ */
+export 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 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>;
+export function sharedValue<S extends SharedSpec, K extends SpecPath<S>, Sel>(
+  memory: SharedMemory<S>,
+  key: K,
+  select?: (value: never) => Sel,
+  options?: SliceOptions<Sel>
+) {
+  return observableSignal(observe(memory, key, select as never, options as never));
+}
+
+/** Bind an AsyncTask or plain async fn (via toTask): `{ state }` is a Signal of its snapshot; `run`/`runOnce` trigger it. */
+export function taskState<R>(source: AsyncTask<void, R> | (() => Promise<R>)): { state: Signal<TaskSnapshot<R>>; run: AsyncTask<void, R>['run']; runOnce: AsyncTask<void, R>['runOnce'] };
+export 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 function taskState<A, R>(source: AsyncTask<A, R> | ((input: A) => Promise<R>)) {
+  const task = toTask(source);
+  return { state: observableSignal(task), run: task.run, runOnce: task.runOnce };
+}
+
+export { provideAtoll, injectAtollPool, getAtollPoolToken } from './provideAtoll';
+export type { AtollPoolDeclaration, AtollPoolSpec, AtollProvideOptions, AtollFeature } from './provideAtoll';
+export { AtollModule, InjectAtollPool } from './atollModule';
+export type { AtollModuleAsyncOptions, AtollPoolAsyncOptions, AtollPoolAsyncDecl } from './atollModule';

package/src/provideAtoll.ts

@@ -0,0 +1,201 @@
+import {
+  DestroyRef,
+  ENVIRONMENT_INITIALIZER,
+  inject,
+  InjectionToken,
+  makeEnvironmentProviders,
+  type EnvironmentProviders,
+  type Provider,
+} from '@angular/core';
+import {
+  WorkerPool,
+  type SharedAccess,
+  type SharedMemory,
+  type SharedSpec,
+  type TaskMap,
+  type WorkerPoolConfig,
+} 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: WorkerPool<any, 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.
+       */
+      // WorkerPool<S,T> is invariant on S through SharedAccess, so the
+      // existing-pool form accepts any specialization.
+      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[];
+}
+
+const poolTokens = new Map<string, InjectionToken<WorkerPool>>();
+
+/** InjectionToken for the pool registered under `name` — ATOLL_POOL:<name>. */
+export function getAtollPoolToken(name = 'default'): InjectionToken<WorkerPool> {
+  let token = poolTokens.get(name);
+  if (!token) poolTokens.set(name, (token = new InjectionToken<WorkerPool>(`ATOLL_POOL:${name}`)));
+  return token;
+}
+
+/**
+ * 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 function injectAtollPool<T = WorkerPool>(name = 'default'): T {
+  return inject(getAtollPoolToken(name)) as unknown as T;
+}
+
+type NamedPoolDeclaration = AtollPoolDeclaration & { name: string };
+
+const defaultName = (cfg: AtollPoolDeclaration, i: number) =>
+  cfg.name ?? (i === 0 ? 'default' : `pool${i}`);
+
+/** @internal Instantiate whatever a declaration describes — client / existing pool / inline config. */
+export function buildAtollPool(cfg: NamedPoolDeclaration): WorkerPool {
+  if ('client' in cfg) return cfg.client as unknown as WorkerPool;
+  if ('pool' in cfg) return cfg.pool() as unknown as WorkerPool;
+  const { name: _name, worker, sharedMemory, ...rest } = cfg;
+  return new WorkerPool({
+    ...rest,
+    ...(sharedMemory
+      ? { sharedMemory: sharedMemory as SharedMemory<SharedSpec> & SharedAccess<SharedSpec> }
+      : {}),
+    createWorker: worker,
+  });
+}
+
+/**
+ * @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 function atollProviders(
+  pools: AtollPoolDeclaration[],
+  features: AtollFeature[] = [],
+): Provider[] {
+  const named = pools.map((cfg, i) => ({ ...cfg, name: defaultName(cfg, i) }));
+  return [
+    ...named.map(
+      (cfg): Provider => ({
+        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)); // force eager spawn
+          destroyRef.onDestroy(() => pool.terminate());
+        }
+      },
+    },
+    ...features.flatMap((f) => f.providers),
+  ];
+}
+
+/**
+ * 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 function provideAtoll(
+  options: AtollProvideOptions,
+  ...features: AtollFeature[]
+): EnvironmentProviders {
+  return makeEnvironmentProviders(atollProviders(options.pools ?? [], features));
+}