@hypequery/serve 0.2.0 → 0.3.0

package/dist/server/api-builder.js

@@ -0,0 +1,76 @@
+import { mergeTags } from "../utils.js";
+import { applyBasePath, normalizeRoutePath } from "../router.js";
+import { mapEndpointToToolkit } from "./mapper.js";
+export const createAPImethods = (queryEntries, queryLogger, router, authStrategies, globalMiddlewares, executeQuery, handler, basePath) => {
+    const api = {
+        queries: queryEntries,
+        queryLogger,
+        manifest: () => {
+            const manifest = {};
+            for (const [key, endpoint] of Object.entries(queryEntries)) {
+                manifest[key] = {
+                    method: endpoint.method,
+                    // queryEntries store the pre-basePath route; re-apply so the manifest
+                    // carries the full request path clients should call.
+                    path: applyBasePath(basePath, endpoint.metadata.path),
+                };
+            }
+            return manifest;
+        },
+        route: (path, endpoint, options = {}) => {
+            if (!endpoint) {
+                throw new Error("Endpoint definition is required when registering a route");
+            }
+            const method = options?.method ?? endpoint.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 api;
+        },
+        use: (middleware) => {
+            globalMiddlewares.push(middleware);
+            return api;
+        },
+        useAuth: (strategy) => {
+            authStrategies.push(strategy);
+            router.markRoutesRequireAuth();
+            return api;
+        },
+        execute: executeQuery,
+        client: executeQuery,
+        run: executeQuery,
+        describe: () => {
+            const description = {
+                basePath: basePath || undefined,
+                queries: router.list().map(mapEndpointToToolkit),
+            };
+            return description;
+        },
+        handler,
+    };
+    return api;
+};

package/dist/server/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/server/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EAEZ,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,oBAAoB,EAGrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAYtD,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EACjD,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EAEzB,cAAc,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EACzD,aAAa,gBAAgB,EAC7B,aAAa,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,EACnD,QAAQ,WAAW,EACnB,gBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,EACrC,mBAAmB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,EAC/D,cAAc,oBAAoB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,EACzF,SAAS,YAAY,EACrB,UAAU,MAAM,KACf,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAsF3E,CAAC"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/server/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EAEV,YAAY,EAEZ,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,oBAAoB,EAGrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAYtD,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EACjD,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EAEzB,cAAc,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EACzD,aAAa,gBAAgB,EAC7B,aAAa,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,EACnD,QAAQ,WAAW,EACnB,gBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,EACrC,mBAAmB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,EAC/D,cAAc,oBAAoB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,EACzF,SAAS,YAAY,EACrB,UAAU,MAAM,KACf,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAoG3E,CAAC"}

package/dist/server/builder.js

@@ -1,5 +1,5 @@
 import { mergeTags } from "../utils.js";
