@hops-ops/distributed 0.0.0

package/dist/request.js

@@ -0,0 +1,123 @@
+/** Isomorphic HTTP GraphQL request helper with injectable URL and authentication. */
+import { buildAuthHeaders } from './auth-headers.js';
+import { documentToString } from './document.js';
+import { DistributedProtocolError, parseGraphqlResponseExtensions } from './protocol.js';
+async function readResponseBody(response) {
+    let rawText;
+    if (typeof response.text === 'function') {
+        try {
+            rawText = await response.text();
+        }
+        catch {
+            // A fetch-compatible test double may only implement json().
+        }
+    }
+    if (rawText !== undefined) {
+        try {
+            return { body: asResponseBody(JSON.parse(rawText)) };
+        }
+        catch {
+            return { body: {}, rawText };
+        }
+    }
+    try {
+        return { body: asResponseBody(await response.json()) };
+    }
+    catch {
+        return { body: {} };
+    }
+}
+function asResponseBody(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function httpFailureMessage(response, body, rawText) {
+    const jsonDetail = typeof body.error === 'string' ? body.error.trim() : '';
+    if (jsonDetail)
+        return jsonDetail;
+    const statusText = response.statusText?.trim();
+    const status = `HTTP ${response.status}${statusText ? ` ${statusText}` : ''}`;
+    const textDetail = rawText?.trim() ?? '';
+    if (!textDetail ||
+        /^<(?:!doctype\s+html|html|head|body)(?:\s|>)/i.test(textDetail)) {
+        return status;
+    }
+    const maxDetailLength = 500;
+    const boundedDetail = textDetail.length > maxDetailLength
+        ? `${textDetail.slice(0, maxDetailLength - 1)}…`
+        : textDetail;
+    return `${status}: ${boundedDetail}`;
+}
+/** POST a GraphQL document to `url`. */
+export async function requestGraphql(url, document, auth = {}, variables = {}, options = {}) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('requestGraphql requires a fetch implementation in this runtime; pass { fetch } as the final argument');
+    }
+    const token = auth.accessToken?.trim() ?? '';
+    const response = await fetchImpl(url, {
+        method: 'POST',
+        headers: buildAuthHeaders(auth),
+        body: JSON.stringify({
+            query: documentToString(document),
+            variables,
+            ...(options.extensions === undefined
+                ? {}
+                : { extensions: options.extensions })
+        }),
+        ...(options.signal === undefined ? {} : { signal: options.signal })
+    });
+    const { body, rawText } = await readResponseBody(response);
+    let extensions;
+    try {
+        extensions = parseGraphqlResponseExtensions(body.extensions);
+    }
+    catch (error) {
+        if (error instanceof DistributedProtocolError) {
+            return {
+                data: undefined,
+                errors: [
+                    ...(body.errors ?? []),
+                    {
+                        message: error.message,
+                        extensions: { code: error.code }
+                    }
+                ],
+                status: response.status
+            };
+        }
+        throw error;
+    }
+    if (response.status === 401) {
+        const detail = body.errors?.[0]?.message ??
+            body.error ??
+            (token
+                ? 'Bearer rejected (audience/issuer/expiry) — sign out and back in'
+                : 'no access token — re-login; check OIDC scopes include the project audience');
+        return {
+            data: body.data,
+            errors: [{ message: detail }],
+            ...(extensions === undefined ? {} : { extensions }),
+            status: response.status
+        };
+    }
+    if (response.status >= 400 &&
+        response.status < 600 &&
+        !body.errors?.length) {
+        return {
+            data: body.data,
+            errors: [{ message: httpFailureMessage(response, body, rawText) }],
+            ...(extensions === undefined ? {} : { extensions }),
+            status: response.status
+        };
+    }
+    return {
+        data: body.data,
+        errors: body.errors,
+        ...(extensions === undefined ? {} : { extensions }),
+        status: response.status
+    };
+}
+export { documentToString } from './document.js';
+export { buildAuthHeaders } from './auth-headers.js';

package/dist/sveltekit/auth.d.ts

@@ -0,0 +1,18 @@
+import type { GqlAuth } from '../types.js';
+/** Minimal page-data shape needed to bind browser GraphQL authentication. */
+export type PageGraphqlData = {
+    accessToken?: string | null;
+    session?: {
+        accessToken?: string | null;
+        user?: {
+            id?: string | null;
+            name?: string | null;
+            email?: string | null;
+            username?: string | null;
+            groups?: string[];
+        } | null;
+    } | null;
+    engineRole?: string | null;
+};
+/** Map SSR/page data into GraphQL auth (Bearer preferred; DevHeaders for local development). */
+export declare function authFromPageData(data: PageGraphqlData): GqlAuth;

package/dist/sveltekit/auth.js

