@haddowg/json-api-angular 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gregory Haddow
+
+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

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @haddowg/json-api-angular
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Part of the [jsonapi.rest](https://jsonapi.rest) suite** — a complete, spec-compliant
+> JSON:API 1.1 stack: a framework-agnostic PHP [core](https://github.com/haddowg/json-api), a
+> [Symfony bundle](https://github.com/haddowg/json-api-symfony), a
+> [Laravel package](https://github.com/haddowg/json-api-laravel), and this **typed TypeScript
+> client**, bound together by one conformance-tested OpenAPI 3.1 contract.
+> Full documentation: **[haddowg.github.io/json-api-ts](https://haddowg.github.io/json-api-ts/)**.
+
+Signal-based Angular bindings for a generated [`@haddowg/json-api-client`](../client). The client
+goes into dependency injection and sends through Angular's `HttpClient`, so your interceptors run
+on every request. Reads become signals through Angular's `resource()`, and writes get a small
+signal-based mutation handle.
+
+## Install
+
+```bash
+npm install @haddowg/json-api-angular @haddowg/json-api-client
+```
+
+`@angular/core` and `@angular/common` (20, 21 or 22) are peer dependencies.
+
+## Provide the client
+
+```ts
+import { provideHttpClient, withInterceptors } from '@angular/common/http'
+import { provideJsonApiClient } from '@haddowg/json-api-angular'
+import { createClient } from './api/music.gen'
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(withInterceptors([authInterceptor])),
+    provideJsonApiClient(createClient, { baseUrl: '/api/v5' }),
+  ],
+}
+```
+
+Register the client's type once so it is typed everywhere without a token:
+
+```ts
+import type { JsonApiClientOf } from '@haddowg/json-api-angular'
+
+declare module '@haddowg/json-api-angular' {
+  interface Register {
+    client: JsonApiClientOf<typeof createClient>
+  }
+}
+```
+
+For a second client (another server), create a token with `createJsonApiClientToken()` and pass it
+as the third argument to `provideJsonApiClient`, then to `injectJsonApiClient(token)` or a
+resource's `client` option.
+
+## Read with a resource
+
+```ts
+@Component({
+  template: `
+    @if (albums.hasValue()) {
+      @for (album of albums.value(); track album.id) {
+        <li>{{ album.title }} by {{ album.artist?.name }}</li>
+      }
+    }
+    @if (albums.jsonApiError(); as error) {
+      <p>{{ error.status }}</p>
+    }
+  `,
+})
+export class AlbumList {
+  readonly search = signal('')
+
+  readonly albums = jsonApiResource({
+    params: () => ({ filter: { title: this.search() } }),
+    loader: ({ client, params, abortSignal }) =>
+      client.albums.list({ ...params, include: ['artist'], signal: abortSignal }),
+  })
+}
+```
+
+Changing `search` starts a new read and cancels the one in flight. Return `undefined` from
+`params` to hold the read until its inputs are ready. As with any Angular resource, `value()`
+throws in the error state, so guard it with `hasValue()`.
+
+`nextPage(list)` and `prevPage(list)` return the `page` params from a collection's links, ready to
+set on the signal your params read. `loadAll(firstPage, { signal })` follows `next` links and
+returns every member in one array.
+
+## Write with a mutation
+
+```ts
+readonly rename = jsonApiMutation((client, title: string) =>
+  client.albums.id(this.id()).update({ title }),
+)
+
+save(title: string) {
+  this.rename.mutate(title).then(() => this.albums.reload(), () => {})
+}
+```
+
+`isPending()`, `error()`, `jsonApiError()`, `value()` and `reset()` track the latest call. Nothing
+is cached between resources, so reload the reads a write affects.
+
+See the [Angular guide](https://haddowg.github.io/json-api-ts/angular/) for the details.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,262 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _angular_core = require("@angular/core");
+let _haddowg_json_api_client = require("@haddowg/json-api-client");
+let _angular_common_http = require("@angular/common/http");
+//#region src/transport.ts
+/**
+* A transport that sends every request through Angular's `HttpClient`, so the app's interceptors
+* run. The body comes back as text for the client to parse, exactly as with `fetchTransport`.
+*
+* A non-2xx response resolves with its status, headers and body, because the client maps those to
+* a `JsonApiError` itself. Only a request that never got a response (status 0: network failure,
+* CORS, a blocked request) rejects, with the `HttpErrorResponse`. Aborting `req.signal`
+* unsubscribes, which cancels the HTTP request, and rejects with the signal's reason.
+*/
+function httpClientTransport(http) {
+	return (req) => new Promise((resolve, reject) => {
+		const signal = req.signal;
+		if (signal?.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		let unsubscribe;
+		const onAbort = () => {
+			unsubscribe?.();
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		const settle = () => signal?.removeEventListener("abort", onAbort);
+		const subscription = http.request(req.method, req.url, {
+			body: req.body ?? null,
+			headers: req.headers,
+			observe: "response",
+			responseType: "text"
+		}).subscribe({
+			next: (res) => {
+				settle();
+				resolve({
+					status: res.status,
+					headers: toRecord(res.headers),
+					body: res.body ?? ""
+				});
+			},
+			error: (error) => {
+				settle();
+				if (error instanceof _angular_common_http.HttpErrorResponse && error.status !== 0) {
+					resolve({
+						status: error.status,
+						headers: toRecord(error.headers),
+						body: errorBody(error.error)
+					});
+					return;
+				}
+				reject(error);
+			}
+		});
+		unsubscribe = () => subscription.unsubscribe();
+	});
+}
+function toRecord(headers) {
+	const out = {};
+	for (const name of headers.keys()) {
+		const values = headers.getAll(name);
+		if (values !== null) out[name.toLowerCase()] = values.join(", ");
+	}
+	return out;
+}
+function errorBody(body) {
+	if (typeof body === "string") return body;
+	if (body === null || body === void 0) return "";
+	return JSON.stringify(body);
+}
+//#endregion
+//#region src/provide.ts
+/** The token {@link provideJsonApiClient} uses when none is given. */
+const JSON_API_CLIENT = new _angular_core.InjectionToken("JSON_API_CLIENT");
+/**
+* Create an injection token for one client, so an app can provide several (one per server).
+* Type it with the client: `createJsonApiClientToken<JsonApiClientOf<typeof createAdminClient>>()`.
+*/
+function createJsonApiClientToken(description = "JsonApiClient") {
+	return new _angular_core.InjectionToken(description);
+}
+/**
+* Provide a generated client to the environment injector. The client sends through `HttpClient`
+* (so `provideHttpClient()` must also be present) unless `options.transport` overrides it.
+*
+* `options` may be a function, which runs in an injection context, to read values such as the
+* base URL from other providers. `token` defaults to {@link JSON_API_CLIENT}; pass one from
+* {@link createJsonApiClientToken} to provide a second client alongside it.
+*/
+function provideJsonApiClient(createClient, options, token = JSON_API_CLIENT) {
+	return (0, _angular_core.makeEnvironmentProviders)([{
+		provide: token,
+		useFactory: () => {
+			const resolved = typeof options === "function" ? options() : options;
+			return createClient({
+				...resolved,
+				transport: resolved.transport ?? httpClientTransport((0, _angular_core.inject)(_angular_common_http.HttpClient))
+			});
+		}
+	}]);
+}
+/**
+* Inject a provided client. Without a token this returns the default client, typed by
+* {@link Register}. With a token it returns that token's client.
+*/
+function injectJsonApiClient(token, options) {
+	const resolved = token ?? JSON_API_CLIENT;
+	if (options?.injector !== void 0) return options.injector.get(resolved);
+	(0, _angular_core.assertInInjectionContext)(injectJsonApiClient);
+	return (0, _angular_core.inject)(resolved);
+}
+//#endregion
+//#region src/mutation.ts
+/**
+* Wrap a client write (create, update, delete, a relationship mutation, a custom action or an
+* atomic batch) in signals. Nothing is cached or invalidated: `reload()` the resources the write
+* affects.
+*
+* ```ts
+* readonly rename = jsonApiMutation((client, title: string) =>
+*   client.albums.id(this.id()).update({ title }),
+* )
+* ```
+*/
+function jsonApiMutation(mutation, options = {}) {
+	if (options.injector === void 0) (0, _angular_core.assertInInjectionContext)(jsonApiMutation);
+	const client = (options.injector ?? (0, _angular_core.inject)(_angular_core.Injector)).get(options.client ?? JSON_API_CLIENT);
+	const value = (0, _angular_core.signal)(void 0);
+	const error = (0, _angular_core.signal)(void 0);
+	const pending = (0, _angular_core.signal)(0);
+	let generation = 0;
+	const mutate = async (input) => {
+		const current = ++generation;
+		pending.update((n) => n + 1);
+		error.set(void 0);
+		try {
+			const result = await mutation(client, input);
+			if (current === generation) value.set(result);
+			return result;
+		} catch (thrown) {
+			if (current === generation) error.set(thrown instanceof Error ? thrown : new Error(String(thrown), { cause: thrown }));
+			throw thrown;
+		} finally {
+			pending.update((n) => Math.max(0, n - 1));
+		}
+	};
+	return {
+		mutate,
+		isPending: (0, _angular_core.computed)(() => pending() > 0),
+		error: error.asReadonly(),
+		jsonApiError: (0, _angular_core.computed)(() => {
+			const e = error();
+			return e instanceof _haddowg_json_api_client.JsonApiError ? e : void 0;
+		}),
+		value: value.asReadonly(),
+		reset: () => {
+			generation++;
+			value.set(void 0);
+			error.set(void 0);
+			pending.set(0);
+		}
+	};
+}
+//#endregion
+//#region src/pagination.ts
+/**
+* The `page` params for the page after `list`, read from its `next` link, or `undefined` on the
+* last page (or before anything has loaded). Works the same for every strategy, because the
+* server's link already carries the right parameters. Feed the result back into the signal your
+* resource's params read:
+*
+* ```ts
+* const next = nextPage(this.albums.value())
+* if (next) this.page.set(next)
+* ```
+*/
+function nextPage(list) {
+	return pageParams(list?.$page, list?.$page.links.next);
+}
+/** The `page` params for the page before `list`, from its `prev` link. See {@link nextPage}. */
+function prevPage(list) {
+	return pageParams(list?.$page, list?.$page.links.prev);
+}
+const CURSOR_ROLES = ["after", "before"];
+function pageParams(page, link) {
+	if (page === void 0 || link === void 0) return;
+	const keys = Object.entries(page.keys);
+	const query = link.includes("?") ? link.slice(link.indexOf("?") + 1).split("#")[0] : "";
+	const params = {};
+	for (const [name, value] of new URLSearchParams(query)) {
+		const member = /^page\[([^\]]+)\]$/.exec(name)?.[1];
+		if (member === void 0) continue;
+		const role = keys.find(([, key]) => key === member)?.[0];
+		const count = Number(value);
+		params[member] = role !== void 0 && !CURSOR_ROLES.includes(role) && value !== "" && Number.isFinite(count) ? count : value;
+	}
+	return params;
+}
+/**
+* Follow `next` links from the first page until the last, and return every member in one plain
+* array. Use it inside a loader to read a whole (small) collection:
+*
+* ```ts
+* loader: ({ client, abortSignal }) =>
+*   loadAll(client.genres.list({ signal: abortSignal }), { signal: abortSignal })
+* ```
+*/
+async function loadAll(first, options = {}) {
+	const { signal, maxPages = Number.POSITIVE_INFINITY } = options;
+	let page = await first;
+	const all = [];
+	let count = 0;
+	while (page !== void 0 && count < maxPages) {
+		all.push(...page);
+		count++;
+		if (count >= maxPages) break;
+		signal?.throwIfAborted();
+		page = await page.$next(signal !== void 0 ? { signal } : void 0);
+	}
+	return all;
+}
+//#endregion
+//#region src/resource.ts
+function jsonApiResource(options) {
+	if (options.injector === void 0) (0, _angular_core.assertInInjectionContext)(jsonApiResource);
+	const injector = options.injector ?? (0, _angular_core.inject)(_angular_core.Injector);
+	const client = injector.get(options.client ?? JSON_API_CLIENT);
+	const ref = (0, _angular_core.resource)({
+		...options.params !== void 0 ? { params: options.params } : {},
+		loader: ({ params, abortSignal, previous }) => options.loader({
+			client,
+			params,
+			abortSignal,
+			previous
+		}),
+		...options.defaultValue !== void 0 ? { defaultValue: options.defaultValue } : {},
+		...options.equal !== void 0 ? { equal: options.equal } : {},
+		...options.debugName !== void 0 ? { debugName: options.debugName } : {},
+		injector
+	});
+	const jsonApiError = (0, _angular_core.computed)(() => {
+		const error = ref.error();
+		return error instanceof _haddowg_json_api_client.JsonApiError ? error : void 0;
+	});
+	Object.defineProperty(ref, "jsonApiError", {
+		value: jsonApiError,
+		enumerable: true
+	});
+	return ref;
+}
+//#endregion
+exports.JSON_API_CLIENT = JSON_API_CLIENT;
+exports.createJsonApiClientToken = createJsonApiClientToken;
+exports.httpClientTransport = httpClientTransport;
+exports.injectJsonApiClient = injectJsonApiClient;
+exports.jsonApiMutation = jsonApiMutation;
+exports.jsonApiResource = jsonApiResource;
+exports.loadAll = loadAll;
+exports.nextPage = nextPage;
+exports.prevPage = prevPage;
+exports.provideJsonApiClient = provideJsonApiClient;

package/dist/index.d.cts

@@ -0,0 +1,219 @@
+import { EnvironmentProviders, InjectionToken, Injector, ResourceRef, ResourceStatus, Signal, ValueEqualityFn } from "@angular/core";
+import { ClientOptions, Collection, ErrorCodeOf, JsonApiError, JsonApiTransport, Page, PageParamsOf, StructuralGuardError } from "@haddowg/json-api-client";
+import { HttpClient } from "@angular/common/http";
+
+//#region src/provide.d.ts
+/**
+ * Options for {@link provideJsonApiClient}: the client's options with the transport made
+ * optional. Leave `transport` out to send through `HttpClient`; set it only to opt out.
+ */
+type JsonApiClientOptions = Omit<ClientOptions, 'transport'> & {
+  transport?: JsonApiTransport;
+};
+/** A generated client factory: the bound `createClient` a codegen module exports. */
+type JsonApiClientFactory<C> = (options: ClientOptions) => C;
+/** The client type a generated `createClient` returns. */
+type JsonApiClientOf<F> = F extends ((options: ClientOptions) => infer C) ? C : never;
+/**
+ * Register the app's default client type once, so `injectJsonApiClient()` and `jsonApiResource()`
+ * are typed without a token:
+ *
+ * ```ts
+ * declare module '@haddowg/json-api-angular' {
+ *   interface Register {
+ *     client: JsonApiClientOf<typeof createClient>
+ *   }
+ * }
+ * ```
+ */
+interface Register {}
+/** The default client's type: whatever {@link Register} declares, else `unknown`. */
+type RegisteredClient = Register extends {
+  client: infer C;
+} ? C : unknown;
+/** The token {@link provideJsonApiClient} uses when none is given. */
+declare const JSON_API_CLIENT: InjectionToken<unknown>;
+/**
+ * Create an injection token for one client, so an app can provide several (one per server).
+ * Type it with the client: `createJsonApiClientToken<JsonApiClientOf<typeof createAdminClient>>()`.
+ */
+declare function createJsonApiClientToken<C>(description?: string): InjectionToken<C>;
+/**
+ * Provide a generated client to the environment injector. The client sends through `HttpClient`
+ * (so `provideHttpClient()` must also be present) unless `options.transport` overrides it.
+ *
+ * `options` may be a function, which runs in an injection context, to read values such as the
+ * base URL from other providers. `token` defaults to {@link JSON_API_CLIENT}; pass one from
+ * {@link createJsonApiClientToken} to provide a second client alongside it.
+ */
+declare function provideJsonApiClient<C>(createClient: JsonApiClientFactory<C>, options: JsonApiClientOptions | (() => JsonApiClientOptions), token?: InjectionToken<C>): EnvironmentProviders;
+/**
+ * Inject a provided client. Without a token this returns the default client, typed by
+ * {@link Register}. With a token it returns that token's client.
+ */
+declare function injectJsonApiClient<C = RegisteredClient>(token?: InjectionToken<C>, options?: {
+  injector?: Injector;
+}): C;
+//#endregion
+//#region src/resource.d.ts
+/**
+ * What a read can fail with: a `JsonApiError` for a non-2xx response, a `StructuralGuardError`
+ * for a response that isn't a JSON:API document, or any other error (a network failure, a
+ * validator's error). Narrow with `instanceof`. `E` types the `JsonApiError`'s codes.
+ */
+type JsonApiResourceError<E extends string = string> = JsonApiError<E> | StructuralGuardError | Error;
+/** What the loader receives each time the params change or the resource reloads. */
+interface JsonApiLoaderContext<C, P> {
+  client: C;
+  params: P;
+  /** Aborts when the params change again or the resource is destroyed. Pass it to the read. */
+  abortSignal: AbortSignal;
+  previous: {
+    status: ResourceStatus;
+  };
+}
+/** Options for {@link jsonApiResource}. */
+interface JsonApiResourceOptions<T, P, C> {
+  /**
+   * A reactive function computing the read's params from signals. Return `undefined` while the
+   * read isn't ready (no id yet, say) and the resource stays idle. Leave it out to load once.
+   */
+  params?: () => P | undefined;
+  /** Make the read. Return the client call's promise, passing `abortSignal` as its `signal`. */
+  loader: (context: JsonApiLoaderContext<C, P>) => PromiseLike<T>;
+  /** The client to read with. Defaults to the one `provideJsonApiClient` registered without a token. */
+  client?: InjectionToken<C>;
+  /** The value while nothing has loaded yet. */
+  defaultValue?: T;
+  equal?: ValueEqualityFn<T>;
+  /** Create the resource outside an injection context. */
+  injector?: Injector;
+  debugName?: string;
+}
+/**
+ * Angular's `ResourceRef` with `error()` typed to what a JSON:API read throws, plus
+ * `jsonApiError()`, the error when it is a `JsonApiError` (handy in templates, which can't
+ * use `instanceof`). `E` is the client's error-code union, so a generated client's
+ * `jsonApiError()` carries its server's `ErrorCode`.
+ */
+interface JsonApiResourceRef<T, E extends string = string> extends Omit<ResourceRef<T>, 'error' | 'hasValue'> {
+  readonly error: Signal<JsonApiResourceError<E> | undefined>;
+  readonly jsonApiError: Signal<JsonApiError<E> | undefined>;
+  /** Whether a value is loaded. Narrows `value()` to exclude `undefined`, in templates too. */
+  hasValue(this: T extends undefined ? this : never): this is JsonApiResourceRef<Exclude<T, undefined>, E>;
+  hasValue(): boolean;
+}
+/**
+ * A signal-based JSON:API read: a thin wrapper over Angular's `resource()` that injects the
+ * client and hands it to the loader. Changing a signal the params read starts a new load and
+ * aborts the one in flight.
+ *
+ * ```ts
+ * readonly albums = jsonApiResource({
+ *   params: () => ({ filter: { title: this.search() } }),
+ *   loader: ({ client, params, abortSignal }) =>
+ *     client.albums.list({ ...params, include: ['artist'], signal: abortSignal }),
+ * })
+ * ```
+ */
+declare function jsonApiResource<T, P = unknown, C = RegisteredClient>(options: JsonApiResourceOptions<T, P, C> & {
+  defaultValue: T;
+}): JsonApiResourceRef<T, ErrorCodeOf<C>>;
+declare function jsonApiResource<T, P = unknown, C = RegisteredClient>(options: JsonApiResourceOptions<T, P, C>): JsonApiResourceRef<T | undefined, ErrorCodeOf<C>>;
+//#endregion
+//#region src/mutation.d.ts
+/** Options for {@link jsonApiMutation}. */
+interface JsonApiMutationOptions<C> {
+  /** The client to write with. Defaults to the one `provideJsonApiClient` registered without a token. */
+  client?: InjectionToken<C>;
+  /** Create the mutation outside an injection context. */
+  injector?: Injector;
+}
+/**
+ * The signal-based handle {@link jsonApiMutation} returns. `E` is the client's error-code union,
+ * so a generated client's `jsonApiError()` carries its server's `ErrorCode`.
+ */
+interface JsonApiMutationRef<I, T, E extends string = string> {
+  /**
+   * Run the write. Resolves with its result and rejects with its error; the signals track the
+   * latest call either way.
+   */
+  mutate(input: I): Promise<T>;
+  readonly isPending: Signal<boolean>;
+  readonly error: Signal<JsonApiResourceError<E> | undefined>;
+  /** The error when it is a `JsonApiError`; use `byPath()` on it for form errors. */
+  readonly jsonApiError: Signal<JsonApiError<E> | undefined>;
+  /** The latest successful result. */
+  readonly value: Signal<T | undefined>;
+  /** Clear the value and error. A call still in flight no longer updates the signals. */
+  reset(): void;
+}
+/**
+ * Wrap a client write (create, update, delete, a relationship mutation, a custom action or an
+ * atomic batch) in signals. Nothing is cached or invalidated: `reload()` the resources the write
+ * affects.
+ *
+ * ```ts
+ * readonly rename = jsonApiMutation((client, title: string) =>
+ *   client.albums.id(this.id()).update({ title }),
+ * )
+ * ```
+ */
+declare function jsonApiMutation<I, T, C = RegisteredClient>(mutation: (client: C, input: I) => PromiseLike<T>, options?: JsonApiMutationOptions<C>): JsonApiMutationRef<I, T, ErrorCodeOf<C>>;
+//#endregion
+//#region src/pagination.d.ts
+/**
+ * The `page` query a link selects, typed by the `$page` it came from: the strategy's members under
+ * their wire keys (counts as numbers, cursors as strings), plus the menu arm the read picked.
+ */
+type PageParams<P extends Page = Page> = PageParamsOf<P>;
+/**
+ * The `page` params for the page after `list`, read from its `next` link, or `undefined` on the
+ * last page (or before anything has loaded). Works the same for every strategy, because the
+ * server's link already carries the right parameters. Feed the result back into the signal your
+ * resource's params read:
+ *
+ * ```ts
+ * const next = nextPage(this.albums.value())
+ * if (next) this.page.set(next)
+ * ```
+ */
+declare function nextPage<P extends Page>(list: {
+  readonly $page: P;
+} | undefined): PageParams<P> | undefined;
+/** The `page` params for the page before `list`, from its `prev` link. See {@link nextPage}. */
+declare function prevPage<P extends Page>(list: {
+  readonly $page: P;
+} | undefined): PageParams<P> | undefined;
+/** Options for {@link loadAll}. */
+interface LoadAllOptions {
+  /** Stops the walk, rejecting with the signal's reason. Pass the loader's `abortSignal`. */
+  signal?: AbortSignal;
+  /** Stop after this many pages, as a guard against an unexpectedly large collection. */
+  maxPages?: number;
+}
+/**
+ * Follow `next` links from the first page until the last, and return every member in one plain
+ * array. Use it inside a loader to read a whole (small) collection:
+ *
+ * ```ts
+ * loader: ({ client, abortSignal }) =>
+ *   loadAll(client.genres.list({ signal: abortSignal }), { signal: abortSignal })
+ * ```
+ */
+declare function loadAll<T>(first: Collection<T> | PromiseLike<Collection<T>>, options?: LoadAllOptions): Promise<T[]>;
+//#endregion
+//#region src/transport.d.ts
+/**
+ * A transport that sends every request through Angular's `HttpClient`, so the app's interceptors
+ * run. The body comes back as text for the client to parse, exactly as with `fetchTransport`.
+ *
+ * A non-2xx response resolves with its status, headers and body, because the client maps those to
+ * a `JsonApiError` itself. Only a request that never got a response (status 0: network failure,
+ * CORS, a blocked request) rejects, with the `HttpErrorResponse`. Aborting `req.signal`
+ * unsubscribes, which cancels the HTTP request, and rejects with the signal's reason.
+ */
+declare function httpClientTransport(http: HttpClient): JsonApiTransport;
+//#endregion
+export { JSON_API_CLIENT, JsonApiClientFactory, JsonApiClientOf, JsonApiClientOptions, JsonApiLoaderContext, JsonApiMutationOptions, JsonApiMutationRef, JsonApiResourceError, JsonApiResourceOptions, JsonApiResourceRef, LoadAllOptions, PageParams, Register, RegisteredClient, createJsonApiClientToken, httpClientTransport, injectJsonApiClient, jsonApiMutation, jsonApiResource, loadAll, nextPage, prevPage, provideJsonApiClient };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/provide.ts","../src/resource.ts","../src/mutation.ts","../src/pagination.ts","../src/transport.ts"],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,219 @@
+import { EnvironmentProviders, InjectionToken, Injector, ResourceRef, ResourceStatus, Signal, ValueEqualityFn } from "@angular/core";
+import { ClientOptions, Collection, ErrorCodeOf, JsonApiError, JsonApiTransport, Page, PageParamsOf, StructuralGuardError } from "@haddowg/json-api-client";
+import { HttpClient } from "@angular/common/http";
+
+//#region src/provide.d.ts
+/**
+ * Options for {@link provideJsonApiClient}: the client's options with the transport made
+ * optional. Leave `transport` out to send through `HttpClient`; set it only to opt out.
+ */
+type JsonApiClientOptions = Omit<ClientOptions, 'transport'> & {
+  transport?: JsonApiTransport;
+};
+/** A generated client factory: the bound `createClient` a codegen module exports. */
+type JsonApiClientFactory<C> = (options: ClientOptions) => C;
+/** The client type a generated `createClient` returns. */
+type JsonApiClientOf<F> = F extends ((options: ClientOptions) => infer C) ? C : never;
+/**
+ * Register the app's default client type once, so `injectJsonApiClient()` and `jsonApiResource()`
+ * are typed without a token:
+ *
+ * ```ts
+ * declare module '@haddowg/json-api-angular' {
+ *   interface Register {
+ *     client: JsonApiClientOf<typeof createClient>
+ *   }
+ * }
+ * ```
+ */
+interface Register {}
+/** The default client's type: whatever {@link Register} declares, else `unknown`. */
+type RegisteredClient = Register extends {
+  client: infer C;
+} ? C : unknown;
+/** The token {@link provideJsonApiClient} uses when none is given. */
+declare const JSON_API_CLIENT: InjectionToken<unknown>;
+/**
+ * Create an injection token for one client, so an app can provide several (one per server).
+ * Type it with the client: `createJsonApiClientToken<JsonApiClientOf<typeof createAdminClient>>()`.
+ */
+declare function createJsonApiClientToken<C>(description?: string): InjectionToken<C>;
+/**
+ * Provide a generated client to the environment injector. The client sends through `HttpClient`
+ * (so `provideHttpClient()` must also be present) unless `options.transport` overrides it.
+ *
+ * `options` may be a function, which runs in an injection context, to read values such as the
+ * base URL from other providers. `token` defaults to {@link JSON_API_CLIENT}; pass one from
+ * {@link createJsonApiClientToken} to provide a second client alongside it.
+ */
+declare function provideJsonApiClient<C>(createClient: JsonApiClientFactory<C>, options: JsonApiClientOptions | (() => JsonApiClientOptions), token?: InjectionToken<C>): EnvironmentProviders;
+/**
+ * Inject a provided client. Without a token this returns the default client, typed by
+ * {@link Register}. With a token it returns that token's client.
+ */
+declare function injectJsonApiClient<C = RegisteredClient>(token?: InjectionToken<C>, options?: {
+  injector?: Injector;
+}): C;
+//#endregion
+//#region src/resource.d.ts
+/**
+ * What a read can fail with: a `JsonApiError` for a non-2xx response, a `StructuralGuardError`
+ * for a response that isn't a JSON:API document, or any other error (a network failure, a
+ * validator's error). Narrow with `instanceof`. `E` types the `JsonApiError`'s codes.
+ */
+type JsonApiResourceError<E extends string = string> = JsonApiError<E> | StructuralGuardError | Error;
+/** What the loader receives each time the params change or the resource reloads. */
+interface JsonApiLoaderContext<C, P> {
+  client: C;
+  params: P;
+  /** Aborts when the params change again or the resource is destroyed. Pass it to the read. */
+  abortSignal: AbortSignal;
+  previous: {
+    status: ResourceStatus;
+  };
+}
+/** Options for {@link jsonApiResource}. */
+interface JsonApiResourceOptions<T, P, C> {
+  /**
+   * A reactive function computing the read's params from signals. Return `undefined` while the
+   * read isn't ready (no id yet, say) and the resource stays idle. Leave it out to load once.
+   */
+  params?: () => P | undefined;
+  /** Make the read. Return the client call's promise, passing `abortSignal` as its `signal`. */
+  loader: (context: JsonApiLoaderContext<C, P>) => PromiseLike<T>;
+  /** The client to read with. Defaults to the one `provideJsonApiClient` registered without a token. */
+  client?: InjectionToken<C>;
+  /** The value while nothing has loaded yet. */
+  defaultValue?: T;
+  equal?: ValueEqualityFn<T>;
+  /** Create the resource outside an injection context. */
+  injector?: Injector;
+  debugName?: string;
+}
+/**
+ * Angular's `ResourceRef` with `error()` typed to what a JSON:API read throws, plus
+ * `jsonApiError()`, the error when it is a `JsonApiError` (handy in templates, which can't
+ * use `instanceof`). `E` is the client's error-code union, so a generated client's
+ * `jsonApiError()` carries its server's `ErrorCode`.
+ */
+interface JsonApiResourceRef<T, E extends string = string> extends Omit<ResourceRef<T>, 'error' | 'hasValue'> {
+  readonly error: Signal<JsonApiResourceError<E> | undefined>;
+  readonly jsonApiError: Signal<JsonApiError<E> | undefined>;
+  /** Whether a value is loaded. Narrows `value()` to exclude `undefined`, in templates too. */
+  hasValue(this: T extends undefined ? this : never): this is JsonApiResourceRef<Exclude<T, undefined>, E>;
+  hasValue(): boolean;
+}
+/**
+ * A signal-based JSON:API read: a thin wrapper over Angular's `resource()` that injects the
+ * client and hands it to the loader. Changing a signal the params read starts a new load and
+ * aborts the one in flight.
+ *
+ * ```ts
+ * readonly albums = jsonApiResource({
+ *   params: () => ({ filter: { title: this.search() } }),
+ *   loader: ({ client, params, abortSignal }) =>
+ *     client.albums.list({ ...params, include: ['artist'], signal: abortSignal }),
+ * })
+ * ```
+ */
+declare function jsonApiResource<T, P = unknown, C = RegisteredClient>(options: JsonApiResourceOptions<T, P, C> & {
+  defaultValue: T;
+}): JsonApiResourceRef<T, ErrorCodeOf<C>>;
+declare function jsonApiResource<T, P = unknown, C = RegisteredClient>(options: JsonApiResourceOptions<T, P, C>): JsonApiResourceRef<T | undefined, ErrorCodeOf<C>>;
+//#endregion
+//#region src/mutation.d.ts
+/** Options for {@link jsonApiMutation}. */
+interface JsonApiMutationOptions<C> {
+  /** The client to write with. Defaults to the one `provideJsonApiClient` registered without a token. */
+  client?: InjectionToken<C>;
+  /** Create the mutation outside an injection context. */
+  injector?: Injector;
+}
+/**
+ * The signal-based handle {@link jsonApiMutation} returns. `E` is the client's error-code union,
+ * so a generated client's `jsonApiError()` carries its server's `ErrorCode`.
+ */
+interface JsonApiMutationRef<I, T, E extends string = string> {
+  /**
+   * Run the write. Resolves with its result and rejects with its error; the signals track the
+   * latest call either way.
+   */
+  mutate(input: I): Promise<T>;
+  readonly isPending: Signal<boolean>;
+  readonly error: Signal<JsonApiResourceError<E> | undefined>;
+  /** The error when it is a `JsonApiError`; use `byPath()` on it for form errors. */
+  readonly jsonApiError: Signal<JsonApiError<E> | undefined>;
+  /** The latest successful result. */
+  readonly value: Signal<T | undefined>;
+  /** Clear the value and error. A call still in flight no longer updates the signals. */
+  reset(): void;
+}
+/**
+ * Wrap a client write (create, update, delete, a relationship mutation, a custom action or an
+ * atomic batch) in signals. Nothing is cached or invalidated: `reload()` the resources the write
+ * affects.
+ *
+ * ```ts
+ * readonly rename = jsonApiMutation((client, title: string) =>
+ *   client.albums.id(this.id()).update({ title }),
+ * )
+ * ```
+ */
+declare function jsonApiMutation<I, T, C = RegisteredClient>(mutation: (client: C, input: I) => PromiseLike<T>, options?: JsonApiMutationOptions<C>): JsonApiMutationRef<I, T, ErrorCodeOf<C>>;
+//#endregion
+//#region src/pagination.d.ts
+/**
+ * The `page` query a link selects, typed by the `$page` it came from: the strategy's members under
+ * their wire keys (counts as numbers, cursors as strings), plus the menu arm the read picked.
+ */
+type PageParams<P extends Page = Page> = PageParamsOf<P>;
+/**
+ * The `page` params for the page after `list`, read from its `next` link, or `undefined` on the
+ * last page (or before anything has loaded). Works the same for every strategy, because the
+ * server's link already carries the right parameters. Feed the result back into the signal your
+ * resource's params read:
+ *
+ * ```ts
+ * const next = nextPage(this.albums.value())
+ * if (next) this.page.set(next)
+ * ```
+ */
+declare function nextPage<P extends Page>(list: {
+  readonly $page: P;
+} | undefined): PageParams<P> | undefined;
+/** The `page` params for the page before `list`, from its `prev` link. See {@link nextPage}. */
+declare function prevPage<P extends Page>(list: {
+  readonly $page: P;
+} | undefined): PageParams<P> | undefined;
+/** Options for {@link loadAll}. */
+interface LoadAllOptions {
+  /** Stops the walk, rejecting with the signal's reason. Pass the loader's `abortSignal`. */
+  signal?: AbortSignal;
+  /** Stop after this many pages, as a guard against an unexpectedly large collection. */
+  maxPages?: number;
+}
+/**
+ * Follow `next` links from the first page until the last, and return every member in one plain
+ * array. Use it inside a loader to read a whole (small) collection:
+ *
+ * ```ts
+ * loader: ({ client, abortSignal }) =>
+ *   loadAll(client.genres.list({ signal: abortSignal }), { signal: abortSignal })
+ * ```
+ */
+declare function loadAll<T>(first: Collection<T> | PromiseLike<Collection<T>>, options?: LoadAllOptions): Promise<T[]>;
+//#endregion
+//#region src/transport.d.ts
+/**
+ * A transport that sends every request through Angular's `HttpClient`, so the app's interceptors
+ * run. The body comes back as text for the client to parse, exactly as with `fetchTransport`.
+ *
+ * A non-2xx response resolves with its status, headers and body, because the client maps those to
+ * a `JsonApiError` itself. Only a request that never got a response (status 0: network failure,
+ * CORS, a blocked request) rejects, with the `HttpErrorResponse`. Aborting `req.signal`
+ * unsubscribes, which cancels the HTTP request, and rejects with the signal's reason.
+ */
+declare function httpClientTransport(http: HttpClient): JsonApiTransport;
+//#endregion
+export { JSON_API_CLIENT, JsonApiClientFactory, JsonApiClientOf, JsonApiClientOptions, JsonApiLoaderContext, JsonApiMutationOptions, JsonApiMutationRef, JsonApiResourceError, JsonApiResourceOptions, JsonApiResourceRef, LoadAllOptions, PageParams, Register, RegisteredClient, createJsonApiClientToken, httpClientTransport, injectJsonApiClient, jsonApiMutation, jsonApiResource, loadAll, nextPage, prevPage, provideJsonApiClient };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/provide.ts","../src/resource.ts","../src/mutation.ts","../src/pagination.ts","../src/transport.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -0,0 +1,254 @@
+import { InjectionToken, Injector, assertInInjectionContext, computed, inject, makeEnvironmentProviders, resource, signal } from "@angular/core";
+import { JsonApiError } from "@haddowg/json-api-client";
+import { HttpClient, HttpErrorResponse } from "@angular/common/http";
+//#region src/transport.ts
+/**
+* A transport that sends every request through Angular's `HttpClient`, so the app's interceptors
+* run. The body comes back as text for the client to parse, exactly as with `fetchTransport`.
+*
+* A non-2xx response resolves with its status, headers and body, because the client maps those to
+* a `JsonApiError` itself. Only a request that never got a response (status 0: network failure,
+* CORS, a blocked request) rejects, with the `HttpErrorResponse`. Aborting `req.signal`
+* unsubscribes, which cancels the HTTP request, and rejects with the signal's reason.
+*/
+function httpClientTransport(http) {
+	return (req) => new Promise((resolve, reject) => {
+		const signal = req.signal;
+		if (signal?.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		let unsubscribe;
+		const onAbort = () => {
+			unsubscribe?.();
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		const settle = () => signal?.removeEventListener("abort", onAbort);
+		const subscription = http.request(req.method, req.url, {
+			body: req.body ?? null,
+			headers: req.headers,
+			observe: "response",
+			responseType: "text"
+		}).subscribe({
+			next: (res) => {
+				settle();
+				resolve({
+					status: res.status,
+					headers: toRecord(res.headers),
+					body: res.body ?? ""
+				});
+			},
+			error: (error) => {
+				settle();
+				if (error instanceof HttpErrorResponse && error.status !== 0) {
+					resolve({
+						status: error.status,
+						headers: toRecord(error.headers),
+						body: errorBody(error.error)
+					});
+					return;
+				}
+				reject(error);
+			}
+		});
+		unsubscribe = () => subscription.unsubscribe();
+	});
+}
+function toRecord(headers) {
+	const out = {};
+	for (const name of headers.keys()) {
+		const values = headers.getAll(name);
+		if (values !== null) out[name.toLowerCase()] = values.join(", ");
+	}
+	return out;
+}
+function errorBody(body) {
+	if (typeof body === "string") return body;
+	if (body === null || body === void 0) return "";
+	return JSON.stringify(body);
+}
+//#endregion
+//#region src/provide.ts
+/** The token {@link provideJsonApiClient} uses when none is given. */
+const JSON_API_CLIENT = new InjectionToken("JSON_API_CLIENT");
+/**
+* Create an injection token for one client, so an app can provide several (one per server).
+* Type it with the client: `createJsonApiClientToken<JsonApiClientOf<typeof createAdminClient>>()`.
+*/
+function createJsonApiClientToken(description = "JsonApiClient") {
+	return new InjectionToken(description);
+}
+/**
+* Provide a generated client to the environment injector. The client sends through `HttpClient`
+* (so `provideHttpClient()` must also be present) unless `options.transport` overrides it.
+*
+* `options` may be a function, which runs in an injection context, to read values such as the
+* base URL from other providers. `token` defaults to {@link JSON_API_CLIENT}; pass one from
+* {@link createJsonApiClientToken} to provide a second client alongside it.
+*/
+function provideJsonApiClient(createClient, options, token = JSON_API_CLIENT) {
+	return makeEnvironmentProviders([{
+		provide: token,
+		useFactory: () => {
+			const resolved = typeof options === "function" ? options() : options;
+			return createClient({
+				...resolved,
+				transport: resolved.transport ?? httpClientTransport(inject(HttpClient))
+			});
+		}
+	}]);
+}
+/**
+* Inject a provided client. Without a token this returns the default client, typed by
+* {@link Register}. With a token it returns that token's client.
+*/
+function injectJsonApiClient(token, options) {
+	const resolved = token ?? JSON_API_CLIENT;
+	if (options?.injector !== void 0) return options.injector.get(resolved);
+	assertInInjectionContext(injectJsonApiClient);
+	return inject(resolved);
+}
+//#endregion
+//#region src/mutation.ts
+/**
+* Wrap a client write (create, update, delete, a relationship mutation, a custom action or an
+* atomic batch) in signals. Nothing is cached or invalidated: `reload()` the resources the write
+* affects.
+*
+* ```ts
+* readonly rename = jsonApiMutation((client, title: string) =>
+*   client.albums.id(this.id()).update({ title }),
+* )
+* ```
+*/
+function jsonApiMutation(mutation, options = {}) {
+	if (options.injector === void 0) assertInInjectionContext(jsonApiMutation);
+	const client = (options.injector ?? inject(Injector)).get(options.client ?? JSON_API_CLIENT);
+	const value = signal(void 0);
+	const error = signal(void 0);
+	const pending = signal(0);
+	let generation = 0;
+	const mutate = async (input) => {
+		const current = ++generation;
+		pending.update((n) => n + 1);
+		error.set(void 0);
+		try {
+			const result = await mutation(client, input);
+			if (current === generation) value.set(result);
+			return result;
+		} catch (thrown) {
+			if (current === generation) error.set(thrown instanceof Error ? thrown : new Error(String(thrown), { cause: thrown }));
+			throw thrown;
+		} finally {
+			pending.update((n) => Math.max(0, n - 1));
+		}
+	};
+	return {
+		mutate,
+		isPending: computed(() => pending() > 0),
+		error: error.asReadonly(),
+		jsonApiError: computed(() => {
+			const e = error();
+			return e instanceof JsonApiError ? e : void 0;
+		}),
+		value: value.asReadonly(),
+		reset: () => {
+			generation++;
+			value.set(void 0);
+			error.set(void 0);
+			pending.set(0);
+		}
+	};
+}
+//#endregion
+//#region src/pagination.ts
+/**
+* The `page` params for the page after `list`, read from its `next` link, or `undefined` on the
+* last page (or before anything has loaded). Works the same for every strategy, because the
+* server's link already carries the right parameters. Feed the result back into the signal your
+* resource's params read:
+*
+* ```ts
+* const next = nextPage(this.albums.value())
+* if (next) this.page.set(next)
+* ```
+*/
+function nextPage(list) {
+	return pageParams(list?.$page, list?.$page.links.next);
+}
+/** The `page` params for the page before `list`, from its `prev` link. See {@link nextPage}. */
+function prevPage(list) {
+	return pageParams(list?.$page, list?.$page.links.prev);
+}
+const CURSOR_ROLES = ["after", "before"];
+function pageParams(page, link) {
+	if (page === void 0 || link === void 0) return;
+	const keys = Object.entries(page.keys);
+	const query = link.includes("?") ? link.slice(link.indexOf("?") + 1).split("#")[0] : "";
+	const params = {};
+	for (const [name, value] of new URLSearchParams(query)) {
+		const member = /^page\[([^\]]+)\]$/.exec(name)?.[1];
+		if (member === void 0) continue;
+		const role = keys.find(([, key]) => key === member)?.[0];
+		const count = Number(value);
+		params[member] = role !== void 0 && !CURSOR_ROLES.includes(role) && value !== "" && Number.isFinite(count) ? count : value;
+	}
+	return params;
+}
+/**
+* Follow `next` links from the first page until the last, and return every member in one plain
+* array. Use it inside a loader to read a whole (small) collection:
+*
+* ```ts
+* loader: ({ client, abortSignal }) =>
+*   loadAll(client.genres.list({ signal: abortSignal }), { signal: abortSignal })
+* ```
+*/
+async function loadAll(first, options = {}) {
+	const { signal, maxPages = Number.POSITIVE_INFINITY } = options;
+	let page = await first;
+	const all = [];
+	let count = 0;
+	while (page !== void 0 && count < maxPages) {
+		all.push(...page);
+		count++;
+		if (count >= maxPages) break;
+		signal?.throwIfAborted();
+		page = await page.$next(signal !== void 0 ? { signal } : void 0);
+	}
+	return all;
+}
+//#endregion
+//#region src/resource.ts
+function jsonApiResource(options) {
+	if (options.injector === void 0) assertInInjectionContext(jsonApiResource);
+	const injector = options.injector ?? inject(Injector);
+	const client = injector.get(options.client ?? JSON_API_CLIENT);
+	const ref = resource({
+		...options.params !== void 0 ? { params: options.params } : {},
+		loader: ({ params, abortSignal, previous }) => options.loader({
+			client,
+			params,
+			abortSignal,
+			previous
+		}),
+		...options.defaultValue !== void 0 ? { defaultValue: options.defaultValue } : {},
+		...options.equal !== void 0 ? { equal: options.equal } : {},
+		...options.debugName !== void 0 ? { debugName: options.debugName } : {},
+		injector
+	});
+	const jsonApiError = computed(() => {
+		const error = ref.error();
+		return error instanceof JsonApiError ? error : void 0;
+	});
+	Object.defineProperty(ref, "jsonApiError", {
+		value: jsonApiError,
+		enumerable: true
+	});
+	return ref;
+}
+//#endregion
+export { JSON_API_CLIENT, createJsonApiClientToken, httpClientTransport, injectJsonApiClient, jsonApiMutation, jsonApiResource, loadAll, nextPage, prevPage, provideJsonApiClient };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/transport.ts","../src/provide.ts","../src/mutation.ts","../src/pagination.ts","../src/resource.ts"],"sourcesContent":["import { HttpErrorResponse, type HttpClient, type HttpHeaders } from '@angular/common/http'\nimport type { JsonApiTransport, TransportResponse } from '@haddowg/json-api-client'\n\n/**\n * A transport that sends every request through Angular's `HttpClient`, so the app's interceptors\n * run. The body comes back as text for the client to parse, exactly as with `fetchTransport`.\n *\n * A non-2xx response resolves with its status, headers and body, because the client maps those to\n * a `JsonApiError` itself. Only a request that never got a response (status 0: network failure,\n * CORS, a blocked request) rejects, with the `HttpErrorResponse`. Aborting `req.signal`\n * unsubscribes, which cancels the HTTP request, and rejects with the signal's reason.\n */\nexport function httpClientTransport(http: HttpClient): JsonApiTransport {\n  return (req) =>\n    new Promise<TransportResponse>((resolve, reject) => {\n      const signal = req.signal\n      if (signal?.aborted) {\n        reject(signal.reason)\n        return\n      }\n\n      let unsubscribe: (() => void) | undefined\n      const onAbort = (): void => {\n        unsubscribe?.()\n        reject(signal?.reason)\n      }\n      signal?.addEventListener('abort', onAbort, { once: true })\n      const settle = (): void => signal?.removeEventListener('abort', onAbort)\n\n      const subscription = http\n        .request(req.method, req.url, {\n          body: req.body ?? null,\n          headers: req.headers,\n          observe: 'response',\n          responseType: 'text',\n        })\n        .subscribe({\n          next: (res) => {\n            settle()\n            resolve({ status: res.status, headers: toRecord(res.headers), body: res.body ?? '' })\n          },\n          error: (error: unknown) => {\n            settle()\n            if (error instanceof HttpErrorResponse && error.status !== 0) {\n              resolve({\n                status: error.status,\n                headers: toRecord(error.headers),\n                body: errorBody(error.error),\n              })\n              return\n            }\n            reject(error)\n          },\n        })\n      unsubscribe = () => subscription.unsubscribe()\n    })\n}\n\nfunction toRecord(headers: HttpHeaders): Record<string, string> {\n  const out: Record<string, string> = {}\n  for (const name of headers.keys()) {\n    const values = headers.getAll(name)\n    if (values !== null) {\n      out[name.toLowerCase()] = values.join(', ')\n    }\n  }\n  return out\n}\n\n// With responseType 'text' the error body is already a string. Anything else (an interceptor that\n// replaced it) is serialised so the client can still try to parse a JSON:API error document.\nfunction errorBody(body: unknown): string {\n  if (typeof body === 'string') {\n    return body\n  }\n  if (body === null || body === undefined) {\n    return ''\n  }\n  return JSON.stringify(body)\n}\n","import { HttpClient } from '@angular/common/http'\nimport {\n  assertInInjectionContext,\n  type EnvironmentProviders,\n  inject,\n  InjectionToken,\n  type Injector,\n  makeEnvironmentProviders,\n} from '@angular/core'\nimport type { ClientOptions, JsonApiTransport } from '@haddowg/json-api-client'\nimport { httpClientTransport } from './transport'\n\n/**\n * Options for {@link provideJsonApiClient}: the client's options with the transport made\n * optional. Leave `transport` out to send through `HttpClient`; set it only to opt out.\n */\nexport type JsonApiClientOptions = Omit<ClientOptions, 'transport'> & {\n  transport?: JsonApiTransport\n}\n\n/** A generated client factory: the bound `createClient` a codegen module exports. */\nexport type JsonApiClientFactory<C> = (options: ClientOptions) => C\n\n/** The client type a generated `createClient` returns. */\nexport type JsonApiClientOf<F> = F extends (options: ClientOptions) => infer C ? C : never\n\n/**\n * Register the app's default client type once, so `injectJsonApiClient()` and `jsonApiResource()`\n * are typed without a token:\n *\n * ```ts\n * declare module '@haddowg/json-api-angular' {\n *   interface Register {\n *     client: JsonApiClientOf<typeof createClient>\n *   }\n * }\n * ```\n */\n// oxlint-disable-next-line typescript/no-empty-object-type -- filled in by module augmentation\nexport interface Register {}\n\n/** The default client's type: whatever {@link Register} declares, else `unknown`. */\nexport type RegisteredClient = Register extends { client: infer C } ? C : unknown\n\n/** The token {@link provideJsonApiClient} uses when none is given. */\nexport const JSON_API_CLIENT = new InjectionToken<unknown>('JSON_API_CLIENT')\n\n/**\n * Create an injection token for one client, so an app can provide several (one per server).\n * Type it with the client: `createJsonApiClientToken<JsonApiClientOf<typeof createAdminClient>>()`.\n */\nexport function createJsonApiClientToken<C>(description = 'JsonApiClient'): InjectionToken<C> {\n  return new InjectionToken<C>(description)\n}\n\n/**\n * Provide a generated client to the environment injector. The client sends through `HttpClient`\n * (so `provideHttpClient()` must also be present) unless `options.transport` overrides it.\n *\n * `options` may be a function, which runs in an injection context, to read values such as the\n * base URL from other providers. `token` defaults to {@link JSON_API_CLIENT}; pass one from\n * {@link createJsonApiClientToken} to provide a second client alongside it.\n */\nexport function provideJsonApiClient<C>(\n  createClient: JsonApiClientFactory<C>,\n  options: JsonApiClientOptions | (() => JsonApiClientOptions),\n  token: InjectionToken<C> = JSON_API_CLIENT as InjectionToken<C>,\n): EnvironmentProviders {\n  return makeEnvironmentProviders([\n    {\n      provide: token,\n      useFactory: (): C => {\n        const resolved = typeof options === 'function' ? options() : options\n        return createClient({\n          ...resolved,\n          transport: resolved.transport ?? httpClientTransport(inject(HttpClient)),\n        })\n      },\n    },\n  ])\n}\n\n/**\n * Inject a provided client. Without a token this returns the default client, typed by\n * {@link Register}. With a token it returns that token's client.\n */\nexport function injectJsonApiClient<C = RegisteredClient>(\n  token?: InjectionToken<C>,\n  options?: { injector?: Injector },\n): C {\n  const resolved = token ?? (JSON_API_CLIENT as InjectionToken<C>)\n  if (options?.injector !== undefined) {\n    return options.injector.get(resolved)\n  }\n  assertInInjectionContext(injectJsonApiClient)\n  return inject(resolved)\n}\n","import {\n  assertInInjectionContext,\n  computed,\n  inject,\n  type InjectionToken,\n  Injector,\n  type Signal,\n  signal,\n} from '@angular/core'\nimport { type ErrorCodeOf, JsonApiError } from '@haddowg/json-api-client'\nimport { JSON_API_CLIENT, type RegisteredClient } from './provide'\nimport type { JsonApiResourceError } from './resource'\n\n/** Options for {@link jsonApiMutation}. */\nexport interface JsonApiMutationOptions<C> {\n  /** The client to write with. Defaults to the one `provideJsonApiClient` registered without a token. */\n  client?: InjectionToken<C>\n  /** Create the mutation outside an injection context. */\n  injector?: Injector\n}\n\n/**\n * The signal-based handle {@link jsonApiMutation} returns. `E` is the client's error-code union,\n * so a generated client's `jsonApiError()` carries its server's `ErrorCode`.\n */\nexport interface JsonApiMutationRef<I, T, E extends string = string> {\n  /**\n   * Run the write. Resolves with its result and rejects with its error; the signals track the\n   * latest call either way.\n   */\n  mutate(input: I): Promise<T>\n  readonly isPending: Signal<boolean>\n  readonly error: Signal<JsonApiResourceError<E> | undefined>\n  /** The error when it is a `JsonApiError`; use `byPath()` on it for form errors. */\n  readonly jsonApiError: Signal<JsonApiError<E> | undefined>\n  /** The latest successful result. */\n  readonly value: Signal<T | undefined>\n  /** Clear the value and error. A call still in flight no longer updates the signals. */\n  reset(): void\n}\n\n/**\n * Wrap a client write (create, update, delete, a relationship mutation, a custom action or an\n * atomic batch) in signals. Nothing is cached or invalidated: `reload()` the resources the write\n * affects.\n *\n * ```ts\n * readonly rename = jsonApiMutation((client, title: string) =>\n *   client.albums.id(this.id()).update({ title }),\n * )\n * ```\n */\nexport function jsonApiMutation<I, T, C = RegisteredClient>(\n  mutation: (client: C, input: I) => PromiseLike<T>,\n  options: JsonApiMutationOptions<C> = {},\n): JsonApiMutationRef<I, T, ErrorCodeOf<C>> {\n  if (options.injector === undefined) {\n    assertInInjectionContext(jsonApiMutation)\n  }\n  const injector = options.injector ?? inject(Injector)\n  const client = injector.get(options.client ?? (JSON_API_CLIENT as InjectionToken<C>))\n\n  const value = signal<T | undefined>(undefined)\n  const error = signal<JsonApiResourceError | undefined>(undefined)\n  const pending = signal(0)\n  // Each call and reset bumps this, so only the latest call writes to the signals.\n  let generation = 0\n\n  const mutate = async (input: I): Promise<T> => {\n    const current = ++generation\n    pending.update((n) => n + 1)\n    error.set(undefined)\n    try {\n      const result = await mutation(client, input)\n      if (current === generation) {\n        value.set(result)\n      }\n      return result\n    } catch (thrown) {\n      if (current === generation) {\n        error.set(thrown instanceof Error ? thrown : new Error(String(thrown), { cause: thrown }))\n      }\n      throw thrown\n    } finally {\n      pending.update((n) => Math.max(0, n - 1))\n    }\n  }\n\n  return {\n    mutate,\n    isPending: computed(() => pending() > 0),\n    error: error.asReadonly(),\n    jsonApiError: computed(() => {\n      const e = error()\n      return e instanceof JsonApiError ? e : undefined\n    }),\n    value: value.asReadonly(),\n    reset: () => {\n      generation++\n      value.set(undefined)\n      error.set(undefined)\n      pending.set(0)\n    },\n  }\n}\n","import type { Collection, Page, PageParamsOf, PaginatorRole } from '@haddowg/json-api-client'\n\n/**\n * The `page` query a link selects, typed by the `$page` it came from: the strategy's members under\n * their wire keys (counts as numbers, cursors as strings), plus the menu arm the read picked.\n */\nexport type PageParams<P extends Page = Page> = PageParamsOf<P>\n\n/**\n * The `page` params for the page after `list`, read from its `next` link, or `undefined` on the\n * last page (or before anything has loaded). Works the same for every strategy, because the\n * server's link already carries the right parameters. Feed the result back into the signal your\n * resource's params read:\n *\n * ```ts\n * const next = nextPage(this.albums.value())\n * if (next) this.page.set(next)\n * ```\n */\nexport function nextPage<P extends Page>(\n  list: { readonly $page: P } | undefined,\n): PageParams<P> | undefined {\n  return pageParams(list?.$page, list?.$page.links.next)\n}\n\n/** The `page` params for the page before `list`, from its `prev` link. See {@link nextPage}. */\nexport function prevPage<P extends Page>(\n  list: { readonly $page: P } | undefined,\n): PageParams<P> | undefined {\n  return pageParams(list?.$page, list?.$page.links.prev)\n}\n\nconst CURSOR_ROLES: readonly string[] = ['after', 'before']\n\nfunction pageParams<P extends Page>(\n  page: P | undefined,\n  link: string | undefined,\n): PageParams<P> | undefined {\n  if (page === undefined || link === undefined) {\n    return undefined\n  }\n  const keys = Object.entries(page.keys) as [PaginatorRole, string][]\n  const query = link.includes('?') ? link.slice(link.indexOf('?') + 1).split('#')[0] : ''\n  const params: Record<string, string | number> = {}\n  for (const [name, value] of new URLSearchParams(query)) {\n    const member = /^page\\[([^\\]]+)\\]$/.exec(name)?.[1]\n    if (member === undefined) {\n      continue\n    }\n    const role = keys.find(([, key]) => key === member)?.[0]\n    const count = Number(value)\n    params[member] =\n      role !== undefined && !CURSOR_ROLES.includes(role) && value !== '' && Number.isFinite(count)\n        ? count\n        : value\n  }\n  return params as PageParams<P>\n}\n\n/** Options for {@link loadAll}. */\nexport interface LoadAllOptions {\n  /** Stops the walk, rejecting with the signal's reason. Pass the loader's `abortSignal`. */\n  signal?: AbortSignal\n  /** Stop after this many pages, as a guard against an unexpectedly large collection. */\n  maxPages?: number\n}\n\n/**\n * Follow `next` links from the first page until the last, and return every member in one plain\n * array. Use it inside a loader to read a whole (small) collection:\n *\n * ```ts\n * loader: ({ client, abortSignal }) =>\n *   loadAll(client.genres.list({ signal: abortSignal }), { signal: abortSignal })\n * ```\n */\nexport async function loadAll<T>(\n  first: Collection<T> | PromiseLike<Collection<T>>,\n  options: LoadAllOptions = {},\n): Promise<T[]> {\n  const { signal, maxPages = Number.POSITIVE_INFINITY } = options\n  let page: Collection<T> | undefined = await first\n  const all: T[] = []\n  let count = 0\n  while (page !== undefined && count < maxPages) {\n    all.push(...page)\n    count++\n    if (count >= maxPages) {\n      break\n    }\n    signal?.throwIfAborted()\n    page = await page.$next(signal !== undefined ? { signal } : undefined)\n  }\n  return all\n}\n","// The only module that touches Angular's `resource()`. It is experimental before Angular 22, so a\n// change to its options or ref shape is absorbed here.\nimport {\n  assertInInjectionContext,\n  computed,\n  inject,\n  type InjectionToken,\n  Injector,\n  resource,\n  type ResourceRef,\n  type ResourceStatus,\n  type Signal,\n  type ValueEqualityFn,\n} from '@angular/core'\nimport { type ErrorCodeOf, JsonApiError, type StructuralGuardError } from '@haddowg/json-api-client'\nimport { JSON_API_CLIENT, type RegisteredClient } from './provide'\n\n/**\n * What a read can fail with: a `JsonApiError` for a non-2xx response, a `StructuralGuardError`\n * for a response that isn't a JSON:API document, or any other error (a network failure, a\n * validator's error). Narrow with `instanceof`. `E` types the `JsonApiError`'s codes.\n */\nexport type JsonApiResourceError<E extends string = string> =\n  | JsonApiError<E>\n  | StructuralGuardError\n  | Error\n\n/** What the loader receives each time the params change or the resource reloads. */\nexport interface JsonApiLoaderContext<C, P> {\n  client: C\n  params: P\n  /** Aborts when the params change again or the resource is destroyed. Pass it to the read. */\n  abortSignal: AbortSignal\n  previous: { status: ResourceStatus }\n}\n\n/** Options for {@link jsonApiResource}. */\nexport interface JsonApiResourceOptions<T, P, C> {\n  /**\n   * A reactive function computing the read's params from signals. Return `undefined` while the\n   * read isn't ready (no id yet, say) and the resource stays idle. Leave it out to load once.\n   */\n  params?: () => P | undefined\n  /** Make the read. Return the client call's promise, passing `abortSignal` as its `signal`. */\n  loader: (context: JsonApiLoaderContext<C, P>) => PromiseLike<T>\n  /** The client to read with. Defaults to the one `provideJsonApiClient` registered without a token. */\n  client?: InjectionToken<C>\n  /** The value while nothing has loaded yet. */\n  defaultValue?: T\n  equal?: ValueEqualityFn<T>\n  /** Create the resource outside an injection context. */\n  injector?: Injector\n  debugName?: string\n}\n\n/**\n * Angular's `ResourceRef` with `error()` typed to what a JSON:API read throws, plus\n * `jsonApiError()`, the error when it is a `JsonApiError` (handy in templates, which can't\n * use `instanceof`). `E` is the client's error-code union, so a generated client's\n * `jsonApiError()` carries its server's `ErrorCode`.\n */\nexport interface JsonApiResourceRef<T, E extends string = string> extends Omit<\n  ResourceRef<T>,\n  'error' | 'hasValue'\n> {\n  readonly error: Signal<JsonApiResourceError<E> | undefined>\n  readonly jsonApiError: Signal<JsonApiError<E> | undefined>\n  /** Whether a value is loaded. Narrows `value()` to exclude `undefined`, in templates too. */\n  hasValue(\n    this: T extends undefined ? this : never,\n  ): this is JsonApiResourceRef<Exclude<T, undefined>, E>\n  hasValue(): boolean\n}\n\n/**\n * A signal-based JSON:API read: a thin wrapper over Angular's `resource()` that injects the\n * client and hands it to the loader. Changing a signal the params read starts a new load and\n * aborts the one in flight.\n *\n * ```ts\n * readonly albums = jsonApiResource({\n *   params: () => ({ filter: { title: this.search() } }),\n *   loader: ({ client, params, abortSignal }) =>\n *     client.albums.list({ ...params, include: ['artist'], signal: abortSignal }),\n * })\n * ```\n */\nexport function jsonApiResource<T, P = unknown, C = RegisteredClient>(\n  options: JsonApiResourceOptions<T, P, C> & { defaultValue: T },\n): JsonApiResourceRef<T, ErrorCodeOf<C>>\nexport function jsonApiResource<T, P = unknown, C = RegisteredClient>(\n  options: JsonApiResourceOptions<T, P, C>,\n): JsonApiResourceRef<T | undefined, ErrorCodeOf<C>>\nexport function jsonApiResource<T, P, C>(\n  options: JsonApiResourceOptions<T, P, C>,\n): JsonApiResourceRef<T | undefined, ErrorCodeOf<C>> {\n  if (options.injector === undefined) {\n    assertInInjectionContext(jsonApiResource)\n  }\n  const injector = options.injector ?? inject(Injector)\n  const client = injector.get(options.client ?? (JSON_API_CLIENT as InjectionToken<C>))\n\n  const ref = resource<T | undefined, P | undefined>({\n    ...(options.params !== undefined ? { params: options.params } : {}),\n    loader: ({ params, abortSignal, previous }) =>\n      options.loader({ client, params: params as P, abortSignal, previous }),\n    ...(options.defaultValue !== undefined ? { defaultValue: options.defaultValue } : {}),\n    ...(options.equal !== undefined\n      ? { equal: options.equal as ValueEqualityFn<T | undefined> }\n      : {}),\n    ...(options.debugName !== undefined ? { debugName: options.debugName } : {}),\n    injector,\n  })\n\n  const jsonApiError = computed(() => {\n    const error = ref.error()\n    return error instanceof JsonApiError ? error : undefined\n  })\n  Object.defineProperty(ref, 'jsonApiError', { value: jsonApiError, enumerable: true })\n  return ref as unknown as JsonApiResourceRef<T | undefined, ErrorCodeOf<C>>\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@haddowg/json-api-angular",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "Signal-based Angular bindings for the JSON:API client: an HttpClient transport, DI providers, and resource/mutation helpers.",
+  "license": "MIT",
+  "author": "Gregory Haddow (https://github.com/haddowg)",
+  "homepage": "https://haddowg.github.io/json-api-ts/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haddowg/json-api-ts.git",
+    "directory": "packages/angular"
+  },
+  "bugs": "https://github.com/haddowg/json-api-ts/issues",
+  "keywords": [
+    "json-api",
+    "jsonapi",
+    "typescript",
+    "angular",
+    "signals",
+    "httpclient",
+    "openapi"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@haddowg/json-api-client": "^1.2.0"
+  },
+  "peerDependencies": {
+    "@angular/common": "^20.0.0 || ^21.0.0 || ^22.0.0",
+    "@angular/core": "^20.0.0 || ^21.0.0 || ^22.0.0"
+  },
+  "devDependencies": {
+    "@angular/common": "^21.0.0",
+    "@angular/compiler": "^21.0.0",
+    "@angular/core": "^21.0.0",
+    "@angular/platform-browser": "^21.0.0",
+    "jsdom": "^25.0.0",
+    "rxjs": "^7.8.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint:publish": "publint --strict && attw --pack ."
+  }
 }