-import { normalizeRoutePath } from "../router.js";
+import { applyBasePath, normalizeRoutePath } from "../router.js";
 import { mapEndpointToToolkit } from "./mapper.js";
 const loadNodeAdapter = async () => {
     if (typeof require !== "undefined") {
@@ -13,6 +13,16 @@ export const createBuilderMethods = (queryEntries, queryLogger, routeConfig, rou
         basePath: basePath || undefined,
         queryLogger,
         _routeConfig: routeConfig,
+        manifest: () => {
+            const manifest = {};
+            for (const [key, endpoint] of Object.entries(queryEntries)) {
+                manifest[key] = {
+                    method: routeConfig[key]?.method ?? endpoint.method,
+                    path: applyBasePath(basePath, endpoint.metadata.path),
+                };
+            }
+            return manifest;
+        },
         route: (path, endpoint, options = {}) => {
             if (!endpoint) {
                 throw new Error("Endpoint definition is required when registering a route");

package/dist/server/create-api.d.ts

@@ -0,0 +1,32 @@
+import type { AuthContext, HypeQueryAPI, ServeEndpointMap, ServeQueriesMap, ServeConfig, MetricsConfig, DatasetsConfig, ServeSemanticEndpointMap } from "../types.js";
+/**
+ * Create a transport-agnostic API definition.
+ *
+ * `createAPI` sets up queries, auth, tenancy, caching, and middleware —
+ * without binding to any HTTP server or runtime. Use standalone transport
+ * functions to serve the API:
+ *
+ * @example
+ * ```ts
+ * import { createAPI } from '@hypequery/serve';
+ * import { startServer, toFetchHandler, toNodeHandler } from '@hypequery/serve';
+ *
+ * const api = createAPI({
+ *   auth: jwtStrategy,
+ *   queries: {
+ *     revenue: { query: async () => db.table('orders').sum('amount').execute() },
+ *   },
+ * });
+ *
+ * // Standalone server
+ * startServer(api, { port: 3000 });
+ *
+ * // Express / Node.js middleware
+ * app.use('/analytics', toNodeHandler(api));
+ *
+ * // Serverless (Vercel, Cloudflare, etc.)
+ * export default toFetchHandler(api);
+ * ```
+ */
+export declare const createAPI: <TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext, TQueries extends ServeQueriesMap<TContext, TAuth> = Record<never, never>, TMetrics extends MetricsConfig<TAuth> = Record<never, never>, TDatasets extends DatasetsConfig<TAuth> = Record<never, never>>(config: ServeConfig<TContext, TAuth, TQueries, TMetrics, TDatasets>) => HypeQueryAPI<ServeEndpointMap<TQueries, TContext, TAuth> & ServeSemanticEndpointMap<TMetrics, TDatasets, TContext, TAuth>, TContext, TAuth>;
+//# sourceMappingURL=create-api.d.ts.map

package/dist/server/create-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-api.d.ts","sourceRoot":"","sources":["../../src/server/create-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,YAAY,EAGZ,gBAAgB,EAIhB,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,wBAAwB,EACzB,MAAM,aAAa,CAAC;AA2BrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,SAAS,GACpB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACxE,QAAQ,SAAS,aAAa,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,SAAS,SAAS,cAAc,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE9D,QAAQ,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,KAClE,YAAY,CACb,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,GACvC,wBAAwB,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,EAClE,QAAQ,EACR,KAAK,CA8ON,CAAC"}

package/dist/server/create-api.js

@@ -0,0 +1,211 @@
+import { createEndpoint } from "../endpoint.js";
+import { ServeRouter, applyBasePath, normalizeRoutePath } from "../router.js";
+import { ensureArray } from "../utils.js";
+import { ServeQueryLogger, formatQueryEvent, formatQueryEventJSON } from "../query-logger.js";
+import { createServeHandler } from "../pipeline.js";
+import { createDocsEndpoint, createOpenApiEndpoint } from "../pipeline.js";
+import { resolveCorsConfig } from "../cors.js";
+import { createExecuteQuery } from "./execute-query.js";
+import { createAPImethods } from "./api-builder.js";
+import { createDatasetClient } from "@hypequery/datasets";
+import { createMetricEndpoint, createDatasetEndpoint } from "../semantic/datasets/index.js";
+import { attachSemanticQueryBuilder, extractQueryBuilderFromContext } from "../semantic/query-builder-context.js";
+const assertSemanticKeyAvailable = (queryEntries, key, kind) => {
+    if (key in queryEntries) {
+        throw new Error(`createAPI: ${kind} "${key}" collides with an existing query key. ` +
+            `Rename the ${kind} or the query to keep api.queries and api.execute() unambiguous.`);
+    }
+};
+/**
+ * Create a transport-agnostic API definition.
+ *
+ * `createAPI` sets up queries, auth, tenancy, caching, and middleware —
+ * without binding to any HTTP server or runtime. Use standalone transport
+ * functions to serve the API:
+ *
+ * @example
+ * ```ts
+ * import { createAPI } from '@hypequery/serve';
+ * import { startServer, toFetchHandler, toNodeHandler } from '@hypequery/serve';
+ *
+ * const api = createAPI({
+ *   auth: jwtStrategy,
+ *   queries: {
+ *     revenue: { query: async () => db.table('orders').sum('amount').execute() },
+ *   },
+ * });
+ *
+ * // Standalone server
+ * startServer(api, { port: 3000 });
+ *
+ * // Express / Node.js middleware
+ * app.use('/analytics', toNodeHandler(api));
+ *
+ * // Serverless (Vercel, Cloudflare, etc.)
+ * export default toFetchHandler(api);
+ * ```
+ */
+export const createAPI = (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 baseContextFactory = config.context;
+    // Extract queryBuilder from context.db if not provided in config
+    let resolvedQueryBuilder = config.queryBuilder;
+    let extractedFromContext = false;
+    if (!resolvedQueryBuilder && baseContextFactory && (config.metrics || config.datasets)) {
+        // If context is a static object (not a function), we can extract queryBuilder synchronously
+        if (typeof baseContextFactory !== "function") {
+            resolvedQueryBuilder = extractQueryBuilderFromContext(baseContextFactory);
+            if (resolvedQueryBuilder) {
+                extractedFromContext = true;
+            }
+        }
+    }
+    const contextFactory = baseContextFactory || resolvedQueryBuilder
+        ? async ({ request, auth }) => {
+            const baseContext = baseContextFactory
+                ? typeof baseContextFactory === "function"
+                    ? await baseContextFactory({ request, auth })
+                    : baseContextFactory
+                : {};
+            // If queryBuilder was explicitly passed in config (not extracted from context),
+            // attach it to context for backward compatibility
+            if (config.queryBuilder) {
+                return attachSemanticQueryBuilder({ ...baseContext }, config.queryBuilder);
+            }
+            // If context.db is a queryBuilder but we haven't extracted it yet,
+            // also check and attach it to the semantic runtime for consistency
+            if (!extractedFromContext && typeof baseContextFactory === "function") {
+                const maybeQueryBuilder = extractQueryBuilderFromContext(baseContext);
+                if (maybeQueryBuilder) {
+                    return attachSemanticQueryBuilder({ ...baseContext }, maybeQueryBuilder);
+                }
+            }
+            return baseContext;
+        }
+        : undefined;
+    const hooks = (config.hooks ?? {});
+    const queryLogger = new ServeQueryLogger();
+    // Wire up production query logging if configured
+    if (config.queryLogging) {
+        if (typeof config.queryLogging === 'function') {
+            queryLogger.on(config.queryLogging);
+        }
+        else if (config.queryLogging === 'json') {
+            queryLogger.on((event) => {
+                const line = formatQueryEventJSON(event);
+                if (line)
+                    console.log(line);
+            });
+        }
+        else {
+            queryLogger.on((event) => {
+                const line = formatQueryEvent(event);
+                if (line)
+                    console.log(line);
+            });
+        }
+    }
+    // Slow query warning
+    if (config.slowQueryThreshold != null) {
+        queryLogger.on((event) => {
+            if (event.status === 'completed' && event.durationMs && event.durationMs > config.slowQueryThreshold) {
+                console.warn(`[hypequery/slow-query] ${event.method} ${event.path} took ${event.durationMs}ms (threshold: ${config.slowQueryThreshold}ms)`);
+            }
+        });
+    }
+    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 = {};
+    for (const key of Object.keys(configuredQueries)) {
+        const endpoint = createEndpoint(String(key), configuredQueries[key]);
+        const routePath = normalizeRoutePath(`/queries/${String(key)}`);
+        const registeredEndpoint = {
+            ...endpoint,
+            metadata: { ...endpoint.metadata, path: routePath },
+        };
+        queryEntries[key] = registeredEndpoint;
+        router.register(registeredEndpoint);
+    }
+    // Process metrics — auto-generate POST endpoints
+    if (config.metrics) {
+        const metricsEntries = config.metrics;
+        const builderFactory = resolvedQueryBuilder;
+        if (!builderFactory) {
+            throw new Error('createAPI: `queryBuilder` is required when `metrics` is provided. ' +
+                'Pass the createQueryBuilder(config) return value as `queryBuilder`, ' +
+                'or provide it via context as `context: () => ({ db: queryBuilder })`.');
+        }
+        const analytics = createDatasetClient({ queryBuilder: builderFactory });
+        for (const [name, entry] of Object.entries(metricsEntries)) {
+            assertSemanticKeyAvailable(queryEntries, name, "metric");
+            const metricEndpoint = createMetricEndpoint(name, entry, analytics, builderFactory);
+            const metricsPath = config.semanticPaths?.metrics ?? '/metrics';
+            const routePath = normalizeRoutePath(`${metricsPath}/${name}`);
+            const registeredEndpoint = {
+                ...metricEndpoint,
+                metadata: { ...metricEndpoint.metadata, path: routePath },
+            };
+            queryEntries[name] = registeredEndpoint;
+            router.register(registeredEndpoint);
+        }
+    }
+    // Process datasets — auto-generate POST endpoints for semantic dataset queries
+    if (config.datasets) {
+        const datasetEntries = config.datasets;
+        const builderFactory = resolvedQueryBuilder;
+        if (!builderFactory) {
+            throw new Error('createAPI: `queryBuilder` is required when `datasets` is provided. ' +
+                'Pass the createQueryBuilder(config) return value as `queryBuilder`, ' +
+                'or provide it via context as `context: () => ({ db: queryBuilder })`.');
+        }
+        for (const [name, entry] of Object.entries(datasetEntries)) {
+            assertSemanticKeyAvailable(queryEntries, `dataset:${name}`, "dataset");
+            const datasetEndpoint = createDatasetEndpoint(name, entry, builderFactory);
+            const datasetsPath = config.semanticPaths?.datasets ?? '/datasets';
+            const routePath = normalizeRoutePath(`${datasetsPath}/${name}/query`);
+            const registeredEndpoint = {
+                ...datasetEndpoint,
+                metadata: { ...datasetEndpoint.metadata, path: routePath },
+            };
+            queryEntries[`dataset:${name}`] = registeredEndpoint;
+            router.register(registeredEndpoint);
+        }
+    }
+    const corsConfig = resolveCorsConfig(config.cors);
+    const handler = createServeHandler({
+        router,
+        globalMiddlewares,
+        authStrategies,
+        tenantConfig: globalTenantConfig,
+        contextFactory,
+        hooks,
+        queryLogger,
+        verboseAuthErrors: config.security?.verboseAuthErrors ?? false,
+        corsConfig,
+    });
+    const executeQuery = createExecuteQuery(queryEntries, authStrategies, contextFactory, globalMiddlewares, globalTenantConfig, hooks, queryLogger, config.security?.verboseAuthErrors ?? false);
+    const api = createAPImethods(queryEntries, queryLogger, router, authStrategies, globalMiddlewares, executeQuery, handler, basePath);
+    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 api;
+};

package/dist/server/define-serve.d.ts

@@ -1,3 +1,22 @@
-import type { AuthContext, ServeBuilder, ServeConfig, ServeEndpointMap, ServeQueriesMap } from "../types.js";
-export declare const defineServe: <TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext, TQueries extends ServeQueriesMap<TContext, TAuth> = ServeQueriesMap<TContext, TAuth>>(config: ServeConfig<TContext, TAuth, TQueries>) => ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth>, TContext, TAuth>;
+import type { AuthContext, ServeBuilder, ServeConfig, ServeEndpointMap, ServeSemanticEndpointMap, ServeQueriesMap, MetricsConfig, DatasetsConfig } from "../types.js";
+/**
+ * Define and configure a serve API with embedded transport.
+ *
+ * @deprecated Prefer `createAPI()` with standalone transport functions for
+ * better separation of concerns. `defineServe()` couples API definition
+ * with the Node.js HTTP server via `.start()`.
+ *
+ * @example
+ * ```ts
+ * // Before (defineServe)
+ * const api = defineServe({ queries: { ... } });
+ * api.start({ port: 3000 });
+ *
+ * // After (createAPI + serve)
+ * import { createAPI, startServer } from '@hypequery/serve';
+ * const api = createAPI({ queries: { ... } });
+ * startServer(api, { port: 3000 });
+ * ```
+ */
+export declare const defineServe: <TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext, TQueries extends ServeQueriesMap<TContext, TAuth> = Record<never, never>, TMetrics extends MetricsConfig<TAuth> = Record<never, never>, TDatasets extends DatasetsConfig<TAuth> = Record<never, never>>(config: ServeConfig<TContext, TAuth, TQueries, TMetrics, TDatasets>) => ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth> & ServeSemanticEndpointMap<TMetrics, TDatasets, TContext, TAuth>, TContext, TAuth>;
 //# sourceMappingURL=define-serve.d.ts.map

package/dist/server/define-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-serve.d.ts","sourceRoot":"","sources":["../../src/server/define-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAGX,YAAY,EACZ,WAAW,EAEX,gBAAgB,EAIhB,eAAe,EAEhB,MAAM,aAAa,CAAC;AAWrB,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,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EAEpF,QAAQ,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,KAC7C,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAoH3E,CAAC"}
+{"version":3,"file":"define-serve.d.ts","sourceRoot":"","sources":["../../src/server/define-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,eAAe,EAEf,aAAa,EACb,cAAc,EACf,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;;;;;;;;GAkBG;AACH,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,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACxE,QAAQ,SAAS,aAAa,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,SAAS,SAAS,cAAc,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE9D,QAAQ,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,KAClE,YAAY,CACb,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,GACvC,wBAAwB,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,EAClE,QAAQ,EACR,KAAK,CAqDN,CAAC"}

package/dist/server/define-serve.js

@@ -1,91 +1,60 @@
-import { createEndpoint } from "../endpoint.js";
-import { ServeRouter, applyBasePath } from "../router.js";
-import { ensureArray } from "../utils.js";
-import { ServeQueryLogger, formatQueryEvent, formatQueryEventJSON } from "../query-logger.js";
-import { createServeHandler } from "../pipeline.js";
-import { createDocsEndpoint, createOpenApiEndpoint } from "../pipeline.js";
-import { resolveCorsConfig } from "../cors.js";
-import { createExecuteQuery } from "./execute-query.js";
-import { createBuilderMethods } from "./builder.js";
+import { createAPI } from "./create-api.js";
+/**
+ * Define and configure a serve API with embedded transport.
+ *
+ * @deprecated Prefer `createAPI()` with standalone transport functions for
+ * better separation of concerns. `defineServe()` couples API definition
+ * with the Node.js HTTP server via `.start()`.
+ *
+ * @example
+ * ```ts
+ * // Before (defineServe)
+ * const api = defineServe({ queries: { ... } });
+ * api.start({ port: 3000 });
+ *
+ * // After (createAPI + serve)
+ * import { createAPI, startServer } from '@hypequery/serve';
+ * const api = createAPI({ queries: { ... } });
+ * startServer(api, { port: 3000 });
+ * ```
+ */
 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 queryLogger = new ServeQueryLogger();
-    // Wire up production query logging if configured
-    if (config.queryLogging) {
-        if (typeof config.queryLogging === 'function') {
-            queryLogger.on(config.queryLogging);
+    const api = createAPI(config);
+    const loadNodeAdapter = async () => {
+        if (typeof require !== "undefined") {
+            return require("../adapters/node.js");
         }
-        else if (config.queryLogging === 'json') {
-            queryLogger.on((event) => {
-                const line = formatQueryEventJSON(event);
-                if (line)
-                    console.log(line);
-            });
-        }
-        else {
-            queryLogger.on((event) => {
-                const line = formatQueryEvent(event);
-                if (line)
-                    console.log(line);
-            });
-        }
-    }
-    // Slow query warning
-    if (config.slowQueryThreshold != null) {
-        queryLogger.on((event) => {
-            if (event.status === 'completed' && event.durationMs && event.durationMs > config.slowQueryThreshold) {
-                console.warn(`[hypequery/slow-query] ${event.method} ${event.path} took ${event.durationMs}ms (threshold: ${config.slowQueryThreshold}ms)`);
-            }
-        });
-    }
-    const openapiConfig = {
-        enabled: config.openapi?.enabled ?? true,
-        path: config.openapi?.path ?? "/openapi.json",
+        return import("../adapters/node.js");
     };
-    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 corsConfig = resolveCorsConfig(config.cors);
-    const handler = createServeHandler({
-        router,
-        globalMiddlewares,
-        authStrategies,
-        tenantConfig: globalTenantConfig,
-        contextFactory,
-        hooks,
-        queryLogger,
-        verboseAuthErrors: config.security?.verboseAuthErrors ?? false,
-        corsConfig,
-    });
-    // Track route configuration for client config extraction
+    // Extend the API with backwards-compatible ServeBuilder methods
+    const builder = api;
     const routeConfig = {};
-    const executeQuery = createExecuteQuery(queryEntries, authStrategies, contextFactory, globalMiddlewares, globalTenantConfig, hooks, queryLogger, config.security?.verboseAuthErrors ?? false);
-    const builder = createBuilderMethods(queryEntries, queryLogger, routeConfig, router, authStrategies, globalMiddlewares, executeQuery, handler, basePath);
-    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);
+    for (const [key, endpoint] of Object.entries(api.queries)) {
+        routeConfig[key] = { method: endpoint.method };
     }
+    Object.defineProperty(builder, "basePath", {
+        value: config.basePath ?? "/api/analytics",
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(builder, "_routeConfig", {
+        value: routeConfig,
+        enumerable: true,
+        configurable: true,
+    });
+    const originalRoute = builder.route.bind(builder);
+    builder.route = (path, endpoint, options = {}) => {
+        const result = originalRoute(path, endpoint, options);
+        const queryKey = Object.entries(api.queries).find(([_, entry]) => entry === endpoint)?.[0];
+        if (queryKey) {
+            routeConfig[queryKey] = { method: options?.method ?? endpoint.method };
+        }
+        return result;
+    };
+    // Add transport method that ServeBuilder expects
+    builder.start = async (options = {}) => {
+        const { startNodeServer } = await loadNodeAdapter();
+        return startNodeServer(api.handler, options);
+    };
     return builder;
 };

package/dist/server/index.d.ts

@@ -1,6 +1,8 @@
+export { createAPI } from "./create-api.js";
 export { defineServe } from "./define-serve.js";
 export { initServe } from "./init-serve.js";
 export { createExecuteQuery } from "./execute-query.js";
 export { createBuilderMethods } from "./builder.js";
+export { createAPImethods } from "./api-builder.js";
 export { mapEndpointToToolkit } from "./mapper.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/server/index.js

@@ -1,5 +1,7 @@
+export { createAPI } from "./create-api.js";
 export { defineServe } from "./define-serve.js";
 export { initServe } from "./init-serve.js";
 export { createExecuteQuery } from "./execute-query.js";
 export { createBuilderMethods } from "./builder.js";
+export { createAPImethods } from "./api-builder.js";
 export { mapEndpointToToolkit } from "./mapper.js";

package/dist/server/init-serve.d.ts

@@ -1,6 +1,6 @@
 import type { AuthContext, ServeContextFactory, ServeInitializer, ServeQueriesMap, ServeConfig } from "../types.js";
 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"> & {
+type ServeInitializerOptions<TFactory extends ServeContextFactory<any, TAuth>, TAuth extends AuthContext> = Omit<ServeConfig<InferInitializerContext<TFactory, TAuth>, TAuth, ServeQueriesMap<InferInitializerContext<TFactory, TAuth>, TAuth>, Record<never, never>, Record<never, never>>, "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>;

package/dist/server/init-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-serve.d.ts","sourceRoot":"","sources":["../../src/server/init-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACZ,MAAM,aAAa,CAAC;AAKrB,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,CAqCN,CAAC"}
+{"version":3,"file":"init-serve.d.ts","sourceRoot":"","sources":["../../src/server/init-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,WAAW,EAGZ,MAAM,aAAa,CAAC;AAKrB,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,EAChE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACpB,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CACrB,EACD,SAAS,GAAG,SAAS,CACtB,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;AAU1B,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,CAkDN,CAAC"}

package/dist/server/init-serve.js

@@ -5,11 +5,16 @@ export const initServe = (options) => {
     const { context, ...staticOptions } = options;
     const procedure = createProcedureBuilder();
     const define = (config) => {
-        return defineServe({
+        // Auto-extract queryBuilder from context.db if metrics/datasets are used
+        // This is handled in createAPI since it needs to support both sync and async contexts
+        const finalConfig = {
             ...staticOptions,
             ...config,
             context: (context ?? {}),
-        });
+        };
+        // Note: defineServe is deprecated for public use, but initServe uses it internally
+        // to provide the .start() method on the returned builder. This is intentional.
+        return defineServe(finalConfig);
     };
     const queryFactory = createQueryFactory((context ?? {}));
     const query = new Proxy(queryFactory, {

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

@@ -13,6 +13,10 @@ export declare const api: import("../types.js").ServeBuilder<import("../types.js
     }[]>;
 }, {
     db: {};
+}, import("../types.js").AuthContext> & import("../types.js").SemanticMetricEndpointMap<Record<never, never>, {
+    db: {};
+}, import("../types.js").AuthContext> & import("../types.js").SemanticDatasetEndpointMap<Record<never, never>, {
+    db: {};
 }, import("../types.js").AuthContext>, {
     db: {};
 }, import("../types.js").AuthContext>;

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

@@ -1 +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;AAYxB,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;qCAUd,CAAC"}
+{"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;AAYxB,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;qCAUd,CAAC"}

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

@@ -1,4 +1,4 @@
-import { initServe } from '../index.js';
+import { createAnalyticsTokenIssuer, createJwtStrategy, initServe } from '../index.js';
 import { z } from 'zod';
 const serve = initServe({
     context: () => ({
@@ -34,3 +34,18 @@ const executableResultPromise = executableQuery.execute({
 const _executableResultIsTyped = { total: 10 };
 // @ts-expect-error total must be number
 const _executableResultRejectsString = { total: '10' };
+createJwtStrategy({ secret: 'secret' });
+createJwtStrategy({ jwksUri: 'https://issuer.example.com/.well-known/jwks.json' });
+// @ts-expect-error exactly one key source is allowed
+createJwtStrategy({ secret: 'secret', jwksUri: 'https://issuer.example.com/.well-known/jwks.json' });
+// @ts-expect-error custom auth types require a mapper that proves required fields exist
+createJwtStrategy({ secret: 'secret' });
+createJwtStrategy({
+    secret: 'secret',
+    mapClaims: (payload) => ({
+        userId: String(payload.sub),
+        tenantId: String(payload.org_id),
+    }),
+});
+// @ts-expect-error token issuer supports symmetric HMAC JWT algorithms only
+createAnalyticsTokenIssuer({ secret: 'secret', algorithm: 'RS256' });

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=semantic.test-d.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.test-d.d.ts","sourceRoot":"","sources":["../../src/type-tests/semantic.test-d.ts"],"names":[],"mappings":""}