@hypequery/serve 0.0.4 → 0.0.5

package/dist/query-logger.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Backend-agnostic query event logger for the serve layer.
+ *
+ * Fires for every endpoint execution regardless of the underlying
+ * query backend (ClickHouse, BigQuery, mock data, etc.).
+ */
+/**
+ * Event emitted by the serve-layer query logger.
+ */
+export interface ServeQueryEvent {
+    requestId: string;
+    endpointKey: string;
+    path: string;
+    method: string;
+    status: 'started' | 'completed' | 'error';
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    input?: unknown;
+    responseStatus?: number;
+    error?: Error;
+    result?: unknown;
+}
+/**
+ * Callback for serve query events.
+ */
+export type ServeQueryEventCallback = (event: ServeQueryEvent) => void;
+/**
+ * Serve-layer query event emitter.
+ *
+ * Created per `defineServe()` call — not a singleton.
+ * Emits events at the request lifecycle level so that dev tools,
+ * logging, and analytics work with any query backend.
+ */
+export declare class ServeQueryLogger {
+    private listeners;
+    /**
+     * Subscribe to query events.
+     * @returns Unsubscribe function.
+     */
+    on(callback: ServeQueryEventCallback): () => void;
+    /**
+     * Emit a query event to all listeners.
+     */
+    emit(event: ServeQueryEvent): void;
+    /**
+     * Number of active listeners.
+     */
+    get listenerCount(): number;
+    /**
+     * Remove all listeners.
+     */
+    removeAll(): void;
+}
+/**
+ * Format a query event as a human-readable log line.
+ * Returns null for 'started' events (only logs completions).
+ */
+export declare function formatQueryEvent(event: ServeQueryEvent): string | null;
+/**
+ * Format a query event as a structured JSON string for log aggregators.
+ * Returns null for 'started' events (only logs completions).
+ */
+export declare function formatQueryEventJSON(event: ServeQueryEvent): string | null;
+//# sourceMappingURL=query-logger.d.ts.map

package/dist/query-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-logger.d.ts","sourceRoot":"","sources":["../src/query-logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAEvE;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAsC;IAEvD;;;OAGG;IACH,EAAE,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAOjD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAUlC;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,SAAS,IAAI,IAAI;CAGlB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAYtE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAiB1E"}

package/dist/query-logger.js

@@ -0,0 +1,91 @@
+/**
+ * Backend-agnostic query event logger for the serve layer.
+ *
+ * Fires for every endpoint execution regardless of the underlying
+ * query backend (ClickHouse, BigQuery, mock data, etc.).
+ */
+/**
+ * Serve-layer query event emitter.
+ *
+ * Created per `defineServe()` call — not a singleton.
+ * Emits events at the request lifecycle level so that dev tools,
+ * logging, and analytics work with any query backend.
+ */
+export class ServeQueryLogger {
+    constructor() {
+        this.listeners = new Set();
+    }
+    /**
+     * Subscribe to query events.
+     * @returns Unsubscribe function.
+     */
+    on(callback) {
+        this.listeners.add(callback);
+        return () => {
+            this.listeners.delete(callback);
+        };
+    }
+    /**
+     * Emit a query event to all listeners.
+     */
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+    /**
+     * Number of active listeners.
+     */
+    get listenerCount() {
+        return this.listeners.size;
+    }
+    /**
+     * Remove all listeners.
+     */
+    removeAll() {
+        this.listeners.clear();
+    }
+}
+/**
+ * Format a query event as a human-readable log line.
+ * Returns null for 'started' events (only logs completions).
+ */
+export function formatQueryEvent(event) {
+    if (event.status === 'started')
+        return null;
+    const status = event.status === 'completed' ? '✓' : '✗';
+    const duration = event.durationMs != null ? `${event.durationMs}ms` : '?';
+    const code = event.responseStatus ?? (event.status === 'error' ? 500 : 200);
+    let line = `  ${status} ${event.method} ${event.path} → ${code} (${duration})`;
+    if (event.status === 'error' && event.error) {
+        line += ` — ${event.error.message}`;
+    }
+    return line;
+}
+/**
+ * Format a query event as a structured JSON string for log aggregators.
+ * Returns null for 'started' events (only logs completions).
+ */
+export function formatQueryEventJSON(event) {
+    if (event.status === 'started')
+        return null;
+    return JSON.stringify({
+        level: event.status === 'error' ? 'error' : 'info',
+        msg: `${event.method} ${event.path}`,
+        requestId: event.requestId,
+        endpoint: event.endpointKey,
+        path: event.path,
+        method: event.method,
+        status: event.responseStatus ?? (event.status === 'error' ? 500 : 200),
+        durationMs: event.durationMs,
+        ...(event.status === 'error' && event.error
+            ? { error: event.error.message }
+            : {}),
+        timestamp: new Date(event.endTime ?? event.startTime).toISOString(),
+    });
+}