@@ -0,0 +1,9 @@
+/** Map SSR/page data into GraphQL auth (Bearer preferred; DevHeaders for local development). */
+export function authFromPageData(data) {
+    const accessToken = data.accessToken ?? data.session?.accessToken ?? null;
+    return {
+        accessToken,
+        userId: accessToken ? undefined : (data.session?.user?.id ?? undefined),
+        role: data.engineRole ?? undefined
+    };
+}

package/dist/sveltekit/context.d.ts

@@ -0,0 +1,28 @@
+import type { ReplicaOperationArtifact } from '../replica/index.js';
+import type { GraphqlVariables } from '../types.js';
+import type { DistributedSvelteKitClient, SveltekitBoundOperation } from './replica.js';
+/**
+ * Install one client in the current Svelte component tree.
+ *
+ * The context key is module-global, but the client value is not: Svelte owns
+ * it per component tree/request. A nested elevated layout may deliberately
+ * replace the nearest user-safe client.
+ */
+export declare function provideDistributedSvelteKitClient<TCommands>(client: DistributedSvelteKitClient<TCommands>): DistributedSvelteKitClient<TCommands>;
+/**
+ * Resolve the nearest client during component initialization.
+ *
+ * This intentionally calls Svelte `getContext` each time. Generated modules
+ * may contain static operation wrappers, but never capture a client or command
+ * tree at module evaluation time.
+ */
+export declare function useDistributedSvelteKitClient<TCommands = Readonly<Record<never, never>>>(): DistributedSvelteKitClient<TCommands>;
+/** Resolve the nearest generated command surface without a global proxy. */
+export declare function useDistributedSvelteKitCommands<TCommands>(): TCommands;
+/**
+ * Define one SSR-safe generated operation wrapper.
+ *
+ * The wrapper stores only immutable compiler output. `use()` and `read()`
+ * resolve the nearest tree-local client when the component calls them.
+ */
+export declare function defineDistributedSvelteKitOperation<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>): SveltekitBoundOperation<TData, TVariables>;

package/dist/sveltekit/context.js

@@ -0,0 +1,58 @@
+import { getContext, setContext } from 'svelte';
+const DISTRIBUTED_CLIENT_CONTEXT = Symbol('@hops-ops/distributed/sveltekit/client');
+/**
+ * Install one client in the current Svelte component tree.
+ *
+ * The context key is module-global, but the client value is not: Svelte owns
+ * it per component tree/request. A nested elevated layout may deliberately
+ * replace the nearest user-safe client.
+ */
+export function provideDistributedSvelteKitClient(client) {
+    if (client === null ||
+        typeof client !== 'object' ||
+        typeof client.operation !== 'function') {
+        throw new TypeError('provideDistributedSvelteKitClient requires a Distributed SvelteKit client');
+    }
+    setContext(DISTRIBUTED_CLIENT_CONTEXT, client);
+    return client;
+}
+/**
+ * Resolve the nearest client during component initialization.
+ *
+ * This intentionally calls Svelte `getContext` each time. Generated modules
+ * may contain static operation wrappers, but never capture a client or command
+ * tree at module evaluation time.
+ */
+export function useDistributedSvelteKitClient() {
+    const client = getContext(DISTRIBUTED_CLIENT_CONTEXT);
+    if (client === undefined) {
+        throw new Error('Distributed client is missing from the active Svelte component tree; call generated provideDistributed(...) in a parent layout');
+    }
+    return client;
+}
+/** Resolve the nearest generated command surface without a global proxy. */
+export function useDistributedSvelteKitCommands() {
+    return useDistributedSvelteKitClient().commands;
+}
+/**
+ * Define one SSR-safe generated operation wrapper.
+ *
+ * The wrapper stores only immutable compiler output. `use()` and `read()`
+ * resolve the nearest tree-local client when the component calls them.
+ */
+export function defineDistributedSvelteKitOperation(artifact) {
+    const use = ((...args) => {
+        const operation = useDistributedSvelteKitClient().operation(artifact);
+        const invoke = operation.use;
+        return invoke(...args);
+    });
+    return Object.freeze({
+        artifact,
+        use,
+        read(variables) {
+            return useDistributedSvelteKitClient()
+                .operation(artifact)
+                .read(variables);
+        }
+    });
+}

package/dist/sveltekit/index.d.ts

