@veloxts/router 0.2.0 → 0.3.0

package/dist/procedure/types.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Procedure builder type definitions
+ *
+ * Provides the generic type accumulation system that enables type-safe
+ * procedure building with automatic inference through the fluent API chain.
+ *
+ * The key insight is using a "state" generic that accumulates type information
+ * as methods are called, without requiring explicit type annotations from users.
+ *
+ * @module procedure/types
+ */
+import type { BaseContext } from '@veloxts/core';
+import type { ZodType, ZodTypeDef } from 'zod';
+import type { CompiledProcedure, MiddlewareFunction, ProcedureHandler, RestRouteOverride } from '../types.js';
+/**
+ * Internal state type that accumulates type information through the builder chain
+ *
+ * This is the core type that enables inference flow. Each builder method returns
+ * a new ProcedureBuilder with updated state, preserving type information.
+ *
+ * @template TInput - The validated input type (unknown if no input schema)
+ * @template TOutput - The validated output type (unknown if no output schema)
+ * @template TContext - The context type (starts as BaseContext, extended by middleware)
+ */
+export interface ProcedureBuilderState<TInput = unknown, TOutput = unknown, TContext extends BaseContext = BaseContext> {
+    /** Marker for state identification */
+    readonly _brand: 'ProcedureBuilderState';
+    /** Phantom type holders - not used at runtime */
+    readonly _input: TInput;
+    readonly _output: TOutput;
+    readonly _context: TContext;
+}
+/**
+ * Constraint for valid input/output schemas
+ *
+ * Accepts any Zod schema type. The generic parameters allow us to
+ * extract the inferred type for state accumulation.
+ */
+export type ValidSchema<T = unknown> = ZodType<T, ZodTypeDef, unknown>;
+/**
+ * Extracts the output type from a Zod schema
+ *
+ * This is used internally to update builder state when .input() or .output() is called.
+ */
+export type InferSchemaOutput<T> = T extends ZodType<infer O, ZodTypeDef, unknown> ? O : never;
+/**
+ * Fluent procedure builder interface
+ *
+ * This interface defines all methods available on the procedure builder.
+ * Each method returns a new builder with updated type state, enabling
+ * full type inference through the chain.
+ *
+ * @template TInput - Current input type
+ * @template TOutput - Current output type
+ * @template TContext - Current context type
+ *
+ * @example
+ * ```typescript
+ * procedure()
+ *   .input(z.object({ id: z.string() }))  // TInput becomes { id: string }
+ *   .output(UserSchema)                    // TOutput becomes User
+ *   .query(async ({ input, ctx }) => {     // input: { id: string }, ctx: BaseContext
+ *     return user;                         // must return User
+ *   })
+ * ```
+ */
+export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext extends BaseContext = BaseContext> {
+    /**
+     * Defines the input validation schema for the procedure
+     *
+     * The input type is automatically inferred from the Zod schema.
+     * Can only be called once per procedure.
+     *
+     * @template TSchema - The Zod schema type
+     * @param schema - Zod schema for input validation
+     * @returns New builder with updated input type
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .input(z.object({
+     *     id: z.string().uuid(),
+     *     name: z.string().optional(),
+     *   }))
+     *   // input is now typed as { id: string; name?: string }
+     * ```
+     */
+    input<TSchema extends ValidSchema>(schema: TSchema): ProcedureBuilder<InferSchemaOutput<TSchema>, TOutput, TContext>;
+    /**
+     * Defines the output validation schema for the procedure
+     *
+     * The output type is automatically inferred from the Zod schema.
+     * The handler return type will be validated against this schema.
+     *
+     * @template TSchema - The Zod schema type
+     * @param schema - Zod schema for output validation
+     * @returns New builder with updated output type
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .output(z.object({
+     *     id: z.string(),
+     *     name: z.string(),
+     *   }))
+     *   // handler must return { id: string; name: string }
+     * ```
+     */
+    output<TSchema extends ValidSchema>(schema: TSchema): ProcedureBuilder<TInput, InferSchemaOutput<TSchema>, TContext>;
+    /**
+     * Adds middleware to the procedure chain
+     *
+     * Middleware executes before the handler and can:
+     * - Extend the context with new properties
+     * - Perform authentication/authorization
+     * - Log requests
+     * - Modify input (though input schema runs first)
+     * - Transform output
+     *
+     * Multiple middlewares are executed in order of definition.
+     *
+     * @template TNewContext - The extended context type
+     * @param middleware - Middleware function
+     * @returns New builder with updated context type
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .use(async ({ ctx, next }) => {
+     *     // Add user to context
+     *     const user = await getUser(ctx.request);
+     *     return next({ ctx: { user } });
+     *   })
+     *   .query(async ({ ctx }) => {
+     *     // ctx.user is now available
+     *   })
+     * ```
+     */
+    use<TNewContext extends BaseContext = TContext>(middleware: MiddlewareFunction<TInput, TContext, TNewContext, TOutput>): ProcedureBuilder<TInput, TOutput, TNewContext>;
+    /**
+     * Configures REST route override
+     *
+     * By default, REST routes are auto-generated from procedure names.
+     * Use this to customize the HTTP method or path.
+     *
+     * @param config - REST route configuration
+     * @returns Same builder (no type changes)
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .rest({ method: 'POST', path: '/users/:id/activate' })
+     * ```
+     */
+    rest(config: RestRouteOverride): ProcedureBuilder<TInput, TOutput, TContext>;
+    /**
+     * Finalizes the procedure as a query (read-only operation)
+     *
+     * Queries map to GET requests in REST and should not modify data.
+     * The handler receives the validated input and context.
+     *
+     * @param handler - The query handler function
+     * @returns Compiled procedure ready for registration
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .input(z.object({ id: z.string() }))
+     *   .query(async ({ input, ctx }) => {
+     *     return ctx.db.user.findUnique({ where: { id: input.id } });
+     *   })
+     * ```
+     */
+    query(handler: ProcedureHandler<TInput, TOutput, TContext>): CompiledProcedure<TInput, TOutput, TContext>;
+    /**
+     * Finalizes the procedure as a mutation (write operation)
+     *
+     * Mutations map to POST/PUT/DELETE in REST and can modify data.
+     * The handler receives the validated input and context.
+     *
+     * @param handler - The mutation handler function
+     * @returns Compiled procedure ready for registration
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .input(CreateUserSchema)
+     *   .mutation(async ({ input, ctx }) => {
+     *     return ctx.db.user.create({ data: input });
+     *   })
+     * ```
+     */
+    mutation(handler: ProcedureHandler<TInput, TOutput, TContext>): CompiledProcedure<TInput, TOutput, TContext>;
+}
+/**
+ * Internal runtime state for the procedure builder
+ *
+ * This holds the actual values during building, separate from the type state.
+ * The type state (generics) and runtime state are kept in sync by the builder.
+ */
+export interface BuilderRuntimeState {
+    /** Input validation schema */
+    inputSchema?: ValidSchema;
+    /** Output validation schema */
+    outputSchema?: ValidSchema;
+    /** Middleware chain */
+    middlewares: MiddlewareFunction<unknown, BaseContext, BaseContext, unknown>[];
+    /** REST route override */
+    restOverride?: RestRouteOverride;
+}
+/**
+ * Type for the procedures object passed to defineProcedures
+ *
+ * Each value must be a CompiledProcedure (result of .query() or .mutation()).
+ *
+ * NOTE: We use `any` here intentionally for the type parameters because:
+ * 1. CompiledProcedure has contravariant input types (handler params)
+ * 2. TypeScript's Record type requires assignability in both directions
+ * 3. Using `unknown` would prevent any concrete procedure from being assigned
+ *
+ * The actual type safety is preserved through InferProcedures<T> which captures
+ * the concrete types at definition time. This `any` only allows the assignment.
+ */
+export type ProcedureDefinitions = Record<string, CompiledProcedure<any, any, any>>;
+/**
+ * Type helper to preserve procedure types in a collection
+ *
+ * This ensures that when you call defineProcedures, the full type information
+ * of each procedure is preserved and accessible.
+ */
+export type InferProcedures<T extends ProcedureDefinitions> = {
+    [K in keyof T]: T[K];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/procedure/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/procedure/types.ts"],"names":[],"mappings":"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"}

package/dist/procedure/types.js

@@ -0,0 +1,13 @@
+/**
+ * Procedure builder type definitions
+ *
+ * Provides the generic type accumulation system that enables type-safe
+ * procedure building with automatic inference through the fluent API chain.
+ *
+ * The key insight is using a "state" generic that accumulates type information
+ * as methods are called, without requiring explicit type annotations from users.
+ *
+ * @module procedure/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/procedure/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/procedure/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/rest/adapter.d.ts

@@ -0,0 +1,124 @@
+/**
+ * REST adapter for procedure collections
+ *
+ * Generates REST routes from procedure definitions using naming conventions
+ * or manual overrides. Handles input validation, middleware execution, and
+ * output serialization.
+ *
+ * @module rest/adapter
+ */
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import type { CompiledProcedure, HttpMethod, ProcedureCollection } from '../types.js';
+/**
+ * REST route definition generated from a procedure
+ */
+export interface RestRoute {
+    /** HTTP method */
+    readonly method: HttpMethod;
+    /** Full path including namespace prefix */
+    readonly path: string;
+    /** Procedure name for debugging */
+    readonly procedureName: string;
+    /** The compiled procedure */
+    readonly procedure: CompiledProcedure;
+}
+/**
+ * Options for REST route registration
+ */
+export interface RestAdapterOptions {
+    /** API prefix (default: '/api') */
+    prefix?: string;
+    /** Custom error handler */
+    onError?: (error: unknown, request: FastifyRequest, reply: FastifyReply) => void;
+}
+/**
+ * Generate REST routes from a procedure collection
+ *
+ * Routes are generated by:
+ * 1. Using manual .rest() override if provided
+ * 2. Inferring from naming convention (getX, listX, createX)
+ * 3. Skipping if neither applies (tRPC-only procedure)
+ *
+ * @param collection - Procedure collection to generate routes from
+ * @returns Array of REST route definitions
+ */
+export declare function generateRestRoutes(collection: ProcedureCollection): RestRoute[];
+/**
+ * Register REST routes from procedure collections onto a Fastify instance
+ *
+ * @param server - Fastify instance to register routes on
+ * @param collections - Array of procedure collections
+ * @param options - Registration options
+ *
+ * @example
+ * ```typescript
+ * import { createVeloxApp } from '@veloxts/core';
+ * import { registerRestRoutes, defineProcedures, procedure } from '@veloxts/router';
+ *
+ * const app = await createVeloxApp();
+ *
+ * const users = defineProcedures('users', {
+ *   getUser: procedure()
+ *     .input(z.object({ id: z.string() }))
+ *     .query(async ({ input }) => ({ id: input.id, name: 'John' })),
+ *
+ *   listUsers: procedure()
+ *     .query(async () => [{ id: '1', name: 'John' }]),
+ *
+ *   createUser: procedure()
+ *     .input(z.object({ name: z.string() }))
+ *     .mutation(async ({ input }) => ({ id: 'new', name: input.name })),
+ * });
+ *
+ * registerRestRoutes(app.server, [users], { prefix: '/api' });
+ *
+ * // Generates:
+ * // GET  /api/users/:id  -> getUser
+ * // GET  /api/users      -> listUsers
+ * // POST /api/users      -> createUser
+ * ```
+ */
+export declare function registerRestRoutes(server: FastifyInstance, collections: ProcedureCollection[], options?: RestAdapterOptions): void;
+/**
+ * Get a summary of routes that would be generated from collections
+ *
+ * Useful for debugging and documentation.
+ *
+ * @param collections - Procedure collections to analyze
+ * @param prefix - API prefix (default: '/api')
+ * @returns Array of route summaries
+ */
+export declare function getRouteSummary(collections: ProcedureCollection[], prefix?: string): Array<{
+    method: HttpMethod;
+    path: string;
+    procedure: string;
+    namespace: string;
+}>;
+/**
+ * Creates a route registrar function for use with VeloxApp.routes()
+ *
+ * This is a convenience helper that returns a function suitable for
+ * passing to app.routes(), enabling a cleaner API.
+ *
+ * @param collections - Procedure collections to register
+ * @param options - Registration options
+ * @returns A function that registers routes on a Fastify instance
+ *
+ * @example
+ * ```typescript
+ * import { createVeloxApp } from '@veloxts/core';
+ * import { createRoutesRegistrar, defineProcedures, procedure } from '@veloxts/router';
+ *
+ * const users = defineProcedures('users', {
+ *   listUsers: procedure().query(async () => []),
+ * });
+ *
+ * const app = await createVeloxApp();
+ *
+ * app.routes(createRoutesRegistrar([users], { prefix: '/api' }));
+ *
+ * await app.start();
+ * ```
+ */
+export declare function createRoutesRegistrar(collections: ProcedureCollection[], options?: RestAdapterOptions): (server: FastifyInstance) => void;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/rest/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/rest/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAOtF;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,kBAAkB;IAClB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CAClF;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,mBAAmB,GAAG,SAAS,EAAE,CAW/E;AAsJD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,mBAAmB,EAAE,EAClC,OAAO,GAAE,kBAAuB,GAC/B,IAAI,CA0BN;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,mBAAmB,EAAE,EAClC,MAAM,SAAS,GACd,KAAK,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAsBnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,mBAAmB,EAAE,EAClC,OAAO,GAAE,kBAAuB,GAC/B,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAInC"}

package/dist/rest/adapter.js

@@ -0,0 +1,270 @@
+/**
+ * REST adapter for procedure collections
+ *
+ * Generates REST routes from procedure definitions using naming conventions
+ * or manual overrides. Handles input validation, middleware execution, and
+ * output serialization.
+ *
+ * @module rest/adapter
+ */
+import { ConfigurationError } from '@veloxts/core';
+import { executeProcedure } from '../procedure/builder.js';
+import { buildRestPath, parseNamingConvention } from './naming.js';
+// ============================================================================
+// Route Generation
+// ============================================================================
+/**
+ * Generate REST routes from a procedure collection
+ *
+ * Routes are generated by:
+ * 1. Using manual .rest() override if provided
+ * 2. Inferring from naming convention (getX, listX, createX)
+ * 3. Skipping if neither applies (tRPC-only procedure)
+ *
+ * @param collection - Procedure collection to generate routes from
+ * @returns Array of REST route definitions
+ */
+export function generateRestRoutes(collection) {
+    const routes = [];
+    for (const [name, procedure] of Object.entries(collection.procedures)) {
+        const route = generateRouteForProcedure(name, procedure, collection.namespace);
+        if (route) {
+            routes.push(route);
+        }
+    }
+    return routes;
+}
+/**
+ * Generate a REST route for a single procedure
+ *
+ * @internal
+ */
+function generateRouteForProcedure(name, procedure, namespace) {
+    // Check for manual REST override first
+    if (procedure.restOverride) {
+        const override = procedure.restOverride;
+        // Must have both method and path for override
+        if (override.method && override.path) {
+            return {
+                method: override.method,
+                path: override.path,
+                procedureName: name,
+                procedure,
+            };
+        }
+        // Partial override - try to fill in missing parts from convention
+        const convention = parseNamingConvention(name, procedure.type);
+        if (convention) {
+            return {
+                method: override.method ?? convention.method,
+                path: override.path ?? buildRestPath(namespace, convention),
+                procedureName: name,
+                procedure,
+            };
+        }
+        // Can't generate route without full info
+        return undefined;
+    }
+    // Try to infer from naming convention
+    const mapping = parseNamingConvention(name, procedure.type);
+    if (mapping) {
+        // MVP: Only allow GET and POST
+        if (mapping.method !== 'GET' && mapping.method !== 'POST') {
+            return undefined;
+        }
+        return {
+            method: mapping.method,
+            path: buildRestPath(namespace, mapping),
+            procedureName: name,
+            procedure,
+        };
+    }
+    // No route for this procedure (tRPC-only)
+    return undefined;
+}
+// ============================================================================
+// Route Handler Creation
+// ============================================================================
+/**
+ * Create a Fastify route handler from a procedure
+ *
+ * The handler:
+ * 1. Extracts input from request (params, query, body)
+ * 2. Gets context from request decorator
+ * 3. Executes the procedure (validation, middleware, handler)
+ * 4. Returns the result
+ */
+function createRouteHandler(route) {
+    return async (request, reply) => {
+        // Gather input from appropriate sources based on method
+        const input = gatherInput(request, route);
+        // Get context from request (decorated by @veloxts/core)
+        const ctx = getContextFromRequest(request);
+        // Execute the procedure
+        const result = await executeProcedure(route.procedure, input, ctx);
+        // For mutations (POST), set 201 status for creates
+        if (route.method === 'POST' && route.procedureName.startsWith('create')) {
+            reply.status(201);
+        }
+        return result;
+    };
+}
+/**
+ * Type guard to check if a value is a plain object
+ */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Gather input data from the request based on HTTP method
+ *
+ * - GET: Merge params and query
+ * - POST: Use body
+ */
+function gatherInput(request, route) {
+    if (route.method === 'GET') {
+        // Safely merge route params and query params with type guards
+        const params = isPlainObject(request.params) ? request.params : {};
+        const query = isPlainObject(request.query) ? request.query : {};
+        return {
+            ...params,
+            ...query,
+        };
+    }
+    // POST, PUT, PATCH, DELETE: Use body
+    return request.body;
+}
+/**
+ * Extract context from Fastify request
+ *
+ * The context is decorated onto the request by @veloxts/core's onRequest hook.
+ * This function expects the context to already be present.
+ */
+function getContextFromRequest(request) {
+    // Type assertion is safe because @veloxts/core decorates this in onRequest hook
+    const requestWithContext = request;
+    // The context should always be present if @veloxts/core is properly initialized
+    // If it's not, we throw an error to help developers debug
+    if (!requestWithContext.context) {
+        throw new ConfigurationError('Request context not found. Ensure VeloxApp is started before registering routes.');
+    }
+    return requestWithContext.context;
+}
+// ============================================================================
+// Route Registration
+// ============================================================================
+/**
+ * Register REST routes from procedure collections onto a Fastify instance
+ *
+ * @param server - Fastify instance to register routes on
+ * @param collections - Array of procedure collections
+ * @param options - Registration options
+ *
+ * @example
+ * ```typescript
+ * import { createVeloxApp } from '@veloxts/core';
+ * import { registerRestRoutes, defineProcedures, procedure } from '@veloxts/router';
+ *
+ * const app = await createVeloxApp();
+ *
+ * const users = defineProcedures('users', {
+ *   getUser: procedure()
+ *     .input(z.object({ id: z.string() }))
+ *     .query(async ({ input }) => ({ id: input.id, name: 'John' })),
+ *
+ *   listUsers: procedure()
+ *     .query(async () => [{ id: '1', name: 'John' }]),
+ *
+ *   createUser: procedure()
+ *     .input(z.object({ name: z.string() }))
+ *     .mutation(async ({ input }) => ({ id: 'new', name: input.name })),
+ * });
+ *
+ * registerRestRoutes(app.server, [users], { prefix: '/api' });
+ *
+ * // Generates:
+ * // GET  /api/users/:id  -> getUser
+ * // GET  /api/users      -> listUsers
+ * // POST /api/users      -> createUser
+ * ```
+ */
+export function registerRestRoutes(server, collections, options = {}) {
+    const { prefix = '/api' } = options;
+    for (const collection of collections) {
+        const routes = generateRestRoutes(collection);
+        for (const route of routes) {
+            const fullPath = `${prefix}${route.path}`;
+            const handler = createRouteHandler(route);
+            // Register route based on method
+            switch (route.method) {
+                case 'GET':
+                    server.get(fullPath, handler);
+                    break;
+                case 'POST':
+                    server.post(fullPath, handler);
+                    break;
+                // MVP: Only GET and POST
+                // v1.1+ will add PUT, PATCH, DELETE
+                default:
+                    // Skip unsupported methods in MVP
+                    break;
+            }
+        }
+    }
+}
+/**
+ * Get a summary of routes that would be generated from collections
+ *
+ * Useful for debugging and documentation.
+ *
+ * @param collections - Procedure collections to analyze
+ * @param prefix - API prefix (default: '/api')
+ * @returns Array of route summaries
+ */
+export function getRouteSummary(collections, prefix = '/api') {
+    const summaries = [];
+    for (const collection of collections) {
+        const routes = generateRestRoutes(collection);
+        for (const route of routes) {
+            summaries.push({
+                method: route.method,
+                path: `${prefix}${route.path}`,
+                procedure: route.procedureName,
+                namespace: collection.namespace,
+            });
+        }
+    }
+    return summaries;
+}
+/**
+ * Creates a route registrar function for use with VeloxApp.routes()
+ *
+ * This is a convenience helper that returns a function suitable for
+ * passing to app.routes(), enabling a cleaner API.
+ *
+ * @param collections - Procedure collections to register
+ * @param options - Registration options
+ * @returns A function that registers routes on a Fastify instance
+ *
+ * @example
+ * ```typescript
+ * import { createVeloxApp } from '@veloxts/core';
+ * import { createRoutesRegistrar, defineProcedures, procedure } from '@veloxts/router';
+ *
+ * const users = defineProcedures('users', {
+ *   listUsers: procedure().query(async () => []),
+ * });
+ *
+ * const app = await createVeloxApp();
+ *
+ * app.routes(createRoutesRegistrar([users], { prefix: '/api' }));
+ *
+ * await app.start();
+ * ```
+ */
+export function createRoutesRegistrar(collections, options = {}) {
+    return (server) => {
+        registerRestRoutes(server, collections, options);
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/rest/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/rest/adapter.ts"],"names":[],"mappings":"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"}

package/dist/rest/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * REST adapter exports
+ *
+ * @module rest
+ */
+export type { RestAdapterOptions, RestRoute } from './adapter.js';
+export { createRoutesRegistrar, generateRestRoutes, getRouteSummary, registerRestRoutes, } from './adapter.js';
+export type { RestMapping } from './naming.js';
+export { buildRestPath, followsNamingConvention, inferResourceName, parseNamingConvention, } from './naming.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rest/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAElE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}