package/dist/router.d.ts

@@ -0,0 +1,13 @@
+import type { EndpointRegistry, HttpMethod, ServeEndpoint } from "./types.js";
+export declare const normalizeRoutePath: (path: string) => string;
+export declare const applyBasePath: (basePath: string, path: string) => string;
+export declare class ServeRouter implements EndpointRegistry {
+    private readonly basePath;
+    private routes;
+    constructor(basePath?: string);
+    list(): ServeEndpoint<any, any, any, any, any>[];
+    register(endpoint: ServeEndpoint<any, any, any, any>): void;
+    match(method: HttpMethod, path: string): ServeEndpoint<any, any, any, any, any> | null;
+    markRoutesRequireAuth(): void;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI9E,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,WAG9C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,WAM3D,CAAC;AAEF,qBAAa,WAAY,YAAW,gBAAgB;IAGtC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,MAAM,CAA2C;gBAE5B,QAAQ,SAAK;IAE1C,IAAI;IAIJ,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IAuBpD,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM;IAStC,qBAAqB;CAetB"}

package/dist/router.js

@@ -0,0 +1,56 @@
+const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, "");
+export const normalizeRoutePath = (path) => {
+    const trimmed = trimSlashes(path || "/");
+    return `/${trimmed}`.replace(/\/+/g, "/").replace(/\/$/, trimmed ? "" : "/");
+};
+export const applyBasePath = (basePath, path) => {
+    const parts = [trimSlashes(basePath ?? ""), trimSlashes(path)]
+        .filter(Boolean)
+        .join("/");
+    const combined = parts ? `/${parts}` : "/";
+    return combined.replace(/\/+/g, "/").replace(/\/$/, combined === "/" ? "/" : "");
+};
+export class ServeRouter {
+    constructor(basePath = "") {
+        this.basePath = basePath;
+        this.routes = [];
+    }
+    list() {
+        return [...this.routes];
+    }
+    register(endpoint) {
+        const path = endpoint.metadata.path || "/";
+        const normalizedPath = applyBasePath(this.basePath, path);
+        const method = endpoint.method;
+        const existing = this.routes.find((route) => route.metadata.path === normalizedPath && route.method === method);
+        if (existing) {
+            throw new Error(`Route already registered for ${method} ${normalizedPath}`);
+        }
+        this.routes.push({
+            ...endpoint,
+            metadata: {
+                ...endpoint.metadata,
+                path: normalizedPath,
+                method,
+            },
+        });
+    }
+    match(method, path) {
+        const normalizedPath = normalizeRoutePath(path);
+        return (this.routes.find((route) => route.method === method && route.metadata.path === normalizedPath) ?? null);
+    }
+    markRoutesRequireAuth() {
+        this.routes = this.routes.map((route) => {
+            if (route.metadata.requiresAuth === false) {
+                return route;
+            }
+            return {
+                ...route,
+                metadata: {
+                    ...route.metadata,
+                    requiresAuth: true,
+                },
+            };
+        });
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+import type { AuthContext, ServeBuilder, ServeConfig, ServeContextFactory, ServeEndpointMap, ServeInitializer, ServeQueriesMap } from "./types.js";
+export declare const defineServe: <TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext, const TQueries extends ServeQueriesMap<TContext, TAuth> = ServeQueriesMap<TContext, TAuth>>(config: ServeConfig<TContext, TAuth, TQueries>) => ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth>, TContext, TAuth>;
+type InferInitializerContext<TFactory, TAuth extends AuthContext> = TFactory extends ServeContextFactory<infer TContext, TAuth> ? TContext : never;
+type ServeInitializerOptions<TFactory extends ServeContextFactory<any, TAuth>, TAuth extends AuthContext> = Omit<ServeConfig<InferInitializerContext<TFactory, TAuth>, TAuth, ServeQueriesMap<InferInitializerContext<TFactory, TAuth>, TAuth>>, "queries" | "context"> & {
+    context: TFactory;
+};
+export declare const initServe: <TFactory extends ServeContextFactory<any, TAuth>, TAuth extends AuthContext = AuthContext>(options: ServeInitializerOptions<TFactory, TAuth>) => ServeInitializer<InferInitializerContext<TFactory, TAuth>, TAuth>;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,WAAW,EAIX,YAAY,EACZ,WAAW,EACX,mBAAmB,EAEnB,gBAAgB,EAEhB,gBAAgB,EAIhB,eAAe,EAMhB,MAAM,YAAY,CAAC;AAWpB,eAAO,MAAM,WAAW,GACtB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,KAAK,CAAC,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EAE1F,QAAQ,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,KAC7C,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAgL3E,CAAC;AA8BF,KAAK,uBAAuB,CAC1B,QAAQ,EACR,KAAK,SAAS,WAAW,IACvB,QAAQ,SAAS,mBAAmB,CAAC,MAAM,QAAQ,EAAE,KAAK,CAAC,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEnF,KAAK,uBAAuB,CAC1B,QAAQ,SAAS,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,EAChD,KAAK,SAAS,WAAW,IACvB,IAAI,CACN,WAAW,CACT,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,EACxC,KAAK,EACL,eAAe,CAAC,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CACjE,EACD,SAAS,GAAG,SAAS,CACtB,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;AAQ1B,eAAO,MAAM,SAAS,GACpB,QAAQ,SAAS,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,EAChD,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,SAAS,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAG,gBAAgB,CACpE,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,EACxC,KAAK,CAsBN,CAAC"}

package/dist/server.js

@@ -0,0 +1,191 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { startNodeServer } from "./adapters/node.js";
+import { createEndpoint } from "./endpoint.js";
+import { applyBasePath, normalizeRoutePath, ServeRouter } from "./router.js";
+import { createProcedureBuilder } from "./builder.js";
+import { ensureArray, mergeTags } from "./utils.js";
+import { createDocsEndpoint, createOpenApiEndpoint, createServeHandler, executeEndpoint, } from "./pipeline.js";
+export const defineServe = (config) => {
+    const basePath = config.basePath ?? "/api/analytics";
+    const router = new ServeRouter(basePath);
+    const globalMiddlewares = [
+        ...(config.middlewares ?? []),
+    ];
+    const authStrategies = ensureArray(config.auth);
+    const globalTenantConfig = config.tenant;
+    const contextFactory = config.context;
+    const hooks = (config.hooks ?? {});
+    const openapiConfig = {
+        enabled: config.openapi?.enabled ?? true,
+        path: config.openapi?.path ?? "/openapi.json",
+    };
+    const docsConfig = {
+        enabled: config.docs?.enabled ?? true,
+        path: config.docs?.path ?? "/docs",
+    };
+    const openapiPublicPath = applyBasePath(basePath, openapiConfig.path);
+    const configuredQueries = config.queries ?? {};
+    const queryEntries = {};
+    const registerQuery = (key, definition) => {
+        queryEntries[key] = createEndpoint(String(key), definition);
+    };
+    for (const key of Object.keys(configuredQueries)) {
+        registerQuery(key, configuredQueries[key]);
+    }
+    const handler = createServeHandler({
+        router,
+        globalMiddlewares,
+        authStrategies,
+        tenantConfig: globalTenantConfig,
+        contextFactory,
+        hooks,
+    });
+    // Track route configuration for client config extraction
+    const routeConfig = {};
+    const executeQuery = async (key, options) => {
+        const endpoint = queryEntries[key];
+        if (!endpoint) {
+            throw new Error(`No query registered for key ${String(key)}`);
+        }
+        const request = {
+            method: endpoint.method,
+            path: options?.request?.path ?? endpoint.metadata.path ?? `/__execute/${String(key)}`,
+            query: options?.request?.query ?? {},
+            headers: options?.request?.headers ?? {},
+            body: options?.input ?? options?.request?.body,
+            raw: options?.request?.raw,
+        };
+        const response = await executeEndpoint({
+            endpoint,
+            request,
+            authStrategies,
+            contextFactory,
+            globalMiddlewares,
+            tenantConfig: globalTenantConfig,
+            hooks,
+            additionalContext: options?.context,
+        });
+        if (response.status !== 200) {
+            const errorBody = response.body;
+            const error = new Error(errorBody.error.message);
+            error.type = errorBody.error.type;
+            if (errorBody.error.details) {
+                error.details = errorBody.error.details;
+            }
+            throw error;
+        }
+        return response.body;
+    };
+    const builder = {
+        queries: queryEntries,
+        _routeConfig: routeConfig,
+        route: (path, endpoint, options) => {
+            if (!endpoint) {
+                throw new Error("Endpoint definition is required when registering a route");
+            }
+            const method = options?.method ?? endpoint.method;
+            // Find the query key for this endpoint
+            const queryKey = Object.entries(queryEntries).find(([_, e]) => e === endpoint)?.[0];
+            if (queryKey) {
+                routeConfig[queryKey] = { method };
+            }
+            const normalizedPath = normalizeRoutePath(path);
+            const fallbackRequiresAuth = endpoint.auth
+                ? true
+                : authStrategies.length > 0
+                    ? true
+                    : undefined;
+            const requiresAuth = options?.requiresAuth ?? endpoint.metadata.requiresAuth ?? fallbackRequiresAuth;
+            const visibility = options?.visibility ?? endpoint.metadata.visibility ?? "public";
+            const metadata = {
+                ...endpoint.metadata,
+                path: normalizedPath,
+                method,
+                name: options?.name ?? endpoint.metadata.name ?? endpoint.key,
+                summary: options?.summary ?? endpoint.metadata.summary,
+                description: options?.description ?? endpoint.metadata.description,
+                tags: mergeTags(endpoint.metadata.tags, options?.tags),
+                requiresAuth,
+                visibility,
+            };
+            const middlewares = [...endpoint.middlewares, ...(options?.middlewares ?? [])];
+            const registeredEndpoint = {
+                ...endpoint,
+                method,
+                metadata,
+                middlewares,
+            };
+            router.register(registeredEndpoint);
+            return builder;
+        },
+        use: (middleware) => {
+            globalMiddlewares.push(middleware);
+            return builder;
+        },
+        useAuth: (strategy) => {
+            authStrategies.push(strategy);
+            router.markRoutesRequireAuth();
+            return builder;
+        },
+        execute: executeQuery,
+        run: executeQuery,
+        describe: () => {
+            const description = {
+                basePath: basePath || undefined,
+                queries: router.list().map(mapEndpointToToolkit),
+            };
+            return description;
+        },
+        handler,
+        start: async (options) => startNodeServer(handler, options),
+    };
+    if (openapiConfig.enabled) {
+        const openapiEndpoint = createOpenApiEndpoint(openapiConfig.path, () => router.list(), config.openapi);
+        router.register(openapiEndpoint);
+    }
+    if (docsConfig.enabled) {
+        const docsEndpoint = createDocsEndpoint(docsConfig.path, openapiPublicPath, config.docs);
+        router.register(docsEndpoint);
+    }
+    return builder;
+};
+const mapEndpointToToolkit = (endpoint) => {
+    // Use type assertion to avoid deep type instantiation issues with zodToJsonSchema
+    const inputSchema = endpoint.inputSchema
+        ? zodToJsonSchema(endpoint.inputSchema, { target: "openApi3" })
+        : undefined;
+    const outputSchema = endpoint.outputSchema
+        ? zodToJsonSchema(endpoint.outputSchema, { target: "openApi3" })
+        : undefined;
+    return {
+        key: endpoint.key,
+        path: endpoint.metadata.path,
+        method: endpoint.method,
+        name: endpoint.metadata.name ?? endpoint.key,
+        summary: endpoint.metadata.summary,
+        description: endpoint.metadata.description,
+        tags: endpoint.metadata.tags,
+        visibility: endpoint.metadata.visibility,
+        requiresAuth: Boolean(endpoint.metadata.requiresAuth),
+        requiresTenant: endpoint.tenant ? (endpoint.tenant.required !== false) : undefined,
+        inputSchema,
+        outputSchema,
+        custom: endpoint.metadata.custom,
+    };
+};
+export const initServe = (options) => {
+    const { context, ...staticOptions } = options;
+    const procedure = createProcedureBuilder();
+    return {
+        procedure,
+        query: procedure,
+        queries: (definitions) => definitions,
+        define: (config) => {
+            return defineServe({
+                ...staticOptions,
+                ...config,
+                context: (context ?? {}),
+            });
+        },
+    };
+};

package/dist/tenant.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Utilities for multi-tenant query isolation
+ */
+/**
+ * Creates a tenant-scoped query builder wrapper that automatically
+ * adds WHERE clauses to filter by tenant.
+ *
+ * @example
+ * ```typescript
+ * const api = defineServe({
+ *   context: ({ auth }) => ({
+ *     db: createTenantScope(myDb, {
+ *       tenantId: auth?.tenantId,
+ *       column: 'organization_id',
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+export declare function createTenantScope<TDb extends {
+    table: (name: string) => any;
+}>(db: TDb, options: {
+    tenantId: string | null | undefined;
+    column: string;
+}): TDb;
+/**
+ * Runtime warning when tenant isolation might be misconfigured
+ */
+export declare function warnTenantMisconfiguration(options: {
+    queryKey: string;
+    hasTenantConfig: boolean;
+    hasTenantId: boolean;
+    mode?: string;
+}): void;
+//# sourceMappingURL=tenant.d.ts.map

package/dist/tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../src/tenant.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAS;IAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,CAAA;CAAE,EAC5E,EAAE,EAAE,GAAG,EACP,OAAO,EAAE;IACP,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB,GACA,GAAG,CAoBL;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,QAYA"}

package/dist/tenant.js

@@ -0,0 +1,49 @@
+/**
+ * Utilities for multi-tenant query isolation
+ */
+/**
+ * Creates a tenant-scoped query builder wrapper that automatically
+ * adds WHERE clauses to filter by tenant.
+ *
+ * @example
+ * ```typescript
+ * const api = defineServe({
+ *   context: ({ auth }) => ({
+ *     db: createTenantScope(myDb, {
+ *       tenantId: auth?.tenantId,
+ *       column: 'organization_id',
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+export function createTenantScope(db, options) {
+    if (!options.tenantId) {
+        return db;
+    }
+    const originalTable = db.table.bind(db);
+    return {
+        ...db,
+        table: (name) => {
+            const query = originalTable(name);
+            // Auto-inject tenant filter
+            if (query && typeof query.where === 'function') {
+                return query.where(options.column, 'eq', options.tenantId);
+            }
+            return query;
+        },
+    };
+}
+/**
+ * Runtime warning when tenant isolation might be misconfigured
+ */
+export function warnTenantMisconfiguration(options) {
+    if (!options.hasTenantConfig) {
+        console.warn(`[hypequery/serve] Query "${options.queryKey}" accesses user data but has no tenant configuration. ` +
+            `This may lead to data leaks. Add tenant config to defineServe or the query definition.`);
+    }
+    else if (options.hasTenantId && options.mode === 'manual') {
+        console.warn(`[hypequery/serve] Query "${options.queryKey}" uses manual tenant mode. ` +
+            `Ensure you manually filter queries by tenantId to prevent data leaks.`);
+    }
+}

package/dist/type-tests/builder.test-d.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const api: import("../types.js").ServeBuilder<import("../types.js").ServeEndpointMap<{
+    typedQuery: import("../types.js").ServeQueryConfig<z.ZodObject<{
+        plan: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        plan?: string | undefined;
+    }, {
+        plan?: string | undefined;
+    }>, z.ZodTypeAny, {}, import("../types.js").AuthContext, {
+        plan: string;
+    }[]>;
+}, {}, import("../types.js").AuthContext>, {}, import("../types.js").AuthContext>;
+//# sourceMappingURL=builder.test-d.d.ts.map

package/dist/type-tests/builder.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.test-d.d.ts","sourceRoot":"","sources":["../../src/type-tests/builder.test-d.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,GAAG;;;;;;;;;;iFAUd,CAAC"}

package/dist/type-tests/builder.test-d.js

@@ -0,0 +1,20 @@
+import { initServe } from '../index.js';
+import { z } from 'zod';
+const serve = initServe({
+    context: () => ({}),
+});
+const { query } = serve;
+export const api = serve.define({
+    queries: serve.queries({
+        typedQuery: query
+            .describe('builder infers input + output')
+            .input(z.object({ plan: z.string().optional() }))
+            .query(async ({ input }) => {
+            const plan = input.plan ?? 'starter';
+            return [{ plan }];
+        }),
+    }),
+});
+const _resultIsTyped = [{ plan: 'starter' }];
+// @ts-expect-error plan must be string
+const _resultRejectsNumber = [{ plan: 123 }];