@@ -0,0 +1,4 @@
+export { authFromPageData, type PageGraphqlData } from './auth.js';
+export { defineDistributedSvelteKitOperation, provideDistributedSvelteKitClient, useDistributedSvelteKitClient, useDistributedSvelteKitCommands } from './context.js';
+export { bindSveltekitOperation, createPageDataSessionSource, createDistributedSvelteKit, sessionSourceFromPageData, type CreateDistributedSvelteKitOptions, type DistributedSvelteKitClient, type SveltekitBoundOperation, type SveltekitCommandRuntimeFactory, type SveltekitCommandRuntimeFactoryOptions, type SveltekitCommandRuntimeLike, type SveltekitDistributedPageData, type SveltekitPageDataSessionSource, type SveltekitPageDataSource, type SveltekitQuerySnapshot, type SveltekitQueryStore, type SveltekitReplicaAuthority, type SveltekitReplicaHydration, type SveltekitSessionSource, type UseSveltekitOperationOptions } from './replica.js';
+export { createDistributedSvelteKitServer, registerDistributedRoute, type CreateDistributedSvelteKitServerOptions, type DistributedRouteOperation, type DistributedRoutePlan, type DistributedRouteVariables, type DistributedSvelteKitServer, type SveltekitServerLoadEventLike } from './server-replica.js';

package/dist/sveltekit/index.js

@@ -0,0 +1,4 @@
+export { authFromPageData } from './auth.js';
+export { defineDistributedSvelteKitOperation, provideDistributedSvelteKitClient, useDistributedSvelteKitClient, useDistributedSvelteKitCommands } from './context.js';
+export { bindSveltekitOperation, createPageDataSessionSource, createDistributedSvelteKit, sessionSourceFromPageData } from './replica.js';
+export { createDistributedSvelteKitServer, registerDistributedRoute } from './server-replica.js';

package/dist/sveltekit/replica.d.ts

