@zmdb/nuxt 1.0.0-beta.1

package/src/client/index.ts

@@ -0,0 +1,142 @@
+import { createFetchTransport } from '@zmdb/client';
+import type { ClientOptions } from '@zmdb/client';
+import type { FetchLike } from '@zmdb/client/transport';
+import { createZmdbVue } from '@zmdb/vue';
+import type { QueryLoader, ZmdbVueBindings } from '@zmdb/vue';
+import type { AsyncData, NuxtError, useAsyncData as useNuxtAsyncData } from 'nuxt/app';
+import { computed, toValue } from 'vue';
+import type { App, MaybeRefOrGetter } from 'vue';
+
+export type NuxtGeneratedClientFactory<Client extends object> = (options: ClientOptions) => Client;
+
+export interface ZmdbNuxtBindingOptions {
+  readonly useAsyncData: typeof useNuxtAsyncData;
+  readonly bindingName?: string;
+}
+
+export interface ZmdbNuxtAsyncData<Output> extends AsyncData<Output | undefined, NuxtError<unknown> | undefined> {}
+
+export interface ZmdbNuxtBindings<Client extends object> extends ZmdbVueBindings<Client> {
+  useZmdbAsyncData<Input, Output>(
+    operationKey: string,
+    input: MaybeRefOrGetter<Input>,
+    load: QueryLoader<Client, Input, Output>,
+  ): ZmdbNuxtAsyncData<Output>;
+}
+
+export interface NuxtClientApplication {
+  readonly vueApp: Pick<App, 'use'>;
+}
+
+export interface ZmdbNuxtClientPluginOptions {
+  readonly baseUrl: string | URL;
+  readonly fetch?: FetchLike;
+}
+
+function encoded(value: unknown, seen: Set<object>): string {
+  if (value === null) return 'null';
+  if (typeof value === 'string' || typeof value === 'boolean') {
+    const result = JSON.stringify(value);
+    if (result === undefined) throw new Error('@zmdb/nuxt could not serialize a hydration input');
+    return result;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('@zmdb/nuxt hydration input numbers must be finite');
+    return Object.is(value, -0) ? '0' : String(value);
+  }
+  if (typeof value !== 'object') {
+    throw new Error(`@zmdb/nuxt hydration input contains non-serializable ${typeof value}`);
+  }
+  if (seen.has(value)) throw new Error('@zmdb/nuxt hydration input contains a cycle');
+
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const keys = Object.keys(value);
+      if (keys.length !== value.length || keys.some((key, index) => key !== String(index))) {
+        throw new Error('@zmdb/nuxt hydration input arrays must be dense and contain no named properties');
+      }
+      if (Object.getOwnPropertySymbols(value).length > 0) {
+        throw new Error('@zmdb/nuxt hydration input contains non-serializable symbol keys');
+      }
+      return `[${value.map(item => encoded(item, seen)).join(',')}]`;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error('@zmdb/nuxt hydration input must contain only plain objects and arrays');
+    }
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+      throw new Error('@zmdb/nuxt hydration input contains non-serializable symbol keys');
+    }
+    const entries = Object.entries(value).toSorted(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries
+      .map(([key, item]) => {
+        const encodedKey = JSON.stringify(key);
+        if (encodedKey === undefined) throw new Error('@zmdb/nuxt could not serialize a hydration key');
+        return `${encodedKey}:${encoded(item, seen)}`;
+      })
+      .join(',')}}`;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+export function createNuxtDataKey(operationKey: string, input: unknown): string {
+  const selectedOperation = operationKey.trim();
+  if (selectedOperation.length === 0) {
+    throw new Error('@zmdb/nuxt operation key must be a non-empty string');
+  }
+  return `zmdb:${encoded([selectedOperation, input], new Set())}`;
+}
+
+function invoke<Client, Input, Output>(
+  load: QueryLoader<Client, Input, Output>,
+  client: Client,
+  input: Input,
+  signal: AbortSignal,
+): Promise<Output> {
+  try {
+    return Promise.resolve(load(client, input, signal));
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+
+export function createZmdbNuxt<Client extends object>(options: ZmdbNuxtBindingOptions): ZmdbNuxtBindings<Client> {
+  const vue = createZmdbVue<Client>(options.bindingName ?? '@zmdb/nuxt');
+
+  return Object.freeze({
+    ...vue,
+    useZmdbAsyncData<Input, Output>(
+      operationKey: string,
+      input: MaybeRefOrGetter<Input>,
+      load: QueryLoader<Client, Input, Output>,
+    ): ZmdbNuxtAsyncData<Output> {
+      const client = vue.useZmdbClient();
+      const key = computed(() => createNuxtDataKey(operationKey, toValue(input)));
+      return options.useAsyncData<Output, unknown, Output, never[], undefined>(
+        key,
+        (_nuxtApp, context) => invoke(load, client, toValue(input), context.signal),
+        {
+          dedupe: 'cancel',
+          deep: false,
+        },
+      );
+    },
+  });
+}
+
+export function createZmdbNuxtClientPlugin<Client extends object>(
+  bindings: Pick<ZmdbNuxtBindings<Client>, 'createZmdbPlugin'>,
+  createClient: NuxtGeneratedClientFactory<Client>,
+  options: ZmdbNuxtClientPluginOptions,
+): (nuxtApp: NuxtClientApplication) => void {
+  return nuxtApp => {
+    const transport = createFetchTransport(options.fetch);
+    const client = createClient({
+      baseUrl: options.baseUrl,
+      transport,
+    });
+    nuxtApp.vueApp.use(bindings.createZmdbPlugin(client));
+  };
+}

package/src/forwarding.ts

@@ -0,0 +1,34 @@
+export type ZmdbNuxtForwardNameKind = 'header' | 'cookie';
+
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const RESERVED_FORWARD_HEADERS = new Set([
+  'accept',
+  'connection',
+  'content-length',
+  'content-type',
+  'cookie',
+  'host',
+  'transfer-encoding',
+]);
+
+export function normalizeForwardNames(
+  values: readonly string[] | undefined,
+  kind: ZmdbNuxtForwardNameKind,
+): readonly string[] {
+  const selected = values ?? [];
+  const normalized = selected.map(value => (kind === 'header' ? value.trim().toLowerCase() : value.trim()));
+  const pattern = kind === 'header' ? HEADER_NAME : COOKIE_NAME;
+  for (const value of normalized) {
+    if (!pattern.test(value)) {
+      throw new Error(`@zmdb/nuxt forward ${kind} name ${JSON.stringify(value)} is invalid`);
+    }
+    if (kind === 'header' && RESERVED_FORWARD_HEADERS.has(value)) {
+      throw new Error(`@zmdb/nuxt forward header ${value} is transport-owned; use forwardCookies for cookies`);
+    }
+  }
+  if (new Set(normalized).size !== normalized.length) {
+    throw new Error(`@zmdb/nuxt forward ${kind} names must not contain duplicates`);
+  }
+  return Object.freeze(normalized);
+}

package/src/index.ts

@@ -0,0 +1,112 @@
+import { addPluginTemplate, defineNuxtModule, resolvePath } from 'nuxt/kit';
+
+import { normalizeForwardNames } from './forwarding.js';
+
+export interface ZmdbNuxtModuleOptions {
+  /**
+   * Application module exporting both the typed bindings and generated-client
+   * factory named below.
+   */
+  readonly integration: string;
+  readonly bindingExport?: string;
+  readonly clientFactoryExport?: string;
+  readonly baseUrl?: string;
+  readonly forwardHeaders?: readonly string[];
+  readonly forwardCookies?: readonly string[];
+}
+
+interface ResolvedModuleOptions {
+  readonly integration: string;
+  readonly bindingExport: string;
+  readonly clientFactoryExport: string;
+  readonly baseUrl: string;
+  readonly forwardHeaders: readonly string[];
+  readonly forwardCookies: readonly string[];
+}
+
+const IDENTIFIER = /^[$A-Z_a-z][$\w]*$/;
+
+function requiredText(value: string | undefined, label: string): string {
+  const selected = value?.trim();
+  if (selected === undefined || selected.length === 0) {
+    throw new Error(`@zmdb/nuxt ${label} must be a non-empty string`);
+  }
+  return selected;
+}
+
+function exportName(value: string | undefined, fallback: string, label: string): string {
+  const selected = value ?? fallback;
+  if (!IDENTIFIER.test(selected)) {
+    throw new Error(`@zmdb/nuxt ${label} must be a JavaScript identifier`);
+  }
+  return selected;
+}
+
+async function resolvedOptions(options: ZmdbNuxtModuleOptions): Promise<ResolvedModuleOptions> {
+  const integration = await resolvePath(requiredText(options.integration, 'integration module'));
+  return Object.freeze({
+    integration,
+    bindingExport: exportName(options.bindingExport, 'zmdb', 'bindingExport'),
+    clientFactoryExport: exportName(options.clientFactoryExport, 'createApiClient', 'clientFactoryExport'),
+    baseUrl: requiredText(options.baseUrl ?? '/api', 'baseUrl'),
+    forwardHeaders: normalizeForwardNames(options.forwardHeaders, 'header'),
+    forwardCookies: normalizeForwardNames(options.forwardCookies, 'cookie'),
+  });
+}
+
+function integrationImport(options: ResolvedModuleOptions): string {
+  return `import { ${options.bindingExport} as zmdbBindings, ${options.clientFactoryExport} as createZmdbClient } from ${JSON.stringify(options.integration)};`;
+}
+
+function clientPlugin(options: ResolvedModuleOptions): string {
+  return [
+    "import { defineNuxtPlugin } from '#app';",
+    "import { createZmdbNuxtClientPlugin } from '@zmdb/nuxt/client';",
+    integrationImport(options),
+    '',
+    `export default defineNuxtPlugin(createZmdbNuxtClientPlugin(zmdbBindings, createZmdbClient, ${JSON.stringify({ baseUrl: options.baseUrl })}));`,
+    '',
+  ].join('\n');
+}
+
+function serverPlugin(options: ResolvedModuleOptions): string {
+  return [
+    "import { defineNuxtPlugin } from '#app';",
+    "import { useNitroApp } from 'nitropack/runtime';",
+    "import { createZmdbNuxtServerPlugin } from '@zmdb/nuxt/server';",
+    integrationImport(options),
+    '',
+    'export default defineNuxtPlugin(',
+    '  createZmdbNuxtServerPlugin(zmdbBindings, createZmdbClient, {',
+    `    baseUrl: ${JSON.stringify(options.baseUrl)},`,
+    `    forwardHeaders: ${JSON.stringify(options.forwardHeaders)},`,
+    `    forwardCookies: ${JSON.stringify(options.forwardCookies)},`,
+    '    fetch: useNitroApp().localFetch,',
+    '  }),',
+    ');',
+    '',
+  ].join('\n');
+}
+
+export const zmdbNuxtModule = defineNuxtModule<ZmdbNuxtModuleOptions>({
+  meta: {
+    name: '@zmdb/nuxt',
+    configKey: 'zmdb',
+    compatibility: {
+      nuxt: '>=4.5.2 <5.0.0',
+    },
+  },
+  async setup(options) {
+    const resolved = await resolvedOptions(options);
+    addPluginTemplate({
+      filename: 'zmdb.client.mjs',
+      getContents: () => clientPlugin(resolved),
+    });
+    addPluginTemplate({
+      filename: 'zmdb.server.mjs',
+      getContents: () => serverPlugin(resolved),
+    });
+  },
+});
+
+export default zmdbNuxtModule;

package/src/server/index.ts

@@ -0,0 +1,128 @@
+import { createFetchTransport } from '@zmdb/client';
+import type { ClientRequest, ClientTransport } from '@zmdb/client';
+import type { FetchLike } from '@zmdb/client/transport';
+import type { App } from 'vue';
+
+import type { NuxtGeneratedClientFactory, ZmdbNuxtBindings } from '../client/index.js';
+import { normalizeForwardNames } from '../forwarding.js';
+
+export interface ZmdbNuxtForwardingOptions {
+  readonly forwardHeaders?: readonly string[];
+  readonly forwardCookies?: readonly string[];
+}
+
+export interface ZmdbNuxtServerPluginOptions extends ZmdbNuxtForwardingOptions {
+  readonly baseUrl: string | URL;
+  readonly fetch: FetchLike;
+}
+
+export interface NuxtServerApplication {
+  readonly vueApp: Pick<App, 'use'>;
+  readonly ssrContext?: {
+    readonly event?: unknown;
+  };
+}
+
+interface NuxtRequestEvent {
+  readonly headers: Headers;
+}
+
+function cookiePairs(value: string | null | undefined): ReadonlyMap<string, string> {
+  const pairs = new Map<string, string>();
+  for (const segment of value?.split(';') ?? []) {
+    const separator = segment.indexOf('=');
+    if (separator <= 0) continue;
+    const name = segment.slice(0, separator).trim();
+    if (name.length === 0 || pairs.has(name)) continue;
+    pairs.set(name, segment.slice(separator + 1).trim());
+  }
+  return pairs;
+}
+
+function selectedCookieHeader(
+  incoming: ReadonlyMap<string, string>,
+  names: readonly string[],
+  operationCookie: string | undefined,
+): string | undefined {
+  const selected = new Map<string, string>();
+  for (const name of names) {
+    const value = incoming.get(name);
+    if (value !== undefined) selected.set(name, value);
+  }
+  for (const [name, value] of cookiePairs(operationCookie)) selected.set(name, value);
+  if (selected.size === 0) return undefined;
+  return [...selected].map(([name, value]) => `${name}=${value}`).join('; ');
+}
+
+function forwardedHeaders(incoming: Headers, names: readonly string[]): Headers {
+  const selected = new Headers();
+  for (const name of names) {
+    const value = incoming.get(name);
+    if (value !== null) selected.set(name, value);
+  }
+  return selected;
+}
+
+function requestInit(init: RequestInit | undefined, forwarded: Headers, cookie: string | undefined): RequestInit {
+  const headers = new Headers(init?.headers);
+  forwarded.forEach((value, name) => {
+    if (!headers.has(name)) headers.set(name, value);
+  });
+  if (cookie !== undefined && !headers.has('cookie')) headers.set('cookie', cookie);
+  return init === undefined ? { headers } : { ...init, headers };
+}
+
+function withoutCookie(request: ClientRequest): ClientRequest {
+  if (request.headers.cookie === undefined) return request;
+  const headers = Object.freeze(
+    Object.fromEntries(Object.entries(request.headers).filter(([name]) => name !== 'cookie')),
+  );
+  return Object.freeze({
+    ...request,
+    headers,
+  });
+}
+
+function requestEvent(value: unknown): NuxtRequestEvent {
+  if (typeof value !== 'object' || value === null || !('headers' in value)) {
+    throw new Error('@zmdb/nuxt server plugin requires the current Nitro request event');
+  }
+  const headers = value.headers;
+  if (!(headers instanceof Headers)) {
+    throw new Error('@zmdb/nuxt server plugin requires the current Nitro request event');
+  }
+  return Object.freeze({ headers });
+}
+
+export function createNuxtServerTransport(
+  fetch: FetchLike,
+  incomingHeaders: Headers,
+  options: ZmdbNuxtForwardingOptions = {},
+): ClientTransport {
+  const headerNames = normalizeForwardNames(options.forwardHeaders, 'header');
+  const cookieNames = normalizeForwardNames(options.forwardCookies, 'cookie');
+  const forwarded = forwardedHeaders(incomingHeaders, headerNames);
+  const incomingCookies = cookiePairs(incomingHeaders.get('cookie'));
+
+  return request => {
+    const cookie = selectedCookieHeader(incomingCookies, cookieNames, request.headers.cookie);
+    const requestFetch: FetchLike = (input, init) => fetch(input, requestInit(init, forwarded, cookie));
+    return createFetchTransport(requestFetch)(withoutCookie(request));
+  };
+}
+
+export function createZmdbNuxtServerPlugin<Client extends object>(
+  bindings: Pick<ZmdbNuxtBindings<Client>, 'createZmdbPlugin'>,
+  createClient: NuxtGeneratedClientFactory<Client>,
+  options: ZmdbNuxtServerPluginOptions,
+): (nuxtApp: NuxtServerApplication) => void {
+  return nuxtApp => {
+    const event = requestEvent(nuxtApp.ssrContext?.event);
+    const transport = createNuxtServerTransport(options.fetch, event.headers, options);
+    const client = createClient({
+      baseUrl: options.baseUrl,
+      transport,
+    });
+    nuxtApp.vueApp.use(bindings.createZmdbPlugin(client));
+  };
+}