universal-api-layer 0.7.0

package/dist/types-CVzD7l4p.d.ts

@@ -0,0 +1,81 @@
+import { f as ApiError, e as ApiClient, h as ResponseSchema } from './client-ByBlZaRg.js';
+
+type SocketData = string | ArrayBuffer | Blob;
+type SocketSendData = string | ArrayBuffer | Blob | ArrayBufferView<ArrayBuffer>;
+interface SocketEvents {
+    open: {
+        readonly type: string;
+    };
+    error: {
+        readonly type: string;
+    };
+    message: {
+        readonly type: string;
+        readonly data: unknown;
+    };
+    close: {
+        readonly type: string;
+        readonly code: number;
+        readonly reason: string;
+        readonly wasClean: boolean;
+    };
+}
+/** Structural native WebSocket interface, also injectable in tests/non-browser runtimes. */
+interface SocketTransport {
+    readonly readyState: number;
+    readonly bufferedAmount: number;
+    binaryType: "blob" | "arraybuffer";
+    send(data: SocketSendData): void;
+    close(code?: number, reason?: string): void;
+    addEventListener<K extends keyof SocketEvents>(type: K, listener: (event: SocketEvents[K]) => void): void;
+    removeEventListener<K extends keyof SocketEvents>(type: K, listener: (event: SocketEvents[K]) => void): void;
+}
+interface SocketSnapshot {
+    readonly status: "idle" | "connecting" | "open" | "reconnecting" | "closed" | "disposed";
+    /** Retries used since the latest explicit connect(), including across short-lived opens. */
+    readonly reconnectAttempt: number;
+    readonly error: ApiError | null;
+    readonly close: Readonly<{
+        code: number;
+        reason: string;
+        wasClean: boolean;
+    }> | null;
+}
+interface SocketOptions<T> {
+    /** Absolute ws(s) URL, or an abortable provider for short-lived connection tickets. */
+    url: string | ((signal: AbortSignal) => string | Promise<string>);
+    /** Required for a URL provider. Exact ws(s) origins, not URL prefixes. */
+    allowedOrigins?: readonly string[];
+    protocols?: readonly string[];
+    sessionClient?: Pick<ApiClient, "getSessionSnapshot" | "subscribeSession">;
+    /** Defaults to true when sessionClient is provided. */
+    requiresAuth?: boolean;
+    /** json (default) parses text JSON; raw preserves native string/ArrayBuffer/Blob data. */
+    format?: "json" | "raw";
+    schema?: ResponseSchema<T>;
+    reconnect?: false | {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        jitter?: boolean;
+    };
+    connectTimeoutMs?: number;
+    maxMessageSize?: number;
+    maxPendingMessages?: number;
+    maxBufferedAmount?: number;
+    webSocketFactory?: (url: string, protocols: string[]) => SocketTransport;
+}
+interface SocketClient<T = unknown> {
+    connect(): void;
+    disconnect(code?: number, reason?: string): void;
+    dispose(): void;
+    /** Sends only while OPEN and under the buffer limit; never queues or replays. */
+    send(data: SocketSendData): void;
+    sendJson(value: unknown): void;
+    getSnapshot(): SocketSnapshot;
+    subscribe(listener: () => void): () => void;
+    onMessage(listener: (message: T) => void): () => void;
+    onError(listener: (error: ApiError) => void): () => void;
+}
+
+export type { SocketClient as S, SocketSnapshot as a, SocketOptions as b, SocketData as c, SocketEvents as d, SocketSendData as e, SocketTransport as f };

package/dist/vue/index.d.ts

@@ -0,0 +1,23 @@
+import * as vue from 'vue';
+import { MaybeRefOrGetter, Plugin } from 'vue';
+import { QueryConfig, ApiClient, MutationConfig, ApiError, SessionSnapshot } from '../core/index.js';
+import { QueryClient, UseMutationReturnType, UseQueryReturnType } from '@tanstack/vue-query';
+
+declare function createApiPlugin({ client, queryClient, }: {
+    client: ApiClient;
+    queryClient?: QueryClient;
+}): Plugin;
+declare function useApiClient(): ApiClient;
+declare function useApiSession(): vue.ComputedRef<SessionSnapshot>;
+type VueQueryConfig<T, S = T | null> = Omit<QueryConfig<T, S>, "key" | "url" | "params" | "enabled" | "cacheScope"> & {
+    key: MaybeRefOrGetter<readonly unknown[]>;
+    url: MaybeRefOrGetter<string>;
+    params?: MaybeRefOrGetter<QueryConfig<T, S>["params"]>;
+    enabled?: MaybeRefOrGetter<boolean>;
+    cacheScope?: MaybeRefOrGetter<string>;
+};
+declare function useApiQuery<T = unknown, S = T | null>(config: VueQueryConfig<T, S>): UseQueryReturnType<S, ApiError>;
+declare function useApiMutation<T = unknown, V = unknown, S = T | null>(config: MutationConfig<T, V, S>): UseMutationReturnType<S, ApiError, V, unknown>;
+
+export { createApiPlugin, useApiClient, useApiMutation, useApiQuery, useApiSession };
+export type { VueQueryConfig };

