ngx-zero 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Anchev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# ngx-zero
+
+Signals-first, zoneless-ready Angular bindings for [Rocicorp Zero](https://zero.rocicorp.dev).
+
+## Quick look
+
+### Provide
+
+```ts
+// app.config.ts
+provideZero(() => ({
+  schema,
+  cacheURL: environment.zeroCache,
+  userID: auth.userId(),
+  auth: auth.jwt(),
+}))
+```
+
+### Query
+
+```ts
+// component — one inject per use-site, fully inferred
+export class IssuesList {
+  readonly issues = injectQuery(() => queries.issues.open({ assignee: this.userId() }));
+}
+```
+
+```html
+@for (issue of issues.data(); track issue.id) {
+  <app-issue [issue]="issue" />
+}
+```
+
+### Mutate
+
+```ts
+export class IssuesList {
+  readonly create = injectMutator(mutators.issue.create);
+  readonly close = injectMutator(mutators.issue.close);
+}
+```
+
+Fire-and-forget from the template, driving UI state off the signals:
+
+```html
+<button (click)="close.mutate({ id: issue.id })" [disabled]="close.pending()">
+  Close
+</button>
+
+@if (close.error(); as err) {
+  <p class="error">{{ err.message }}</p>
+}
+```
+
+Or await the outcome - the returned promises never reject:
+
+```ts
+async addIssue(title: string) {
+  const { client, server } = this.create.mutate({ id: crypto.randomUUID(), title });
+
+  await client;                  // optimistic apply settled
+  const result = await server;   // authoritative server outcome
+  if (result.type === 'error') {
+    // mutation was rejected and rolled back
+  }
+}
+```
+
+## Why
+
+- **Signals end-to-end.** Zoneless-first, zone.js fully supported (no `NgZone.run`
+  anywhere).
+- **Tight inference.** Zero generics at call sites via Zero's own `DefaultTypes`
+  registration.
+- **Modern Zero only.** Built on the ≥1.x API: query/mutator registries,
+  `zero.materialize`, `zero.connection`.
+
+## API
+
+### `provideZero(source, ...features)`
+
+Registers Zero at the environment level. `source` is `ZeroOptions`, an external
+`{ zero }` instance, or a thunk of either. When the thunk reads signals
+(`userID`, `auth`), ngx-zero reconciles on change — rotating auth reconnects in
+place, switching users recreates the instance.
+
+```ts
+provideZero(
+  () => ({ schema, cacheURL: env.zeroCache, userID: auth.userId(), auth: auth.jwt() }),
+  withBootstrap(zero => zero.preload(queries.issues.open())),
+)
+```
+
+### `injectQuery(queryThunk, options?)`
+
+Materializes a query and exposes it as signals. The thunk is reactive: reading a
+signal inside it re-runs the query when that signal changes. Returning a falsy
+value disables the query.
+
+```ts
+readonly issue = injectQuery(
+  () => this.issueId() && queries.issue.byId({ id: this.issueId()! }),
+  { ttl: '1m', keepPreviousData: true },
+);
+```
+
+Returns a `QueryRef`:
+
+| Member | Type | Meaning |
+| --- | --- | --- |
+| `data` | `Signal<TData>` | Rows (or row for `.one()` queries) |
+| `status` | `Signal<QueryStatus>` | `'unknown' \| 'complete' \| 'error' \| 'disabled'` |
+| `error` | `Signal<ErroredQuery \| undefined>` | Cleared on next successful emission |
+| `isComplete` | `Signal<boolean>` | Shorthand for `status() === 'complete'` |
+| `retry()` | method | Destroy and re-materialize |
+| `updateTTL(ttl)` | method | Forward a TTL to the current view |
+
+### `injectMutator(mutator, options?)`
+
+Binds a registry mutator to a `mutate()` function plus lifecycle signals.
+Returned promises never reject; errors land in the `error` signal.
+
+```ts
+readonly close = injectMutator(mutators.issue.close);
+
+close.clientPending() // optimistic apply in flight
+close.pending() // server confirmation in flight
+close.clientResult() / close.serverResult() // outcome details
+close.error() // client error, else server error (rollback)
+```
+
+### `injectConnectionState()`
+
+The current instance's connection state as a signal — seeded synchronously and
+following instance replacement. `'needs-auth'` is the cue to refresh auth: when
+the refreshed token lands in `provideZero`'s thunk, Zero reconnects in place.
+
+```ts
+readonly connection = injectConnectionState();
+
+constructor() {
+  effect(() => {
+    if (this.connection().name === 'needs-auth') {
+      void this.auth.refreshSession();
+    }
+  });
+}
+```
+
+```html
+@if (connection().name !== 'connected') {
+  <span class="badge">offline</span>
+}
+```
+
+### `injectZero()`
+
+Escape hatch: the raw `Zero` instance as a signal, for anything not covered
+above.
+
+### `provideZeroTesting(source, ...features)`
+
+Test-friendly `provideZero`: forces a local-only instance (`cacheURL: null`,
+`server: null`) with an in-memory store, for `TestBed` setups.
+
+## Development
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## Local playground
+
+[`examples/playground`](examples/playground) runs the library against a real
+backend: Postgres in Docker, `zero-cache`, and a Hono API embedded in the Vite
+dev server.
+
+```sh
+pnpm playground:db   # once: start Postgres, push the schema, seed
+pnpm playground      # build ngx-zero, then run zero-cache + vite
+```
+
+Open http://localhost:5173 — create/complete/delete issues, switch users to
+exercise instance rotation, rotate auth to exercise in-place reconnection, or
+add a title containing "rollback" to watch a server rejection roll back an
+optimistic mutation. Details in the
+[playground README](examples/playground/README.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function ngxZeroError(message: string): Error;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAEnD"}

package/dist/errors.js

@@ -0,0 +1,4 @@
+export function ngxZeroError(message) {
+    return new Error(`[ngx-zero] ${message}`);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,KAAK,CAAC,cAAc,OAAO,EAAE,CAAC,CAAC;AAC5C,CAAC"}

package/dist/features.d.ts

@@ -0,0 +1,9 @@
+import type { Provider } from '@angular/core';
+export type ZeroFeatureKind = 'bootstrap';
+export interface ZeroFeature<K extends ZeroFeatureKind = ZeroFeatureKind> {
+    readonly ɵkind: K;
+    readonly ɵproviders: readonly Provider[];
+}
+export declare function zeroFeature<K extends ZeroFeatureKind>(kind: K, providers: readonly Provider[]): ZeroFeature<K>;
+export declare function assertUniqueFeatureKinds(features: readonly ZeroFeature[]): void;
+//# sourceMappingURL=features.d.ts.map

package/dist/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC;AAE1C,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe;IACtE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,UAAU,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC1C;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,eAAe,EACnD,IAAI,EAAE,CAAC,EACP,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,WAAW,CAAC,CAAC,CAAC,CAEhB;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAQ/E"}

package/dist/features.js

@@ -0,0 +1,14 @@
+import { ngxZeroError } from './errors.js';
+export function zeroFeature(kind, providers) {
+    return { ɵkind: kind, ɵproviders: providers };
+}
+export function assertUniqueFeatureKinds(features) {
+    const kinds = new Set();
+    for (const f of features) {
+        if (kinds.has(f.ɵkind)) {
+            throw ngxZeroError(`provideZero(): duplicate feature "${f.ɵkind}".`);
+        }
+        kinds.add(f.ɵkind);
+    }
+}
+//# sourceMappingURL=features.js.map

package/dist/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.js","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAS3C,MAAM,UAAU,WAAW,CACzB,IAAO,EACP,SAA8B;IAE9B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,QAAgC;IACvE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,YAAY,CAAC,qCAAqC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;QACvE,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { provideZero } from './provide-zero.js';
+export { injectZero } from './inject-zero.js';
+export { injectQuery } from './inject-query.js';
+export { injectMutator } from './inject-mutator.js';
+export { injectConnectionState } from './inject-connection-state.js';
+export { provideZeroTesting, type ZeroTestingOptions } from './provide-zero-testing.js';
+export { withBootstrap } from './with-bootstrap.js';
+export type { ZeroFeature, ZeroFeatureKind } from './features.js';
+export type { InjectQueryOptions, QueryRef, QueryStatus } from './query-ref.js';
+export type { InjectMutatorOptions, MutatorError, MutatorRef } from './mutator-ref.js';
+export type { ConnectionState, Falsy } from '@rocicorp/zero';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACxF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChF,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACvF,YAAY,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { provideZero } from './provide-zero.js';
+export { injectZero } from './inject-zero.js';
+export { injectQuery } from './inject-query.js';
+export { injectMutator } from './inject-mutator.js';
+export { injectConnectionState } from './inject-connection-state.js';
+export { provideZeroTesting } from './provide-zero-testing.js';
+export { withBootstrap } from './with-bootstrap.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAA2B,MAAM,2BAA2B,CAAC;AACxF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/inject-connection-state.d.ts

@@ -0,0 +1,6 @@
+import { Injector, type Signal } from '@angular/core';
+import type { ConnectionState } from '@rocicorp/zero';
+export declare function injectConnectionState(options?: {
+    injector?: Injector;
+}): Signal<ConnectionState>;
+//# sourceMappingURL=inject-connection-state.d.ts.map

package/dist/inject-connection-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-connection-state.d.ts","sourceRoot":"","sources":["../src/inject-connection-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,QAAQ,EAGR,KAAK,MAAM,EACZ,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,eAAe,EAAQ,MAAM,gBAAgB,CAAC;AAI5D,wBAAgB,qBAAqB,CACnC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAO,GACpC,MAAM,CAAC,eAAe,CAAC,CAiDzB"}

package/dist/inject-connection-state.js

@@ -0,0 +1,41 @@
+import { assertInInjectionContext, DestroyRef, effect, inject, Injector, signal, untracked, } from '@angular/core';
+import { ngxZeroError } from './errors.js';
+import { ZERO_INSTANCE } from './instance-manager.js';
+export function injectConnectionState(options = {}) {
+    if (options.injector === undefined) {
+        assertInInjectionContext(injectConnectionState);
+    }
+    const injector = options.injector ?? inject(Injector);
+    const manager = injector.get(ZERO_INSTANCE, null, { optional: true });
+    if (!manager) {
+        throw ngxZeroError('injectConnectionState() could not find a Zero instance manager. ' +
+            'Add provideZero(...) to your ApplicationConfig providers.');
+    }
+    const initial = untracked(() => manager.zeroOrThrow());
+    const state = signal(initial.connection.state.current);
+    let subscribed;
+    let unsubscribe;
+    // Zero's subscribe() does not replay the current value, so every (re)attach
+    // seeds from `current` before listening.
+    const attach = (zero) => {
+        if (zero === subscribed) {
+            return;
+        }
+        unsubscribe?.();
+        subscribed = zero;
+        state.set(zero.connection.state.current);
+        unsubscribe = zero.connection.state.subscribe(next => state.set(next));
+    };
+    attach(initial);
+    effect(() => {
+        const zero = manager.zeroOrThrow();
+        untracked(() => attach(zero));
+    }, { injector });
+    injector.get(DestroyRef).onDestroy(() => {
+        unsubscribe?.();
+        unsubscribe = undefined;
+        subscribed = undefined;
+    });
+    return state.asReadonly();
+}
+//# sourceMappingURL=inject-connection-state.js.map

package/dist/inject-connection-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-connection-state.js","sourceRoot":"","sources":["../src/inject-connection-state.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,UAAU,EACV,MAAM,EACN,MAAM,EACN,QAAQ,EACR,MAAM,EACN,SAAS,GAEV,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,UAAU,qBAAqB,CACnC,UAAmC,EAAE;IAErC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,wBAAwB,CAAC,qBAAqB,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC;IAEtD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,YAAY,CAChB,kEAAkE;YAChE,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,MAAM,CAAkB,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAExE,IAAI,UAA4B,CAAC;IACjC,IAAI,WAAqC,CAAC;IAE1C,4EAA4E;IAC5E,yCAAyC;IACzC,MAAM,MAAM,GAAG,CAAC,IAAU,EAAQ,EAAE;QAClC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QACD,WAAW,EAAE,EAAE,CAAC;QAChB,UAAU,GAAG,IAAI,CAAC;QAClB,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACzC,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACzE,CAAC,CAAC;IAEF,MAAM,CAAC,OAAO,CAAC,CAAC;IAEhB,MAAM,CACJ,GAAG,EAAE;QACH,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QACnC,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAChC,CAAC,EACD,EAAE,QAAQ,EAAE,CACb,CAAC;IAEF,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;QACtC,WAAW,EAAE,EAAE,CAAC;QAChB,WAAW,GAAG,SAAS,CAAC;QACxB,UAAU,GAAG,SAAS,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC,UAAU,EAAE,CAAC;AAC5B,CAAC"}

package/dist/inject-mutator.d.ts

@@ -0,0 +1,4 @@
+import type { DefaultContext, DefaultSchema, DefaultWrappedTransaction, Mutator, ReadonlyJSONValue, Schema } from '@rocicorp/zero';
+import type { InjectMutatorOptions, MutatorRef } from './mutator-ref.js';
+export declare function injectMutator<TInput extends ReadonlyJSONValue | undefined, TSchema extends Schema = DefaultSchema, TContext = DefaultContext, TWrappedTransaction = DefaultWrappedTransaction>(mutator: Mutator<TInput, TSchema, TContext, TWrappedTransaction>, options?: InjectMutatorOptions): MutatorRef<TInput>;
+//# sourceMappingURL=inject-mutator.d.ts.map

package/dist/inject-mutator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-mutator.d.ts","sourceRoot":"","sources":["../src/inject-mutator.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,yBAAyB,EACzB,OAAO,EAGP,iBAAiB,EACjB,MAAM,EACP,MAAM,gBAAgB,CAAC;AAIxB,OAAO,KAAK,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEzE,wBAAgB,aAAa,CAC3B,MAAM,SAAS,iBAAiB,GAAG,SAAS,EAC5C,OAAO,SAAS,MAAM,GAAG,aAAa,EACtC,QAAQ,GAAG,cAAc,EACzB,mBAAmB,GAAG,yBAAyB,EAE/C,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,mBAAmB,CAAC,EAChE,OAAO,CAAC,EAAE,oBAAoB,GAC7B,UAAU,CAAC,MAAM,CAAC,CAAC"}

package/dist/inject-mutator.js

@@ -0,0 +1,63 @@
+import { assertInInjectionContext, DestroyRef, inject, Injector, untracked, } from '@angular/core';
+import { ngxZeroError } from './errors.js';
+import { ZERO_INSTANCE } from './instance-manager.js';
+import { MutatorCallTracker } from './mutator-call-tracker.js';
+// Upstream's AnyMutator alias is private — take the leaf as `unknown`,
+// cast once at the zero.mutate boundary.
+export function injectMutator(mutator, options = {}) {
+    if (options.injector === undefined) {
+        assertInInjectionContext(injectMutator);
+    }
+    const injector = options.injector ?? inject(Injector);
+    const manager = injector.get(ZERO_INSTANCE, null, { optional: true });
+    if (!manager) {
+        throw ngxZeroError('injectMutator() could not find a Zero instance manager. ' +
+            'Add provideZero(...) to your ApplicationConfig providers.');
+    }
+    const tracker = new MutatorCallTracker();
+    injector.get(DestroyRef).onDestroy(() => tracker.destroy());
+    const mutate = (args) => {
+        // untracked: a mutate() inside an effect must not subscribe it to
+        // instance changes.
+        const zero = untracked(() => manager.zeroOrThrow());
+        const buildRequest = mutator;
+        // begin() after zero.mutate: its sync throw (unregistered mutator) must
+        // not leave a fake pending call.
+        const raw = zero.mutate(buildRequest(args));
+        const callId = tracker.begin();
+        const client = settleSafe(raw.client);
+        const server = settleSafe(raw.server);
+        // Two-arg then: the rejection handler is defensive-only (settleSafe is
+        // total); a throwing settle must stay observable, not swallowed.
+        void client.then(details => tracker.settleClient(callId, details), noop);
+        void server.then(details => tracker.settleServer(callId, details), noop);
+        return { client, server };
+    };
+    return {
+        mutate,
+        clientPending: tracker.clientPending,
+        pending: tracker.pending,
+        clientResult: tracker.clientResult,
+        serverResult: tracker.serverResult,
+        error: tracker.error,
+    };
+}
+/** Never-reject boundary: rejections become Zero's own error details shape. */
+function settleSafe(promise) {
+    return promise.catch((reason) => ({
+        type: 'error',
+        error: { type: 'zero', message: describeReason(reason) },
+    }));
+}
+// Total for any unknown reason: a hostile coercion (throwing
+// Symbol.toPrimitive or message getter) must not re-reject the boundary.
+function describeReason(reason) {
+    try {
+        return reason instanceof Error ? reason.message : String(reason);
+    }
+    catch {
+        return 'Unknown mutation failure';
+    }
+}
+function noop() { }
+//# sourceMappingURL=inject-mutator.js.map

package/dist/inject-mutator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-mutator.js","sourceRoot":"","sources":["../src/inject-mutator.ts"],"names":[],"mappings":"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"}

package/dist/inject-query.d.ts

@@ -0,0 +1,7 @@
+import type { BaseDefaultContext, BaseDefaultSchema, DefaultContext, DefaultSchema, Falsy, HumanReadable, PullRow, QueryOrQueryRequest, ReadonlyJSONValue } from '@rocicorp/zero';
+import type { InjectQueryOptions, QueryRef, QueryStatus } from './query-ref.js';
+/** Always-enabled: tight data type, status can never be 'disabled'. */
+export declare function injectQuery<TTable extends keyof TSchema['tables'] & string, TInput extends ReadonlyJSONValue | undefined, TOutput extends ReadonlyJSONValue | undefined, TSchema extends BaseDefaultSchema = DefaultSchema, TReturn = PullRow<TTable, TSchema>, TContext extends BaseDefaultContext = DefaultContext>(queryThunk: () => QueryOrQueryRequest<TTable, TInput, TOutput, TSchema, TReturn, TContext>, options?: InjectQueryOptions): QueryRef<HumanReadable<TReturn>>;
+/** Disableable: data widens with `| undefined`, status with 'disabled'. */
+export declare function injectQuery<TTable extends keyof TSchema['tables'] & string, TInput extends ReadonlyJSONValue | undefined, TOutput extends ReadonlyJSONValue | undefined, TSchema extends BaseDefaultSchema = DefaultSchema, TReturn = PullRow<TTable, TSchema>, TContext extends BaseDefaultContext = DefaultContext>(queryThunk: () => QueryOrQueryRequest<TTable, TInput, TOutput, TSchema, TReturn, TContext> | Falsy, options?: InjectQueryOptions): QueryRef<HumanReadable<TReturn> | undefined, QueryStatus>;
+//# sourceMappingURL=inject-query.d.ts.map

package/dist/inject-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-query.d.ts","sourceRoot":"","sources":["../src/inject-query.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,KAAK,EACL,aAAa,EACb,OAAO,EACP,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAOxB,OAAO,KAAK,EACV,kBAAkB,EAClB,QAAQ,EACR,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAUxB,uEAAuE;AACvE,wBAAgB,WAAW,CACzB,MAAM,SAAS,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM,EAC/C,MAAM,SAAS,iBAAiB,GAAG,SAAS,EAC5C,OAAO,SAAS,iBAAiB,GAAG,SAAS,EAC7C,OAAO,SAAS,iBAAiB,GAAG,aAAa,EACjD,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,QAAQ,SAAS,kBAAkB,GAAG,cAAc,EAEpD,UAAU,EAAE,MAAM,mBAAmB,CACnC,MAAM,EACN,MAAM,EACN,OAAO,EACP,OAAO,EACP,OAAO,EACP,QAAQ,CACT,EACD,OAAO,CAAC,EAAE,kBAAkB,GAC3B,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAEpC,2EAA2E;AAC3E,wBAAgB,WAAW,CACzB,MAAM,SAAS,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM,EAC/C,MAAM,SAAS,iBAAiB,GAAG,SAAS,EAC5C,OAAO,SAAS,iBAAiB,GAAG,SAAS,EAC7C,OAAO,SAAS,iBAAiB,GAAG,aAAa,EACjD,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,QAAQ,SAAS,kBAAkB,GAAG,cAAc,EAEpD,UAAU,EAAE,MACR,mBAAmB,CACjB,MAAM,EACN,MAAM,EACN,OAAO,EACP,OAAO,EACP,OAAO,EACP,QAAQ,CACT,GACD,KAAK,EACT,OAAO,CAAC,EAAE,kBAAkB,GAC3B,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,EAAE,WAAW,CAAC,CAAC"}

package/dist/inject-query.js

@@ -0,0 +1,47 @@
+import { assertInInjectionContext, computed, DestroyRef, effect, inject, Injector, untracked, } from '@angular/core';
+import { ngxZeroError } from './errors.js';
+import { ZERO_INSTANCE } from './instance-manager.js';
+import { resolveQuery, } from './query-identity.js';
+import { DISABLED, QueryViewController, } from './query-view-controller.js';
+export function injectQuery(queryThunk, options = {}) {
+    if (options.injector === undefined) {
+        assertInInjectionContext(injectQuery);
+    }
+    const injector = options.injector ?? inject(Injector);
+    const manager = injector.get(ZERO_INSTANCE, null, { optional: true });
+    if (!manager) {
+        throw ngxZeroError('injectQuery() could not find a Zero instance manager. ' +
+            'Add provideZero(...) to your ApplicationConfig providers.');
+    }
+    // One computed for both change sources (instance + thunk signals);
+    // key-equal reruns keep the old reference via `equal`.
+    const spec = computed(() => {
+        const zero = manager.zeroOrThrow();
+        const result = queryThunk();
+        if (!result) {
+            return { zero, key: DISABLED, query: undefined };
+        }
+        return { zero, ...resolveQuery(zero, result) };
+    }, { equal: (a, b) => a.zero === b.zero && a.key === b.key });
+    const controller = new QueryViewController({
+        keepPreviousData: options.keepPreviousData ?? false,
+        ttl: options.ttl,
+    });
+    injector.get(DestroyRef).onDestroy(() => controller.destroy());
+    // Eager: the first change-detection pass renders real rows; the effect's
+    // first flush re-reads the same cached spec and is a no-op.
+    untracked(() => controller.reconcile(spec()));
+    effect(() => {
+        const current = spec();
+        untracked(() => controller.reconcile(current));
+    }, { injector });
+    return {
+        data: controller.data,
+        status: controller.status,
+        error: controller.error,
+        isComplete: computed(() => controller.status() === 'complete'),
+        retry: () => controller.retry(spec),
+        updateTTL: ttl => controller.updateTTL(ttl),
+    };
+}
+//# sourceMappingURL=inject-query.js.map

package/dist/inject-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-query.js","sourceRoot":"","sources":["../src/inject-query.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,QAAQ,EACR,UAAU,EACV,MAAM,EACN,MAAM,EACN,QAAQ,EACR,SAAS,GACV,MAAM,eAAe,CAAC;AAYvB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EACL,YAAY,GAEb,MAAM,qBAAqB,CAAC;AAM7B,OAAO,EACL,QAAQ,EACR,mBAAmB,GAEpB,MAAM,4BAA4B,CAAC;AA+CpC,MAAM,UAAU,WAAW,CACzB,UAA2C,EAC3C,UAA8B,EAAE;IAEhC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,wBAAwB,CAAC,WAAW,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC;IAEtD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,YAAY,CAChB,wDAAwD;YACtD,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,uDAAuD;IACvD,MAAM,IAAI,GAAG,QAAQ,CACnB,GAAG,EAAE;QACH,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QACnD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;IACjD,CAAC,EACD,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,EAAE,CAC1D,CAAC;IAEF,MAAM,UAAU,GAAG,IAAI,mBAAmB,CAAC;QACzC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,KAAK;QACnD,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;IAEH,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;IAE/D,yEAAyE;IACzE,4DAA4D;IAC5D,SAAS,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAE9C,MAAM,CACJ,GAAG,EAAE;QACH,MAAM,OAAO,GAAG,IAAI,EAAE,CAAC;QACvB,SAAS,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACjD,CAAC,EACD,EAAE,QAAQ,EAAE,CACb,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,UAAU,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,UAAU,CAAC;QAC9D,KAAK,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;QACnC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/dist/inject-zero.d.ts

@@ -0,0 +1,6 @@
+import { Injector, type Signal } from '@angular/core';
+import type { Zero } from '@rocicorp/zero';
+export declare function injectZero(options?: {
+    injector?: Injector;
+}): Signal<Zero>;
+//# sourceMappingURL=inject-zero.d.ts.map

package/dist/inject-zero.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-zero.d.ts","sourceRoot":"","sources":["../src/inject-zero.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAI3C,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAe1E"}

package/dist/inject-zero.js

@@ -0,0 +1,16 @@
+import { assertInInjectionContext, inject, Injector } from '@angular/core';
+import { ngxZeroError } from './errors.js';
+import { ZERO_INSTANCE } from './instance-manager.js';
+export function injectZero(options) {
+    if (options?.injector === undefined) {
+        assertInInjectionContext(injectZero);
+    }
+    const injector = options?.injector ?? inject(Injector);
+    const manager = injector.get(ZERO_INSTANCE, null, { optional: true });
+    if (!manager) {
+        throw ngxZeroError('injectZero() could not find a Zero instance manager. ' +
+            'Add provideZero(...) to your ApplicationConfig providers.');
+    }
+    return manager.zeroOrThrow;
+}
+//# sourceMappingURL=inject-zero.js.map

package/dist/inject-zero.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-zero.js","sourceRoot":"","sources":["../src/inject-zero.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,EAAE,QAAQ,EAAe,MAAM,eAAe,CAAC;AAExF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,UAAU,UAAU,CAAC,OAAiC;IAC1D,IAAI,OAAO,EAAE,QAAQ,KAAK,SAAS,EAAE,CAAC;QACpC,wBAAwB,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC;IAEvD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,YAAY,CAChB,uDAAuD;YACvD,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,CAAC;AAC7B,CAAC"}

package/dist/instance-manager.d.ts

@@ -0,0 +1,13 @@
+import { InjectionToken } from '@angular/core';
+import { Zero, type ZeroOptions } from '@rocicorp/zero';
+import type { ZeroInstanceHooks, ZeroInstanceOptions } from './types.js';
+export declare const ZERO_INSTANCE: InjectionToken<ZeroInstanceManager>;
+export declare const ZERO_CONSTRUCTOR: InjectionToken<(options: ZeroOptions) => Zero>;
+export declare const ZERO_INSTANCE_HOOKS: InjectionToken<readonly ZeroInstanceHooks[]>;
+export declare class ZeroInstanceManager {
+    #private;
+    readonly zeroOrThrow: import("@angular/core").Signal<Zero<import("@rocicorp/zero").Schema, undefined, unknown>>;
+    constructor(source: ZeroInstanceOptions);
+    start(): void;
+}
+//# sourceMappingURL=instance-manager.d.ts.map

package/dist/instance-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-manager.d.ts","sourceRoot":"","sources":["../src/instance-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,cAAc,EAIf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGxD,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,aAAa,qCAEzB,CAAC;AAEF,eAAO,MAAM,gBAAgB,2BAAgC,WAAW,KAAK,IAAI,CAGhF,CAAC;AAEF,eAAO,MAAM,mBAAmB,8CAE/B,CAAC;AAMF,qBAAa,mBAAmB;;IAc9B,QAAQ,CAAC,WAAW,4FAQjB;gBAUS,MAAM,EAAE,mBAAmB;IAMvC,KAAK,IAAI,IAAI;CAiJd"}