@qlever-llc/trellis-svelte 0.7.0 → 0.8.0-rc.3

package/README.md

@@ -2,12 +2,15 @@
 
 Svelte integration for Trellis browser applications.
 
-Provides `TrellisProvider` for app-level wiring, along with reactive helpers for auth state, NATS connection state, and Trellis client state.
+Provides `TrellisProvider` for app-level wiring and `createTrellisApp(...)` for
+app-scoped typed Svelte context around the real connected Trellis client.
 
 Use `TrellisProvider` as the primary integration surface:
 
-- pass `trellisUrl`, `contract`, and `loginPath`
-- read the live client with `getTrellis<typeof contract>()`
-- use `createAuthState(...)` only for lower-level sign-in flows when needed
+- create an app context with `createTrellisApp({ contract, trellisUrl })`
+- pass `trellisApp` to `TrellisProvider`
+- read the live client synchronously with `app.getTrellis()` from child
+  components
 
-Uses the contract/runtime model from `@qlever-llc/trellis/contracts` and `@qlever-llc/trellis`.
+Uses the contract/runtime model from `@qlever-llc/trellis/contracts` and
+`@qlever-llc/trellis`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qlever-llc/trellis-svelte",
-  "version": "0.7.0",
+  "version": "0.8.0-rc.3",
   "type": "module",
   "description": "Svelte components and state helpers for Trellis browser applications.",
   "license": "Apache-2.0",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@nats-io/nats-core": "^3.3.1",
-    "@qlever-llc/trellis": "^0.7.0",
+    "@qlever-llc/trellis": "^0.8.0-rc.3",
     "typebox": "^1.0.15"
   },
   "peerDependencies": {

package/src/components/TrellisContextProvider.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import {
+    provideConnectedTrellisContext,
+    type TrellisAppOwner,
+    type TrellisContextClient,
+  } from "../context.svelte.ts";
+
+  type Props = {
+    trellisApp: TrellisAppOwner;
+    trellis: TrellisContextClient;
+    children: Snippet;
+  };
+
+  const { trellisApp, trellis, children }: Props = $props();
+
+  function installContext(): void {
+    provideConnectedTrellisContext(trellisApp, trellis);
+  }
+
+  installContext();
+</script>
+
+{@render children()}

package/src/components/TrellisProvider.svelte

@@ -1,229 +1,144 @@
-<script lang="ts">
-  import type { NatsConnection } from "@nats-io/nats-core";
-  import { AsyncResult } from "@qlever-llc/result";
-  import type { Trellis, TrellisAPI } from "../../../trellis/trellis.ts";
-  import { onDestroy } from "svelte";
-  import type { Snippet } from "svelte";
+<script lang="ts" generics="TContract extends TrellisContractLike">
   import {
-    setAuthContext,
-    setNatsStateContext,
-    setTrellisContext,
-  } from "../context.svelte.ts";
-  import { createAuthState, type BindErrorResult } from "../state/auth.svelte.ts";
-  import { createConnectedNatsState, type NatsState } from "../state/nats.svelte.ts";
-  import {
-    type TrellisClientContract,
-  } from "../state/trellis.svelte.ts";
-  import { TrellisClient } from "../../../trellis/client_connect.ts";
-
-  type Props = {
-    children: Snippet;
-    loading?: Snippet;
-    bindError?: Snippet<[BindErrorResult]>;
-    trellisUrl: string;
-    loginPath?: string;
-    contract: TrellisClientContract;
-    onAuthExpired?: () => void;
-    onAuthFailed?: (error: unknown) => void;
-    onAuthRequired?: (redirectTo: string) => void;
-    onBindError?: (result: BindErrorResult) => void;
-    onNatsConnecting?: () => void;
-    onNatsConnected?: () => void;
-    onNatsDisconnect?: () => void;
-    onNatsReconnecting?: () => void;
-    onNatsReconnect?: () => void;
-    onNatsError?: (error: Error) => void;
-  };
-
-  let {
+    ClientAuthHandledError,
+    TrellisClient,
+    type ClientAuthOptions,
+    type ConnectedTrellisClient,
+  } from "@qlever-llc/trellis";
+  import { onMount } from "svelte";
+  import type { TrellisContractLike } from "../context.svelte.ts";
+  import { resolveTrellisAppUrl } from "../context.svelte.ts";
+  import TrellisContextProvider from "./TrellisContextProvider.svelte";
+  import type { TrellisProviderProps } from "./TrellisProvider.types.ts";
+
+  const {
+    trellisApp,
+    auth,
+    client,
     children,
     loading,
-    bindError,
-    trellisUrl,
-    loginPath,
-    contract,
-    onAuthExpired,
-    onAuthFailed,
+    error: errorSnippet,
     onAuthRequired,
-    onBindError,
-    onNatsConnecting,
-    onNatsConnected,
-    onNatsDisconnect,
-    onNatsReconnecting,
-    onNatsReconnect,
-    onNatsError,
-  }: Props = $props();
+  }: TrellisProviderProps<TContract> = $props();
 