package/dist/vue/index.js

@@ -0,0 +1,257 @@
+import {
+  defaultQueryRetry,
+  queryIdentity,
+  runMutation
+} from "../chunk-HDW7BOZI.js";
+import {
+  invokeAsyncCallback,
+  invokeCallback
+} from "../chunk-DXYWZQW5.js";
+import "../chunk-YTM3FV65.js";
+
+// src/vue/index.ts
+import {
+  computed,
+  inject,
+  onScopeDispose,
+  shallowRef,
+  toValue
+} from "vue";
+import {
+  QueryClient,
+  VueQueryPlugin,
+  useQuery,
+  useMutation,
+  useQueryClient
+} from "@tanstack/vue-query";
+var clientKey = /* @__PURE__ */ Symbol("universal-api-layer");
+function clearClientCache(client, cache, staleOnly = false) {
+  const current = client.getSessionSnapshot();
+  const predicate = (query) => {
+    if (!client.ownsQuery(query.queryKey)) return false;
+    if (!staleOnly) return true;
+    const snapshot = query.queryKey.at(-1).session;
+    return !snapshot || snapshot.revision !== current.revision || snapshot.userId !== current.userId || snapshot.tenantId !== current.tenantId;
+  };
+  void cache.cancelQueries({ predicate }).catch(() => {
+  });
+  cache.removeQueries({ predicate });
+  for (const mutation of cache.getMutationCache().getAll()) {
+    const variables = mutation.state.variables;
+    const revision = variables && typeof variables === "object" && "revision" in variables ? variables.revision : void 0;
+    if (mutation.options.meta?.universalApiLayer === client.cacheScope && (!staleOnly || revision !== current.revision))
+      cache.getMutationCache().remove(mutation);
+  }
+}
+var cacheBindings = /* @__PURE__ */ new WeakMap();
+function bindCache(client, cache) {
+  let caches = cacheBindings.get(client);
+  if (!caches) {
+    caches = /* @__PURE__ */ new WeakMap();
+    cacheBindings.set(client, caches);
+  }
+  let binding = caches.get(cache);
+  if (!binding) {
+    clearClientCache(client, cache, true);
+    binding = {
+      count: 0,
+      unsubscribe: client.subscribeSession(
+        () => clearClientCache(client, cache)
+      )
+    };
+    caches.set(cache, binding);
+  }
+  binding.count++;
+  const current = binding;
+  return () => {
+    current.count--;
+    if (current.count === 0) {
+      current.unsubscribe();
+      clearClientCache(client, cache);
+      caches.delete(cache);
+    }
+  };
+}
+function createApiPlugin({
+  client,
+  queryClient
+}) {
+  return {
+    install(app) {
+      const cache = queryClient ?? new QueryClient();
+      app.provide(clientKey, client);
+      app.use(VueQueryPlugin, { queryClient: cache });
+      const unsubscribe = bindCache(client, cache);
+      const unmount = app.unmount.bind(app);
+      app.unmount = () => {
+        unsubscribe();
+        unmount();
+      };
+    }
+  };
+}
+function useApiClient() {
+  const client = inject(clientKey);
+  if (!client)
+    throw new Error("Install createApiPlugin before using API composables");
+  return client;
+}
+function useSession(client) {
+  const snapshot = shallowRef(client.getSessionSnapshot());
+  const unsubscribe = client.subscribeSession(() => {
+    snapshot.value = client.getSessionSnapshot();
+  });
+  onScopeDispose(unsubscribe);
+  return computed(() => snapshot.value);
+}
+function useApiSession() {
+  return useSession(useApiClient());
+}
+function useApiQuery(config) {
+  const client = useApiClient();
+  const session = useSession(client);
+  const cache = useQueryClient();
+  return useQuery(
+    computed(() => {
+      const url = toValue(config.url), params = toValue(config.params);
+      const snapshot = session.value;
+      return {
+        queryKey: queryIdentity(
+          client,
+          toValue(config.key),
+          url,
+          params,
+          config.headers,
+          toValue(config.cacheScope)
+        ),
+        queryFn: ({ signal }) => {
+          client.assertSession(snapshot.revision);
+          return client.request(url, {
+            params,
+            headers: config.headers,
+            timeoutMs: config.timeoutMs,
+            signal,
+            schema: config.schema,
+            authRetry: config.authRetry,
+            requiresAuth: config.requiresAuth
+          });
+        },
+        select: config.select ? (data) => invokeCallback(() => config.select(data)) : void 0,
+        enabled: config.requiresAuth ? !!snapshot.userId && toValue(config.enabled) !== false : toValue(config.enabled),
+        staleTime: config.staleTime,
+        retry: config.retry ?? cache.getDefaultOptions().queries?.retry ?? defaultQueryRetry
+      };
+    })
+  );
+}
+function useApiMutation(config) {
+  const client = useApiClient(), cache = useQueryClient(), session = useSession(client);
+  const mutation = useMutation(
+    computed(() => ({
+      mutationKey: [
+        "universal-api-layer",
+        client.cacheScope,
+        session.value.revision
+      ],
+      meta: { universalApiLayer: client.cacheScope },
+      mutationFn: async (envelope) => {
+        client.assertSession(envelope.revision);
+        const data = await runMutation(client, config, envelope.input);
+        client.assertSession(envelope.revision);
+        return data;
+      },
+      onSuccess: async (data, envelope) => {
+        client.assertSession(envelope.revision);
+        await Promise.all(
+          (config.invalidateKeys ?? []).map(
+            (queryKey) => cache.invalidateQueries({
+              queryKey,
+              predicate: config.invalidateScope === "all" ? void 0 : (query) => client.ownsQuery(query.queryKey)
+            })
+          )
+        );
+        client.assertSession(envelope.revision);
+        await invokeAsyncCallback(
+          () => config.onSuccess?.(data, envelope.input)
+        );
+        client.assertSession(envelope.revision);
+      }
+    }))
+  );
+  const translate = (options) => options ? {
+    onSuccess: (data, envelope, context, mutationContext) => {
+      if (envelope.revision === client.getSessionSnapshot().revision)
+        options.onSuccess?.(
+          data,
+          envelope.input,
+          context,
+          mutationContext
+        );
+    },
+    onError: (error, envelope, context, mutationContext) => {
+      if (envelope.revision === client.getSessionSnapshot().revision)
+        options.onError?.(
+          error,
+          envelope.input,
+          context,
+          mutationContext
+        );
+    },
+    onSettled: (data, error, envelope, context, mutationContext) => {
+      if (envelope.revision === client.getSessionSnapshot().revision)
+        options.onSettled?.(
+          data,
+          error,
+          envelope.input,
+          context,
+          mutationContext
+        );
+    }
+  } : void 0;
+  const current = computed(
+    () => !mutation.variables.value || mutation.variables.value.revision === session.value.revision
+  );
+  return {
+    ...mutation,
+    data: computed(() => current.value ? mutation.data.value : void 0),
+    error: computed(() => current.value ? mutation.error.value : null),
+    variables: computed(
+      () => current.value ? mutation.variables.value?.input : void 0
+    ),
+    context: computed(
+      () => current.value ? mutation.context.value : void 0
+    ),
+    status: computed(() => current.value ? mutation.status.value : "idle"),
+    isPaused: computed(() => current.value && mutation.isPaused.value),
+    isIdle: computed(() => !current.value || mutation.isIdle.value),
+    isPending: computed(() => current.value && mutation.isPending.value),
+    isSuccess: computed(() => current.value && mutation.isSuccess.value),
+    isError: computed(() => current.value && mutation.isError.value),
+    submittedAt: computed(
+      () => current.value ? mutation.submittedAt.value : 0
+    ),
+    failureCount: computed(
+      () => current.value ? mutation.failureCount.value : 0
+    ),
+    failureReason: computed(
+      () => current.value ? mutation.failureReason.value : null
+    ),
+    mutate: (input, options) => mutation.mutate(
+      { input, revision: client.getSessionSnapshot().revision },
+      translate(options)
+    ),
+    mutateAsync: (input, options) => client.withSession(
+      () => mutation.mutateAsync(
+        { input, revision: client.getSessionSnapshot().revision },
+        translate(options)
+      )
+    )
+  };
+}
+export {
+  createApiPlugin,
+  useApiClient,
+  useApiMutation,
+  useApiQuery,
+  useApiSession
+};

