@lunora/angular 0.0.1 → 1.0.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,146 @@
+import { InjectionToken, EnvironmentProviders, DestroyRef, Signal } from '@angular/core';
+import { LunoraClient, LunoraClientOptions, ConnectionStatus, SubscriptionError, FunctionReference, ArgsOf, ReturnOf, MutationCallOptions } from '@lunora/client';
+export type { ArgsOf, ConnectionStatus, FunctionReference, LunoraClient, LunoraClientOptions, MutationCallOptions, ReturnOf, SubscriptionError, Unsubscribe } from '@lunora/client';
+export { SKIP } from '@lunora/client/query';
+/**
+* DI token carrying the framework-neutral {@link LunoraClient}. Every reactive
+* primitive in this adapter (`liveQuery`, `mutate`, `connectionStatus`) reads the
+* client from here, so a single {@link provideLunora} in the application config
+* wires the whole app.
+*
+* The token has a root-scoped default factory, so it resolves even without
+* {@link provideLunora}: it builds one same-origin browser client (which opens
+* its WebSocket lazily on the first subscription). Call {@link provideLunora} to
+* point it at a remote URL or hand it a pre-built client.
+*/
+declare const LUNORA_CLIENT: InjectionToken<LunoraClient>;
+/**
+* Options accepted by {@link provideLunora}. Identical to {@link LunoraClientOptions}
+* except `url` is optional — it defaults to the page origin in the browser (and to
+* `""` on the server; pass an explicit `url` for SSR data-loading — see
+* {@link sameOriginUrl}).
+*/
+type ProvideLunoraOptions = Omit<LunoraClientOptions, "url"> & {
+  url?: string;
+};
+/**
+* Wire a {@link LunoraClient} into the application injector. Add the result to the
+* `providers` array of an Angular application config (or any `EnvironmentProviders`
+* consumer):
+*
+* ```ts
+* export const appConfig: ApplicationConfig = {
+*     providers: [provideLunora({ url: "https://api.example.com" })],
+* };
+* ```
+*
+* Pass {@link LunoraClientOptions} to configure a fresh client (URL defaults to
+* the page origin), or hand in an already-constructed {@link LunoraClient} to
+* share one instance (e.g. a client you also preload against during SSR).
+*/
+declare const provideLunora: (optionsOrClient?: LunoraClient | ProvideLunoraOptions) => EnvironmentProviders;
+/**
+* Read the {@link LunoraClient} from the current injector. Call inside an
+* injection context (a component/service field initializer or constructor, or a
+* `runInInjectionContext` callback). Use it to hold the client for imperative
+* calls — e.g. `mutation`/`action` from event handlers, which run outside an
+* injection context:
+*
+* ```ts
+* private readonly client = injectLunoraClient();
+* send = (text: string) => this.client.mutation(api.messages.send, { text });
+* ```
+*/
+declare const injectLunoraClient: () => LunoraClient;
+interface ConnectionStatusOptions {
+  /** Client to observe. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /** `DestroyRef` whose `onDestroy` removes the status listener. Defaults to `inject(DestroyRef)`. */
+  destroyRef?: DestroyRef;
+}
+/**
+* A `signal` of the client's aggregate live-socket status across all shard
+* connections. Reads the current status synchronously and updates on every
+* transition (`idle` → `connecting` → `connected` → `offline`). The Angular
+* equivalent of `@lunora/react`'s `useConnectionStatus`.
+*
+* The listener is removed when the owning `DestroyRef` fires. Call from an
+* injection context (component/service field or constructor).
+*/
+declare const connectionStatus: (options?: ConnectionStatusOptions) => Signal<ConnectionStatus>;
+interface LiveQueryOptions {
+  /**
+  * Client to bind to. Defaults to the injected `LUNORA_CLIENT`; pass one
+  * explicitly to use `liveQuery` outside an injection context (or in a test).
+  */
+  client?: LunoraClient;
+  /**
+  * `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to
+  * `inject(DestroyRef)` — the calling component/service — so it closes when that
+  * component is destroyed. Pass one explicitly to control the lifetime yourself.
+  */
+  destroyRef?: DestroyRef;
+  /**
+  * Called when the subscription errors after the initial attach — the async
+  * error channel `createQuerySubscription` only wires when a sink is present.
+  * Without it, a post-attach failure is dropped silently: the signal simply
+  * stops updating with no error state exposed. Pass a handler to surface it
+  * (log, toast, set an error signal of your own).
+  */
+  onError?: (error: SubscriptionError) => void;
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/**
+* Subscribe to a server query and mirror its value into an Angular `signal`.
+*
+* Reads `undefined` until the first server frame lands, then updates on every
+* delta the WebSocket pushes. The underlying subscription is torn down
+* automatically when the owning `DestroyRef` fires (the component/service is
+* destroyed), so there is no leaked socket subscription.
+*
+* Call it from an injection context (a component/service field initializer or
+* constructor) so the default `inject(DestroyRef)` resolves the caller's
+* lifetime:
+*
+* ```ts
+* export class MessagesComponent {
+*     readonly messages = liveQuery(api.messages.list, { channelId: "general" });
+* }
+* ```
+*
+* Pass `"skip"` (the `SKIP` sentinel from `@lunora/client/query`) as `args` to
+* short-circuit — no network call, no socket; the signal stays `undefined`. To
+* call outside an injection context (e.g. lazily in `ngOnInit`), supply `client`
+* and `destroyRef` via {@link LiveQueryOptions}.
+*/
+declare const liveQuery: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip", options?: LiveQueryOptions) => Signal<ReturnOf<F> | undefined>;
+interface MutateOptions<F extends FunctionReference> extends MutationCallOptions<unknown, unknown, ArgsOf<F>> {
+  /**
+  * Client to run the mutation on. Defaults to the injected `LUNORA_CLIENT`.
+  * Because mutations usually fire from event handlers — which run *outside* an
+  * injection context — capture the client once (`injectLunoraClient()` in a
+  * field) and pass it here, or call `client.mutation(...)` directly.
+  */
+  client?: LunoraClient;
+}
+/**
+* Run a Lunora mutation and resolve with the server result (rejects on failure).
+*
+* Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
+* call options pass straight through to `client.mutation`, which applies and
+* rolls them back against the live subscription cache — the same cache
+* `liveQuery` reads, so an optimistic write reflects immediately and
+* reverts on failure. The client's offline queue also engages when the socket is
+* down, so the write stays durable across reconnects.
+*
+* ```ts
+* private readonly client = injectLunoraClient();
+* send = (text: string) => mutate(api.messages.send, { text }, { client: this.client });
+* ```
+*
+* When called from within an injection context you may omit `client` and let it
+* resolve from the injector.
+*/
+declare const mutate: <F extends FunctionReference>(reference: F, args: ArgsOf<F>, options?: MutateOptions<F>) => Promise<ReturnOf<F>>;
+export { type ConnectionStatusOptions, LUNORA_CLIENT, type LiveQueryOptions, type MutateOptions, type ProvideLunoraOptions, connectionStatus, injectLunoraClient, liveQuery, mutate, provideLunora };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import { InjectionToken, EnvironmentProviders, DestroyRef, Signal } from '@angular/core';
+import { LunoraClient, LunoraClientOptions, ConnectionStatus, SubscriptionError, FunctionReference, ArgsOf, ReturnOf, MutationCallOptions } from '@lunora/client';
+export type { ArgsOf, ConnectionStatus, FunctionReference, LunoraClient, LunoraClientOptions, MutationCallOptions, ReturnOf, SubscriptionError, Unsubscribe } from '@lunora/client';
+export { SKIP } from '@lunora/client/query';
+/**
+* DI token carrying the framework-neutral {@link LunoraClient}. Every reactive
+* primitive in this adapter (`liveQuery`, `mutate`, `connectionStatus`) reads the
+* client from here, so a single {@link provideLunora} in the application config
+* wires the whole app.
+*
+* The token has a root-scoped default factory, so it resolves even without
+* {@link provideLunora}: it builds one same-origin browser client (which opens
+* its WebSocket lazily on the first subscription). Call {@link provideLunora} to
+* point it at a remote URL or hand it a pre-built client.
+*/
+declare const LUNORA_CLIENT: InjectionToken<LunoraClient>;
+/**
+* Options accepted by {@link provideLunora}. Identical to {@link LunoraClientOptions}
+* except `url` is optional — it defaults to the page origin in the browser (and to
+* `""` on the server; pass an explicit `url` for SSR data-loading — see
+* {@link sameOriginUrl}).
+*/
+type ProvideLunoraOptions = Omit<LunoraClientOptions, "url"> & {
+  url?: string;
+};
+/**
+* Wire a {@link LunoraClient} into the application injector. Add the result to the
+* `providers` array of an Angular application config (or any `EnvironmentProviders`
+* consumer):
+*
+* ```ts
+* export const appConfig: ApplicationConfig = {
+*     providers: [provideLunora({ url: "https://api.example.com" })],
+* };
+* ```
+*
+* Pass {@link LunoraClientOptions} to configure a fresh client (URL defaults to
+* the page origin), or hand in an already-constructed {@link LunoraClient} to
+* share one instance (e.g. a client you also preload against during SSR).
+*/
+declare const provideLunora: (optionsOrClient?: LunoraClient | ProvideLunoraOptions) => EnvironmentProviders;
+/**
+* Read the {@link LunoraClient} from the current injector. Call inside an
+* injection context (a component/service field initializer or constructor, or a
+* `runInInjectionContext` callback). Use it to hold the client for imperative
+* calls — e.g. `mutation`/`action` from event handlers, which run outside an
+* injection context:
+*
+* ```ts
+* private readonly client = injectLunoraClient();
+* send = (text: string) => this.client.mutation(api.messages.send, { text });
+* ```
+*/
+declare const injectLunoraClient: () => LunoraClient;
+interface ConnectionStatusOptions {
+  /** Client to observe. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /** `DestroyRef` whose `onDestroy` removes the status listener. Defaults to `inject(DestroyRef)`. */
+  destroyRef?: DestroyRef;
+}
+/**
+* A `signal` of the client's aggregate live-socket status across all shard
+* connections. Reads the current status synchronously and updates on every
+* transition (`idle` → `connecting` → `connected` → `offline`). The Angular
+* equivalent of `@lunora/react`'s `useConnectionStatus`.
+*
+* The listener is removed when the owning `DestroyRef` fires. Call from an
+* injection context (component/service field or constructor).
+*/
+declare const connectionStatus: (options?: ConnectionStatusOptions) => Signal<ConnectionStatus>;
+interface LiveQueryOptions {
+  /**
+  * Client to bind to. Defaults to the injected `LUNORA_CLIENT`; pass one
+  * explicitly to use `liveQuery` outside an injection context (or in a test).
+  */
+  client?: LunoraClient;
+  /**
+  * `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to
+  * `inject(DestroyRef)` — the calling component/service — so it closes when that
+  * component is destroyed. Pass one explicitly to control the lifetime yourself.
+  */
+  destroyRef?: DestroyRef;
+  /**
+  * Called when the subscription errors after the initial attach — the async
+  * error channel `createQuerySubscription` only wires when a sink is present.
+  * Without it, a post-attach failure is dropped silently: the signal simply
+  * stops updating with no error state exposed. Pass a handler to surface it
+  * (log, toast, set an error signal of your own).
+  */
+  onError?: (error: SubscriptionError) => void;
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/**
+* Subscribe to a server query and mirror its value into an Angular `signal`.
+*
+* Reads `undefined` until the first server frame lands, then updates on every
+* delta the WebSocket pushes. The underlying subscription is torn down
+* automatically when the owning `DestroyRef` fires (the component/service is
+* destroyed), so there is no leaked socket subscription.
+*
+* Call it from an injection context (a component/service field initializer or
+* constructor) so the default `inject(DestroyRef)` resolves the caller's
+* lifetime:
+*
+* ```ts
+* export class MessagesComponent {
+*     readonly messages = liveQuery(api.messages.list, { channelId: "general" });
+* }
+* ```
+*
+* Pass `"skip"` (the `SKIP` sentinel from `@lunora/client/query`) as `args` to
+* short-circuit — no network call, no socket; the signal stays `undefined`. To
+* call outside an injection context (e.g. lazily in `ngOnInit`), supply `client`
+* and `destroyRef` via {@link LiveQueryOptions}.
+*/
+declare const liveQuery: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip", options?: LiveQueryOptions) => Signal<ReturnOf<F> | undefined>;
+interface MutateOptions<F extends FunctionReference> extends MutationCallOptions<unknown, unknown, ArgsOf<F>> {
+  /**
+  * Client to run the mutation on. Defaults to the injected `LUNORA_CLIENT`.
+  * Because mutations usually fire from event handlers — which run *outside* an
+  * injection context — capture the client once (`injectLunoraClient()` in a
+  * field) and pass it here, or call `client.mutation(...)` directly.
+  */
+  client?: LunoraClient;
+}
+/**
+* Run a Lunora mutation and resolve with the server result (rejects on failure).
+*
+* Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
+* call options pass straight through to `client.mutation`, which applies and
+* rolls them back against the live subscription cache — the same cache
+* `liveQuery` reads, so an optimistic write reflects immediately and
+* reverts on failure. The client's offline queue also engages when the socket is
+* down, so the write stays durable across reconnects.
+*
+* ```ts
+* private readonly client = injectLunoraClient();
+* send = (text: string) => mutate(api.messages.send, { text }, { client: this.client });
+* ```
+*
+* When called from within an injection context you may omit `client` and let it
+* resolve from the injector.
+*/
+declare const mutate: <F extends FunctionReference>(reference: F, args: ArgsOf<F>, options?: MutateOptions<F>) => Promise<ReturnOf<F>>;
+export { type ConnectionStatusOptions, LUNORA_CLIENT, type LiveQueryOptions, type MutateOptions, type ProvideLunoraOptions, connectionStatus, injectLunoraClient, liveQuery, mutate, provideLunora };

package/dist/index.mjs

@@ -0,0 +1,5 @@
+export { LUNORA_CLIENT, injectLunoraClient, provideLunora } from './packem_shared/LUNORA_CLIENT-DHUfNu9x.mjs';
+export { connectionStatus } from './packem_shared/connectionStatus-BlLodleK.mjs';
+export { liveQuery } from './packem_shared/liveQuery-D5VQBOgf.mjs';
+export { mutate } from './packem_shared/mutate-D3rEHwbb.mjs';
+export { SKIP } from '@lunora/client/query';

package/dist/packem_shared/LUNORA_CLIENT-DHUfNu9x.mjs

@@ -0,0 +1,23 @@
+import { InjectionToken, makeEnvironmentProviders, inject } from '@angular/core';
+import { LunoraClient } from '@lunora/client';
+
+const sameOriginUrl = () => globalThis.location?.origin ?? "";
+const LUNORA_CLIENT = new InjectionToken("lunora.client", {
+  factory: () => new LunoraClient({ url: sameOriginUrl() }),
+  providedIn: "root"
+});
+const provideLunora = (optionsOrClient = {}) => makeEnvironmentProviders([
+  {
+    provide: LUNORA_CLIENT,
+    useFactory: () => {
+      if (optionsOrClient instanceof LunoraClient) {
+        return optionsOrClient;
+      }
+      return new LunoraClient({ ...optionsOrClient, url: optionsOrClient.url ?? sameOriginUrl() });
+    }
+  }
+]);
+const injectLunoraClient = () => inject(LUNORA_CLIENT);
+const resolveLunoraClient = (client) => client ?? injectLunoraClient();
+
+export { LUNORA_CLIENT, injectLunoraClient, provideLunora, resolveLunoraClient };

package/dist/packem_shared/connectionStatus-BlLodleK.mjs

@@ -0,0 +1,15 @@
+import { inject, DestroyRef, signal } from '@angular/core';
+import { resolveLunoraClient } from './LUNORA_CLIENT-DHUfNu9x.mjs';
+
+const connectionStatus = (options = {}) => {
+  const client = resolveLunoraClient(options.client);
+  const destroyRef = options.destroyRef ?? inject(DestroyRef);
+  const status = signal(client.connectionStatus());
+  const unsubscribe = client.onConnectionStatus((next) => {
+    status.set(next);
+  });
+  destroyRef.onDestroy(unsubscribe);
+  return status.asReadonly();
+};
+
+export { connectionStatus };

package/dist/packem_shared/liveQuery-D5VQBOgf.mjs

@@ -0,0 +1,28 @@
+import { inject, DestroyRef, signal } from '@angular/core';
+import { createQuerySubscription } from '@lunora/client/query';
+import { resolveLunoraClient } from './LUNORA_CLIENT-DHUfNu9x.mjs';
+
+const liveQuery = (reference, args, options = {}) => {
+  const client = resolveLunoraClient(options.client);
+  const destroyRef = options.destroyRef ?? inject(DestroyRef);
+  const value = signal(void 0);
+  const unsubscribe = createQuerySubscription(
+    client,
+    reference,
+    args,
+    {
+      onData: (next) => {
+        value.set(next);
+      },
+      onError: options.onError,
+      onReset: () => {
+        value.set(void 0);
+      }
+    },
+    { shardKey: options.shardKey }
+  );
+  destroyRef.onDestroy(unsubscribe);
+  return value.asReadonly();
+};
+
+export { liveQuery };

package/dist/packem_shared/mutate-D3rEHwbb.mjs

@@ -0,0 +1,8 @@
+import { resolveLunoraClient } from './LUNORA_CLIENT-DHUfNu9x.mjs';
+
+const mutate = (reference, args, options = {}) => {
+  const { client, ...callOptions } = options;
+  return resolveLunoraClient(client).mutation(reference, args, callOptions);
+};
+
+export { mutate };

package/package.json

@@ -1,10 +1,61 @@
 {
   "name": "@lunora/angular",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @lunora/angular",
+  "version": "1.0.0-alpha.1",
+  "description": "Angular reactive adapter for Lunora — signal-based live queries and mutations",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "angular",
+    "cloudflare",
+    "durable-objects",
+    "lunora",
+    "realtime",
+    "signals",
+    "workers"
+  ],
+  "homepage": "https://lunora.sh",
+  "bugs": "https://github.com/anolilab/lunora/issues",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anolilab/lunora.git",
+    "directory": "packages/angular"
+  },
+  "files": [
+    "./dist",
+    "README.md",
+    "LICENSE.md",
+    "__assets__"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lunora/client": "1.0.0-alpha.17"
+  },
+  "peerDependencies": {
+    "@angular/core": "^19.2.0 || ^20.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@angular/core": {
+      "optional": false
+    }
+  },
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
+  }
+}