-  let bindErrorResult = $state<BindErrorResult | null>(null);
-  let providerAuth = $state<ReturnType<typeof createAuthState> | null>(null);
+  let trellis = $state<ConnectedTrellisClient<TContract> | null>(null);
+  let connectError = $state<unknown>(null);
 
-  function getProviderAuth() {
-    if (providerAuth === null) {
-      providerAuth = createAuthState({ authUrl: trellisUrl, loginPath, contract });
-    }
-
-    providerAuth.setAuthUrl(trellisUrl);
-
-    return providerAuth;
-  }
-
-  type InitContext = {
-    auth: ReturnType<typeof createAuthState>;
-    nats: NatsState;
-    trellis: Trellis<TrellisAPI>;
+  type SerializableTrellisError = {
+    message?: unknown;
+    code?: unknown;
+    hint?: unknown;
+    context?: unknown;
   };
-  const isBrowser = typeof window !== "undefined";
 
-  function requireTrellisUrl(): string {
-    const auth = getProviderAuth();
-    const resolvedTrellisUrl = auth.authUrl;
-    if (!resolvedTrellisUrl) {
-      throw new Error("Trellis URL is not configured");
+  function maybeSerializableError(
+    value: unknown,
+  ): SerializableTrellisError | undefined {
+    if (!value || typeof value !== "object" || !("toSerializable" in value)) {
+      return undefined;
     }
-
-    return resolvedTrellisUrl;
+    const serialize = value.toSerializable;
+    if (typeof serialize !== "function") return undefined;
+    const serialized = serialize.call(value);
+    return serialized && typeof serialized === "object"
+      ? (serialized as SerializableTrellisError)
+      : undefined;
   }
 
-  function getRedirectTo(): string {
-    if (typeof window === "undefined") {
-      return "/";
-    }
-
-    return window.location.pathname + window.location.search;
+  function contextRecord(value: unknown): Record<string, unknown> | undefined {
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined;
   }
 
-  function redirectToLogin(redirectTo: string): void {
-    if (typeof window === "undefined") return;
-
-    const auth = getProviderAuth();
-    const url = new URL(auth.loginPath, window.location.origin);
-    url.searchParams.set("redirectTo", redirectTo);
-    window.location.href = url.toString();
+  function logConnectionError(error: unknown): void {
+    const serialized = maybeSerializableError(error);
+    const context = contextRecord(serialized?.context);
+    const causeMessage =
+      typeof context?.causeMessage === "string"
+        ? context.causeMessage
+        : undefined;
+    const message =
+      typeof serialized?.message === "string"
+        ? serialized.message
+        : error instanceof Error
+          ? error.message
+          : String(error);
+
+    console.error("Error:", error);
   }
 
-  function handleAuthRequired(): void {
-    const redirectTo = getRedirectTo();
-    onAuthRequired?.(redirectTo);
-    if (!onAuthRequired) {
-      redirectToLogin(redirectTo);
-    }
-  }
+  onMount(() => {
+    let active = true;
 
-  async function initialize(): Promise<InitContext | null> {
-    const result = await AsyncResult.try(async () => {
-      const auth = getProviderAuth();
-
-      await auth.init();
-      const bindResult = await auth.handleCallback();
-
-      if (bindResult !== null && bindResult.status !== "bound") {
-        bindErrorResult = bindResult;
-        onBindError?.(bindResult);
-        return null;
-      }
-
-      if (!auth.isAuthenticated) {
-        handleAuthRequired();
-        return null;
+    function withBrowserAuthDefaults(
+      authOptions: ClientAuthOptions | undefined,
+    ): ClientAuthOptions {
+      if (authOptions?.mode === "session_key") {
+        return authOptions;
       }
 
-      const trellis = await TrellisClient.connect({
-        trellisUrl: requireTrellisUrl(),
-        contract,
-        auth: {
-          handle: auth.handle ?? undefined,
-        },
-        onAuthRequired: ({ loginUrl }) => {
-          onAuthExpired?.();
-          const redirectTo = getRedirectTo();
-          onAuthRequired?.(redirectTo);
-          if (!onAuthRequired && typeof window !== "undefined") {
-            window.location.href = loginUrl;
-          }
-        },
-      });
-
-      const natsState = await createConnectedNatsState(trellis.natsConnection, auth, {
-        onConnecting: onNatsConnecting,
-        onConnected: onNatsConnected,
-        onDisconnect: onNatsDisconnect,
-        onReconnecting: onNatsReconnecting,
-        onReconnect: onNatsReconnect,
-        onError: onNatsError,
-        onAuthRequired: () => {
-          onAuthExpired?.();
-          handleAuthRequired();
-        },
-      });
-
       return {
-        auth,
-        nats: natsState,
-        trellis,
+        ...authOptions,
+        currentUrl:
+          authOptions?.currentUrl ?? (() => new URL(window.location.href)),
       };
-    });
-
-    if (result.isErr()) {
-      const error = result.error;
-      getProviderAuth().clearAuth();
-      onAuthFailed?.(error);
-      throw error;
     }
 
-    return result.match({
-      ok: (value) => value,
-      err: (error) => {
-        throw error;
-      },
-    });
-  }
-
-  const initPromise = isBrowser ? initialize() : null;
-  const readyPromise: Promise<InitContext> | null = initPromise?.then((ctx) => {
-    if (!ctx) {
-      throw new Error("Trellis context is not available");
+    const connectAuth = withBrowserAuthDefaults(auth);
+    const trellisUrl = resolveTrellisAppUrl(trellisApp.trellisUrl);
+    if (!trellisUrl) {
+      connectError = new TypeError(
+        "Expected trellisApp to resolve a Trellis URL",
+      );
+      return;
     }
-    return ctx;
-  }) ?? null;
-  const natsStatePromise: Promise<NatsState> | null = readyPromise?.then((ctx) => ctx.nats) ?? null;
-  const trellisPromise: Promise<Trellis<TrellisAPI>> | null = readyPromise?.then((ctx) => ctx.trellis) ?? null;
-  const natsPromise: Promise<NatsConnection> | null = readyPromise?.then((ctx) => ctx.nats.nc) ?? null;
-
-  if (readyPromise && natsStatePromise && trellisPromise && natsPromise) {
-    void readyPromise.catch(() => {});
-    setAuthContext(() => getProviderAuth());
-    setNatsStateContext(natsStatePromise);
-    setTrellisContext({
-      trellis: trellisPromise,
-      nats: natsPromise,
-    });
-  }
 
-  onDestroy(() => {
-    if (!readyPromise) return;
-
-    void readyPromise.then((ctx) => {
-      void ctx.nats.disconnect();
-    });
+    void (async () => {
+      try {
+        const connected = await TrellisClient.connect({
+          ...client,
+          trellisUrl,
+          contract: trellisApp.contract,
+          auth: connectAuth,
+          onAuthRequired: onAuthRequired
+            ? async (ctx) => {
+                await onAuthRequired(ctx.loginUrl, ctx);
+                return { status: "handled" };
+              }
+            : undefined,
+        }).orThrow();
+
+        if (active) {
+          trellis = connected;
+        } else {
+          await connected.connection.close();
+        }
+      } catch (error) {
+        if (!active) return;
+        if (error instanceof ClientAuthHandledError) return;
+        logConnectionError(error);
+        connectError = error;
+      }
+    })();
+
+    return () => {
+      active = false;
+      const connected = trellis;
+      trellis = null;
+      if (connected) {
+        void connected.connection.close();
+      }
+    };
   });
 </script>
 
-{#if !isBrowser}
-  {#if loading}
-    {@render loading()}
+{#if trellis}
+  <TrellisContextProvider {trellisApp} {trellis} {children} />
+{:else if connectError}
+  {#if errorSnippet}
+    {@render errorSnippet(connectError)}
   {/if}
-{:else}
-  {#await initPromise}
-    {#if loading}
-      {@render loading()}
-    {/if}
-  {:then ctx}
-    {#if bindErrorResult}
-      {#if bindError}
-        {@render bindError(bindErrorResult)}
-      {/if}
-    {:else if ctx}
-      {@render children()}
-    {/if}
-  {/await}
+{:else if loading}
+  {@render loading()}
 {/if}

package/src/components/TrellisProvider.types.ts

@@ -0,0 +1,26 @@
+import type {
+  ClientAuthOptions,
+  ClientAuthRequiredContext,
+  ClientOpts,
+} from "@qlever-llc/trellis";
+import type { Snippet } from "svelte";
+import type {
+  TrellisAppOwner,
+  TrellisContractLike,
+} from "../context.svelte.ts";
+
+/** Props accepted by the Svelte Trellis provider component. */
+export type TrellisProviderProps<
+  TContract extends TrellisContractLike = TrellisContractLike,
+> = {
+  trellisApp: TrellisAppOwner<TContract>;
+  auth?: ClientAuthOptions;
+  client?: ClientOpts;
+  children: Snippet;
+  loading?: Snippet;
+  error?: Snippet<[unknown]>;
+  onAuthRequired?: (
+    loginUrl: string,
+    context: ClientAuthRequiredContext,
+  ) => void | Promise<void>;
+};

package/src/context.svelte.ts

@@ -1,50 +1,218 @@
-import type { NatsConnection } from "@nats-io/nats-core";
-import type { TrellisAPI } from "../../trellis/contracts.ts";
+import type {
+  ClientTrellis,
+  RuntimeStateStoresForContract,
+  TrellisAPI,
+  TrellisConnection,
+  TrellisConnectionStatus,
+  TrellisContractV1,
+} from "@qlever-llc/trellis";
 import { createContext } from "svelte";
-import type { AuthState } from "./state/auth.svelte.ts";
-import type { NatsState } from "./state/nats.svelte.ts";
-
-type TrellisContext = {
-  trellis: Promise<unknown>;
-  nats: Promise<NatsConnection>;
-};
+import { createSubscriber } from "svelte/reactivity";
 
+/** Minimal contract shape required to create a typed Trellis Svelte app context. */
 export type TrellisContractLike<TA extends TrellisAPI = TrellisAPI> = {
+  CONTRACT: TrellisContractV1;
+  CONTRACT_DIGEST: string;
   API: {
     trellis: TA;
   };
 };
 
-const [getTrellisContext, setTrellisContextValue] = createContext<TrellisContext>();
-const [getNatsStateContext, setNatsStateContextValue] = createContext<Promise<NatsState>>();
-const [getAuthContext, setAuthContextValue] = createContext<() => AuthState>();
+/** Real connected Trellis client type exposed by a Svelte app context. */
+export type TrellisClientFor<TContract extends TrellisContractLike> =
+  ClientTrellis<
+    TContract["API"]["trellis"],
+    RuntimeStateStoresForContract<TContract>
+  >;
 
-export function setTrellisContext(
-  ctx: TrellisContext,
-): void {
-  setTrellisContextValue(ctx);
+/** Minimal client surface required for Trellis Svelte context clients. */
+export type TrellisContextClient = {
+  readonly connection: TrellisConnection;
+};
+
+/** URL value accepted by a Trellis Svelte app owner. */
+export type TrellisAppUrl = string | URL;
+
+/**
+ * Trellis URL configuration for a Svelte app owner.
+ *
+ * A function resolver supports apps whose Trellis instance is selected at
+ * runtime. Returning `undefined` means no instance is currently available.
+ */
+export type TrellisAppUrlResolver =
+  | TrellisAppUrl
+  | (() => TrellisAppUrl | undefined);
+
+/** Options used to create a Trellis Svelte app owner. */
+export type CreateTrellisAppOptions<
+  TContract extends TrellisContractLike = TrellisContractLike,
+> = {
+  /** Contract used by this app context and by `TrellisProvider` connections. */
+  contract: TContract;
+
+  /** Trellis URL, or a resolver for runtime-selected Trellis URLs. */
+  trellisUrl: TrellisAppUrlResolver;
+};
+
+/** Resolves a Trellis app URL config to the string shape required by the client. */
+export function resolveTrellisAppUrl(
+  trellisUrl: TrellisAppUrlResolver,
+): string | undefined {
+  const resolved = typeof trellisUrl === "function" ? trellisUrl() : trellisUrl;
+  return resolved?.toString();
 }
 
-export function setNatsStateContext(natsState: Promise<NatsState>): void {
-  setNatsStateContextValue(natsState);
+/** Svelte-reactive adapter around a framework-neutral Trellis connection. */
+export class SvelteTrellisConnection {
+  #connection: TrellisConnection;
+  #subscribe: () => void;
+
+  /** Creates a reactive connection adapter for a connected Trellis runtime. */
+  constructor(connection: TrellisConnection) {
+    this.#connection = connection;
+    this.#subscribe = createSubscriber((update) => {
+      return this.#connection.subscribe(() => update());
+    });
+  }
+
+  /** Latest connection status, reactive when read by Svelte effects or markup. */
+  get status(): TrellisConnectionStatus {
+    this.#subscribe();
+    return this.#connection.status;
+  }
+
+  /** Closes the underlying Trellis runtime connection. */
+  close(): Promise<void> {
+    return this.#connection.close();
+  }
 }
 
-export function setAuthContext(getAuth: () => AuthState): void {
-  setAuthContextValue(getAuth);
+type TrellisAppContext<TClient extends TrellisContextClient> = {
+  trellis: TClient;
+  connection: SvelteTrellisConnection;
+};
+
+const provideTrellisContext = Symbol("provideTrellisContext");
+const trellisAppOwnerBrand: unique symbol = Symbol("trellisAppOwner");
+
+/** Minimal branded app owner surface accepted by the Trellis Svelte provider. */
+export type TrellisAppOwner<
+  TContract extends TrellisContractLike = TrellisContractLike,
+> = {
+  readonly contract: TContract;
+  readonly trellisUrl: TrellisAppUrlResolver;
+  readonly [trellisAppOwnerBrand]: true;
+};
+
+/**
+ * Public app-scoped typed Svelte context owner for a Trellis browser app.
+ *
+ * `TClient` is a type-only facade over the runtime client that `TrellisProvider`
+ * installs. Use it with generated client facade types for the same contract.
+ */
+export interface TrellisApp<
+  TContract extends TrellisContractLike = TrellisContractLike,
+  TClient extends TrellisContextClient = TrellisClientFor<TContract>,
+> extends TrellisAppOwner<TContract> {
+  /** Contract used by this app context and by `TrellisProvider` connections. */
+  readonly contract: TContract;
+
+  /** Trellis URL configuration used by `TrellisProvider` connections. */
+  readonly trellisUrl: TrellisAppUrlResolver;
+
+  /** Returns the contract-typed connected Trellis client from Svelte context synchronously. */
+  getTrellis(): TClient;
+
+  /** Returns a Svelte-reactive adapter for the real Trellis connection. */
+  getConnection(): SvelteTrellisConnection;
 }
 
-export function getTrellis<T = unknown>(): Promise<T> {
-  return getTrellisContext().trellis as Promise<T>;
+/** Internal app-scoped typed Svelte context implementation. */
+class TrellisAppImpl<
+  TContract extends TrellisContractLike = TrellisContractLike,
+  TClient extends TrellisContextClient = TrellisClientFor<TContract>,
+> {
+  readonly [trellisAppOwnerBrand] = true as const;
+  readonly #contract: TContract;
+  readonly #trellisUrl: TrellisAppUrlResolver;
+  readonly #getContext: () => TrellisAppContext<TClient>;
+  readonly #setContext: (
+    context: TrellisAppContext<TClient>,
+  ) => TrellisAppContext<TClient>;
+
+  /** Creates an app-scoped context owner for a specific Trellis contract. */
+  constructor(options: CreateTrellisAppOptions<TContract>) {
+    const { contract, trellisUrl } = options;
+    this.#contract = contract;
+    this.#trellisUrl = trellisUrl;
+    const [getContext, setContext] = createContext<
+      TrellisAppContext<TClient>
+    >();
+    this.#getContext = getContext;
+    this.#setContext = setContext;
+  }
+
+  /** Contract used by this app context and by `TrellisProvider` connections. */
+  get contract(): TContract {
+    return this.#contract;
+  }
+
+  /** Trellis URL configuration used by `TrellisProvider` connections. */
+  get trellisUrl(): TrellisAppUrlResolver {
+    return this.#trellisUrl;
+  }
+
+  /** Returns the contract-typed connected Trellis client from Svelte context synchronously. */
+  getTrellis(): TClient {
+    return this.#getContext().trellis;
+  }
+
+  /** Returns a Svelte-reactive adapter for the real Trellis connection. */
+  getConnection(): SvelteTrellisConnection {
+    return this.#getContext().connection;
+  }
+
+  /** Installs the connected Trellis runtime into Svelte context synchronously. */
+  [provideTrellisContext](trellis: TrellisContextClient): void {
+    this.#setContext({
+      trellis: trellis as TClient,
+      connection: new SvelteTrellisConnection(trellis.connection),
+    });
+  }
 }
 
-export function getNats(): Promise<NatsConnection> {
-  return getTrellisContext().nats;
+/**
+ * Creates an app-scoped typed Svelte context owner for a Trellis contract and URL.
+ *
+ * The optional `TClient` type parameter is a type-only facade over the connected
+ * runtime client. It should be a generated client facade for `options.contract`.
+ */
+export function createTrellisApp<
+  TContract extends TrellisContractLike,
+  TClient extends TrellisContextClient = TrellisClientFor<TContract>,
+>(
+  options: CreateTrellisAppOptions<TContract>,
+): TrellisApp<TContract, TClient> {
+  return new TrellisAppImpl<TContract, TClient>(options);
 }
 
-export function getNatsState(): Promise<NatsState> {
-  return getNatsStateContext();
+function isTrellisAppImpl(
+  app: TrellisAppOwner,
+): app is TrellisAppImpl<TrellisContractLike> {
+  return app instanceof TrellisAppImpl;
 }
 
-export function getAuth(): AuthState {
-  return getAuthContext()();
+/**
+ * Internal provider helper that synchronously installs connected Trellis context.
+ *
+ * This is intentionally not exported from `src/index.ts`.
+ */
+export function provideConnectedTrellisContext(
+  app: TrellisAppOwner,
+  trellis: TrellisContextClient,
+): void {
+  if (!isTrellisAppImpl(app)) {
+    throw new TypeError("Expected an app created by createTrellisApp");
+  }
+  app[provideTrellisContext](trellis);
 }