package/dist/websocket/angular.d.ts

@@ -0,0 +1,9 @@
+import { Signal } from '@angular/core';
+import { SocketClient, SocketSnapshot } from './index.js';
+import '../client-ByBlZaRg.js';
+
+/** Subscription only: the application owns connect/disconnect/dispose. */
+declare function injectSocketState<T>(client: SocketClient<T>): Signal<SocketSnapshot>;
+declare function injectSocketMessage<T>(client: SocketClient<T>, listener: (message: T) => void): void;
+
+export { injectSocketMessage, injectSocketState };

package/dist/websocket/angular.js

@@ -0,0 +1,15 @@
+// src/websocket/angular.ts
+import { DestroyRef, inject, signal } from "@angular/core";
+function injectSocketState(client) {
+  const destroy = inject(DestroyRef);
+  const state = signal(client.getSnapshot());
+  destroy.onDestroy(client.subscribe(() => state.set(client.getSnapshot())));
+  return state.asReadonly();
+}
+function injectSocketMessage(client, listener) {
+  inject(DestroyRef).onDestroy(client.onMessage(listener));
+}
+export {
+  injectSocketMessage,
+  injectSocketState
+};

package/dist/websocket/index.d.ts

@@ -0,0 +1,7 @@
+import { b as SocketOptions, S as SocketClient } from '../types-CVzD7l4p.js';
+export { c as SocketData, d as SocketEvents, e as SocketSendData, a as SocketSnapshot, f as SocketTransport } from '../types-CVzD7l4p.js';
+import '../client-ByBlZaRg.js';
+
+declare function createSocketClient<T = unknown>(config: SocketOptions<T>): SocketClient<T>;
+
+export { SocketClient, SocketOptions, createSocketClient };