@@ -0,0 +1,145 @@
+import { type DistributedReplica, type DistributedReplicaOptions, type ReplicaAuthoritativeScope, type ReplicaCommandReceipt, type ReplicaCommandRuntime, type ReplicaCommandRuntimeOptions, type ReplicaGraphqlTransport, type ReplicaOperationArtifact, type ReplicaSnapshot } from '../replica/index.js';
+import type { GqlAuth, GqlError, GraphqlVariables } from '../types.js';
+import type { WebSocketConstructor } from '../websocket.js';
+import type { FetchLike } from '../request.js';
+import { type PageGraphqlData } from './auth.js';
+type UnknownCommandEntries = Readonly<Record<string, never>>;
+export type SveltekitSessionSource = Readonly<{
+    /** Current credential. HTTP, WS, and commands all call this exact source. */
+    getAuth(): GqlAuth | Promise<GqlAuth>;
+    /**
+     * Notify on token, logout, role, tenant, or session changes.
+     *
+     * The adapter re-reads `getAuth`; callers never label a cache scope.
+     */
+    subscribe?(listener: () => void): () => void;
+}>;
+export type SveltekitPageDataSource<TData extends PageGraphqlData> = Readonly<{
+    get(): TData;
+    subscribe?(listener: () => void): () => void;
+}>;
+export type SveltekitPageDataSessionSource<TData extends PageGraphqlData> = Readonly<{
+    session: SveltekitSessionSource;
+    get(): TData;
+    set(next: TData): void;
+}>;
+export type SveltekitReplicaHydration = Readonly<{
+    version: 1;
+    state: import('../replica/index.js').ReplicaDehydratedState;
+    readonly operations?: readonly string[];
+}>;
+/**
+ * Independently trusted SSR/session authority for one hydration transfer.
+ *
+ * Do not persist this beside replica state. State never authorizes its own
+ * scope; the adapter compares its embedded scope to this server-owned value.
+ */
+export type SveltekitReplicaAuthority = Readonly<{
+    version: 1;
+    scope: ReplicaAuthoritativeScope;
+}>;
+export type SveltekitDistributedPageData = PageGraphqlData & Readonly<{
+    distributed?: SveltekitReplicaHydration;
+    distributedAuthority?: SveltekitReplicaAuthority;
+}>;
+export type SveltekitCommandRuntimeLike<TCommands> = Pick<ReplicaCommandRuntime<UnknownCommandEntries>, 'dispose'> & Readonly<{
+    commands: TCommands;
+}>;
+export type SveltekitCommandRuntimeFactory<TCommands> = (replica: DistributedReplica, transport: ReplicaGraphqlTransport, options: SveltekitCommandRuntimeFactoryOptions) => SveltekitCommandRuntimeLike<TCommands>;
+export type SveltekitCommandRuntimeFactoryOptions = Pick<ReplicaCommandRuntimeOptions, 'diagnostics'>;
+export type CreateDistributedSvelteKitOptions<TCommands = Readonly<Record<never, never>>> = Readonly<{
+    session: SveltekitSessionSource;
+    /** Same-origin `/graphql` by default. */
+    url?: string | (() => string);
+    fetch?: FetchLike;
+    webSocket?: WebSocketConstructor;
+    /**
+     * Set to SvelteKit's `$app/environment` `browser` flag. When false,
+     * store subscriptions remain side-effect-free during component SSR.
+     */
+    browser?: boolean;
+    hydration?: SveltekitReplicaHydration;
+    /** Required with `hydration`; must come from current trusted SSR page data. */
+    authority?: SveltekitReplicaAuthority;
+    createCommands?: SveltekitCommandRuntimeFactory<TCommands>;
+    replica?: Omit<DistributedReplicaOptions, 'transport'>;
+    onAuthError?: (error: unknown) => void;
+}>;
+export type SveltekitQuerySnapshot<TData> = ReplicaSnapshot<TData> & Readonly<{
+    loading: boolean;
+    error?: GqlError;
+    /** Causally accepted commands still waiting for projection visibility. */
+    pending: readonly ReplicaCommandReceipt<unknown>[];
+    refetch(): Promise<void>;
+}>;
+export interface SveltekitQueryStore<TData> {
+    /** Current value for imperative code and adapter conformance. */
+    get(): SveltekitQuerySnapshot<TData>;
+    /** Svelte-readable store contract; use `$query` in a component. */
+    subscribe(listener: (snapshot: SveltekitQuerySnapshot<TData>) => void): () => void;
+    refetch(): Promise<void>;
+    destroy(): void;
+    readonly data: ReplicaSnapshot<TData>['data'];
+    readonly status: ReplicaSnapshot<TData>['status'];
+    readonly complete: boolean;
+    readonly loading: boolean;
+    readonly fetching: boolean;
+    readonly stale: boolean;
+    readonly live: ReplicaSnapshot<TData>['live'];
+    readonly errors: readonly GqlError[];
+    readonly error: GqlError | undefined;
+    readonly pending: readonly ReplicaCommandReceipt<unknown>[];
+}
+export type UseSveltekitOperationOptions = Readonly<{
+    /** Defaults to true when the compiler emitted a live companion. */
+    live?: boolean;
+}>;
+type UseOperationArguments<TVariables extends GraphqlVariables> = Record<string, never> extends TVariables ? [] | [variables: TVariables] | [
+    variables: TVariables,
+    options: UseSveltekitOperationOptions
+] : [
+    variables: TVariables,
+    options?: UseSveltekitOperationOptions
+];
+export type SveltekitBoundOperation<TData, TVariables extends GraphqlVariables> = Readonly<{
+    artifact: ReplicaOperationArtifact<TData, TVariables>;
+    use(...args: UseOperationArguments<TVariables>): SveltekitQueryStore<TData>;
+    read(variables: TVariables): ReplicaSnapshot<TData>;
+}>;
+export type DistributedSvelteKitClient<TCommands> = Readonly<{
+    replica: DistributedReplica;
+    transport: ReplicaGraphqlTransport;
+    commands: TCommands;
+    operation<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>): SveltekitBoundOperation<TData, TVariables>;
+    /**
+     * Apply a server seed. A malformed or mismatched seed closes the old
+     * generation and returns false so the bound operation refetches.
+     */
+    hydrate(hydration: SveltekitReplicaHydration, authority: SveltekitReplicaAuthority): boolean;
+    invalidateAuthorization(): void;
+    destroy(): void;
+}>;
+/**
+ * Bind the framework-neutral replica to Svelte's readable-store lifecycle.
+ *
+ * Generated `$distributed` modules call this once, then export
+ * `client.operation(Operation_Todos)` and `client.commands`.
+ */
+export declare function createDistributedSvelteKit<TCommands = Readonly<Record<never, never>>>(options: CreateDistributedSvelteKitOptions<TCommands>): DistributedSvelteKitClient<TCommands>;
+/**
+ * Low-level composition seam for applications that already own a replica.
+ *
+ * Most SvelteKit applications use `createDistributedSvelteKit().operation()`;
+ * this form exists for custom composition and framework adapter conformance.
+ */
+export declare function bindSveltekitOperation<TData, TVariables extends GraphqlVariables>(replica: DistributedReplica, artifact: ReplicaOperationArtifact<TData, TVariables>): SveltekitBoundOperation<TData, TVariables>;
+/** Map SvelteKit page data into the one shared transport/session source. */
+export declare function sessionSourceFromPageData<TData extends PageGraphqlData>(source: SveltekitPageDataSource<TData>): SveltekitSessionSource;
+/**
+ * Create the single mutable page-data/session source owned by one layout.
+ *
+ * HTTP, WebSocket reconnects, commands, and authorization invalidation all
+ * observe `session`; navigation updates the same source through `set`.
+ */
+export declare function createPageDataSessionSource<TData extends PageGraphqlData>(initial: TData): SveltekitPageDataSessionSource<TData>;
+export {};