@veloxts/router 0.6.68 → 0.6.70

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @veloxts/router
 
+## 0.6.70
+
+### Patch Changes
+
+- ### feat(auth): Unified Adapter-Only Architecture
+
+  **New Features:**
+
+  - Add `JwtAdapter` implementing the `AuthAdapter` interface for unified JWT authentication
+  - Add `jwtAuth()` convenience function for direct adapter usage with optional built-in routes (`/api/auth/refresh`, `/api/auth/logout`)
+  - Add `AuthContext` discriminated union (`NativeAuthContext | AdapterAuthContext`) for type-safe auth mode handling
+  - Add double-registration protection to prevent conflicting auth system setups
+  - Add shared decoration utilities (`decorateAuth`, `setRequestAuth`, `checkDoubleRegistration`)
+
+  **Architecture Changes:**
+
+  - `authPlugin` now uses `JwtAdapter` internally - all authentication flows through the adapter pattern
+  - Single code path for authentication (no more dual native/adapter modes)
+  - `authContext.authMode` is now always `'adapter'` with `providerId='jwt'` when using `authPlugin`
+
+  **Breaking Changes:**
+
+  - Remove deprecated `LegacySessionConfig` interface (use `sessionMiddleware` instead)
+  - Remove deprecated `session` field from `AuthConfig`
+  - `User` interface no longer has index signature (extend via declaration merging)
+
+  **Type Safety Improvements:**
+
+  - `AuthContext` discriminated union enables exhaustive type narrowing based on `authMode`
+  - Export `NativeAuthContext` and `AdapterAuthContext` types for explicit typing
+
+  **Migration:**
+
+  - Existing `authPlugin` usage remains backward-compatible
+  - If checking `authContext.token`, use `authContext.session` instead (token stored in session for adapter mode)
+
+- Updated dependencies
+  - @veloxts/core@0.6.70
+  - @veloxts/validation@0.6.70
+
+## 0.6.69
+
+### Patch Changes
+
+- implement user feedback improvements across packages
+
+  ## Summary
+
+  Addresses 9 user feedback items to improve DX, reduce boilerplate, and eliminate template duplications.
+
+  ### Phase 1: Validation Helpers (`@veloxts/validation`)
+
+  - Add `prismaDecimal()`, `prismaDecimalNullable()`, `prismaDecimalOptional()` for Prisma Decimal → number conversion
+  - Add `dateToIso`, `dateToIsoNullable`, `dateToIsoOptional` aliases for consistency
+
+  ### Phase 2: Template Deduplication (`@veloxts/auth`)
+
+  - Export `createEnhancedTokenStore()` with token revocation and refresh token reuse detection
+  - Export `parseUserRoles()` and `DEFAULT_ALLOWED_ROLES`
+  - Fix memory leak: track pending timeouts for proper cleanup on `destroy()`
+  - Update templates to import from `@veloxts/auth` instead of duplicating code
+  - Fix jwtManager singleton pattern in templates
+
+  ### Phase 3: Router Helpers (`@veloxts/router`)
+
+  - Add `createRouter()` returning `{ collections, router }` for DRY setup
+  - Add `toRouter()` for router-only use cases
+  - Update all router templates to use `createRouter()`
+
+  ### Phase 4: Guard Type Narrowing - Experimental (`@veloxts/auth`, `@veloxts/router`)
+
+  - Add `NarrowingGuard` interface with phantom `_narrows` type
+  - Add `authenticatedNarrow` and `hasRoleNarrow()` guards
+  - Add `guardNarrow()` method to `ProcedureBuilder` for context narrowing
+  - Enables `ctx.user` to be non-null after guard passes
+
+  ### Phase 5: Documentation (`@veloxts/router`)
+
+  - Document `.rest()` override patterns
+  - Document `createRouter()` helper usage
+  - Document `guardNarrow()` experimental API
+  - Add schema browser-safety patterns for RSC apps
+
+- Updated dependencies
+  - @veloxts/core@0.6.69
+  - @veloxts/validation@0.6.69
+
 ## 0.6.68
 
 ### Patch Changes

package/GUIDE.md

@@ -48,6 +48,81 @@ Procedure names auto-map to HTTP methods:
 | `patch*` | PATCH | `/:id` |
 | `delete*`, `remove*` | DELETE | `/:id` |
 
+## REST Overrides with `.rest()`
+
+When naming conventions don't fit your use case, use `.rest()` as an escape hatch:
+
+```typescript
+const userProcedures = procedures('users', {
+  // Override method only
+  activateUser: procedure()
+    .input(z.object({ id: z.string().uuid() }))
+    .rest({ method: 'POST' })  // Would be PUT by default
+    .mutation(async ({ input, ctx }) => {
+      return ctx.db.user.update({ where: { id: input.id }, data: { active: true } });
+    }),
+
+  // Override path with parameters
+  getUserByEmail: procedure()
+    .input(z.object({ email: z.string().email() }))
+    .rest({ method: 'GET', path: '/users/by-email/:email' })
+    .query(async ({ input, ctx }) => {
+      return ctx.db.user.findUnique({ where: { email: input.email } });
+    }),
+
+  // Custom action endpoint
+  sendPasswordReset: procedure()
+    .input(z.object({ userId: z.string().uuid() }))
+    .rest({ method: 'POST', path: '/users/:userId/password-reset' })
+    .mutation(async ({ input, ctx }) => {
+      // ...
+    }),
+});
+```
+
+**Important**: Do NOT include the API prefix in `.rest()` paths:
+
+```typescript
+// Correct - prefix is added automatically
+.rest({ method: 'POST', path: '/users/:id/activate' })
+
+// Wrong - results in /api/api/users/:id/activate
+.rest({ method: 'POST', path: '/api/users/:id/activate' })
+```
+
+## Router Helper (`createRouter`)
+
+Use `createRouter()` to eliminate redundancy when defining both collections and router:
+
+```typescript
+import { createRouter, extractRoutes } from '@veloxts/router';
+
+// Before (redundant):
+// export const collections = [healthProcedures, userProcedures];
+// export const router = {
+//   health: healthProcedures,
+//   users: userProcedures,
+// };
+
+// After (DRY):
+export const { collections, router } = createRouter(
+  healthProcedures,
+  userProcedures
+);
+
+export type AppRouter = typeof router;
+export const routes = extractRoutes(collections);
+```
+
+If you only need the router object (not collections), use `toRouter()`:
+
+```typescript
+import { toRouter } from '@veloxts/router';
+
+export const router = toRouter(healthProcedures, userProcedures);
+// Result: { health: healthProcedures, users: userProcedures }
+```
+
 ## Registering Routes
 
 ```typescript
@@ -320,6 +395,109 @@ const getUser = procedure()
   .query(handler);
 ```
 
+## Guard Type Narrowing (Experimental)
+
+When using guards like `authenticated`, TypeScript doesn't know that `ctx.user` is guaranteed non-null after the guard passes. Use `guardNarrow()` to narrow the context type:
+
+```typescript
+import { authenticatedNarrow, hasRoleNarrow } from '@veloxts/auth';
+
+// ctx.user is guaranteed non-null after guard passes
+const getProfile = procedure()
+  .guardNarrow(authenticatedNarrow)
+  .query(({ ctx }) => {
+    return { email: ctx.user.email }; // No null check needed!
+  });
+
+// Chain multiple narrowing guards
+const adminAction = procedure()
+  .guardNarrow(authenticatedNarrow)
+  .guardNarrow(hasRoleNarrow('admin'))
+  .mutation(({ ctx }) => {
+    // ctx.user is non-null with roles
+  });
+```
+
+**Note**: This API is experimental. The current stable alternative is to use middleware for context extension:
+
+```typescript
+const getProfile = procedure()
+  .guard(authenticated)
+  .use(async ({ ctx, next }) => {
+    if (!ctx.user) throw new Error('Unreachable');
+    return next({ ctx: { user: ctx.user } });
+  })
+  .query(({ ctx }) => {
+    // ctx.user is non-null via middleware
+  });
+```
+
+## Schema Browser-Safety
+
+When building full-stack apps, schemas may be imported on both server and client. Avoid importing server-only dependencies in schema files:
+
+### Safe Pattern: Pure Zod Schemas
+
+```typescript
+// src/schemas/user.ts - Safe for browser import
+import { z } from '@veloxts/validation';
+
+export const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.string().datetime(),
+});
+
+export type User = z.infer<typeof UserSchema>;
+```
+
+### Unsafe Pattern: Server Dependencies in Schemas
+
+```typescript
+// DO NOT import server-only modules in schema files
+import { db } from '@/database'; // BAD - pulls Prisma into client bundle
+
+export const UserSchema = z.object({
+  // ...
+});
+```
+
+### Separating Input/Output Schemas
+
+Keep input schemas (for mutations) separate from output schemas (with transforms):
+
+```typescript
+// src/schemas/user.input.ts - For mutations
+export const CreateUserInput = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+
+// src/schemas/user.output.ts - May have transforms
+import { dateToIso, prismaDecimal } from '@veloxts/validation';
+
+export const UserOutput = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  email: z.string().email(),
+  balance: prismaDecimal(),      // Transforms Prisma Decimal
+  createdAt: dateToIso(),        // Transforms Date to string
+});
+```
+
+### Type-Only Imports
+
+In server actions, use type-only imports to avoid bundling server code:
+
+```typescript
+// GOOD - Type stripped at build time
+import type { User } from '@/schemas/user';
+
+// BAD - Pulls in full module graph
+import { User } from '@/schemas/user';
+```
+
 ## Learn More
 
 See [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox) for complete documentation.

package/dist/index.d.ts

@@ -47,6 +47,8 @@ export type { DefineProceduresOptions, } from './procedure/builder.js';
 export { defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection, procedure, procedures, } from './procedure/builder.js';
 export { createProcedure, typedProcedure } from './procedure/factory.js';
 export type { BuilderRuntimeState, InferProcedures, InferSchemaOutput, ProcedureBuilder, ProcedureBuilderState, ProcedureDefinitions, ValidSchema, } from './procedure/types.js';
+export type { RouterResult } from './router-utils.js';
+export { createRouter, toRouter } from './router-utils.js';
 export type { NamingWarning, NamingWarningType, WarningConfig, WarningOption } from './warnings.js';
 export { analyzeNamingConvention, isDevelopment, normalizeWarningOption } from './warnings.js';
 export type { ExtractRoutesType, RestAdapterOptions, RestMapping, RestRoute, RouteMap, } from './rest/index.js';

package/dist/index.js

@@ -51,8 +51,12 @@ export {
 // Builder functions
 defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection, procedure, procedures, // Short alias for defineProcedures
  } from './procedure/builder.js';
+// ============================================================================
+// Router Utilities
+// ============================================================================
 // Typed procedure factory
 export { createProcedure, typedProcedure } from './procedure/factory.js';
+export { createRouter, toRouter } from './router-utils.js';
 export { analyzeNamingConvention, isDevelopment, normalizeWarningOption } from './warnings.js';
 export { buildNestedRestPath, buildRestPath, extractRoutes, followsNamingConvention, generateRestRoutes, getRouteSummary, inferResourceName, parseNamingConvention, registerRestRoutes, rest, } from './rest/index.js';
 export { 

package/dist/procedure/builder.js

@@ -175,6 +175,18 @@ function createBuilder(state) {
                 guards: [...state.guards, guardDef],
             });
         },
+        /**
+         * Adds an authorization guard with type narrowing (EXPERIMENTAL)
+         *
+         * Unlike `guard()`, this method narrows the context type based on
+         * what the guard guarantees after it passes.
+         */
+        guardNarrow(guardDef) {
+            return createBuilder({
+                ...state,
+                guards: [...state.guards, guardDef],
+            });
+        },
         /**
          * Sets REST route override
          */

package/dist/procedure/types.d.ts

@@ -170,6 +170,41 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      * ```
      */
     guard<TGuardContext extends Partial<TContext>>(guard: GuardLike<TGuardContext>): ProcedureBuilder<TInput, TOutput, TContext>;
+    /**
+     * Adds an authorization guard with type narrowing (EXPERIMENTAL)
+     *
+     * Unlike `.guard()`, this method narrows the context type based on
+     * what the guard guarantees. For example, `authenticatedNarrow` narrows
+     * `ctx.user` from `User | undefined` to `User`.
+     *
+     * **EXPERIMENTAL**: This API may change. Consider using middleware
+     * for context type extension as the current stable alternative.
+     *
+     * @template TNarrowedContext - The context type guaranteed by the guard
+     * @param guard - Narrowing guard definition with `_narrows` type
+     * @returns New builder with narrowed context type
+     *
+     * @example
+     * ```typescript
+     * import { authenticatedNarrow, hasRoleNarrow } from '@veloxts/auth';
+     *
+     * // ctx.user is guaranteed non-null after guard passes
+     * procedure()
+     *   .guardNarrow(authenticatedNarrow)
+     *   .query(({ ctx }) => {
+     *     return { email: ctx.user.email }; // No null check needed!
+     *   });
+     *
+     * // Chain multiple narrowing guards
+     * procedure()
+     *   .guardNarrow(authenticatedNarrow)
+     *   .guardNarrow(hasRoleNarrow('admin'))
+     *   .mutation(({ ctx }) => { ... });
+     * ```
+     */
+    guardNarrow<TNarrowedContext>(guard: GuardLike<Partial<TContext>> & {
+        readonly _narrows: TNarrowedContext;
+    }): ProcedureBuilder<TInput, TOutput, TContext & TNarrowedContext>;
     /**
      * Configures REST route override
      *

package/dist/router-utils.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Router Utility Functions
+ *
+ * Helpers for creating type-safe router definitions from procedure collections.
+ *
+ * @module router-utils
+ */
+import type { ProcedureCollection, ProcedureRecord } from './types.js';
+/**
+ * Extracts the namespace from a ProcedureCollection as a literal type
+ */
+type ExtractNamespace<T> = T extends ProcedureCollection<infer _P> & {
+    readonly namespace: infer N;
+} ? N extends string ? N : never : never;
+/**
+ * Creates a union of namespaces from an array of ProcedureCollections
+ */
+type CollectionNamespaces<T extends readonly ProcedureCollection[]> = {
+    [K in keyof T]: ExtractNamespace<T[K]>;
+}[number];
+/**
+ * Maps namespaces to their corresponding ProcedureCollections
+ */
+type RouterFromCollections<T extends readonly ProcedureCollection[]> = {
+    [K in CollectionNamespaces<T>]: Extract<T[number], {
+        namespace: K;
+    }>;
+};
+/**
+ * Result type from createRouter
+ */
+export interface RouterResult<T extends readonly ProcedureCollection[]> {
+    /** Array of procedure collections for routing */
+    readonly collections: T;
+    /** Object mapping namespaces to procedure collections */
+    readonly router: RouterFromCollections<T>;
+}
+/**
+ * Creates both collections array and router object from procedure collections.
+ *
+ * This helper eliminates the redundancy of defining both `collections` and `router`
+ * separately. The router object is automatically keyed by each collection's namespace.
+ *
+ * @param collections - Procedure collections to include in the router
+ * @returns Object containing both `collections` array and `router` object
+ *
+ * @example
+ * ```typescript
+ * import { createRouter, extractRoutes } from '@veloxts/router';
+ * import { healthProcedures } from './procedures/health.js';
+ * import { userProcedures } from './procedures/users.js';
+ *
+ * // Before (redundant):
+ * // export const collections = [healthProcedures, userProcedures];
+ * // export const router = {
+ * //   health: healthProcedures,
+ * //   users: userProcedures,
+ * // };
+ *
+ * // After (DRY):
+ * export const { collections, router } = createRouter(
+ *   healthProcedures,
+ *   userProcedures
+ * );
+ *
+ * export type AppRouter = typeof router;
+ * export const routes = extractRoutes(collections);
+ * ```
+ */
+export declare function createRouter<T extends ProcedureCollection<ProcedureRecord>[]>(...collections: T): RouterResult<T>;
+/**
+ * Creates a router object from procedure collections.
+ *
+ * This is an alternative to `createRouter` when you only need the router object
+ * and not the collections array. Useful for frontend-only type imports.
+ *
+ * @param collections - Procedure collections to include in the router
+ * @returns Object mapping namespaces to procedure collections
+ *
+ * @example
+ * ```typescript
+ * import { toRouter } from '@veloxts/router';
+ *
+ * export const router = toRouter(healthProcedures, userProcedures);
+ * // Result: { health: healthProcedures, users: userProcedures }
+ *
+ * export type AppRouter = typeof router;
+ * ```
+ */
+export declare function toRouter<T extends ProcedureCollection<ProcedureRecord>[]>(...collections: T): RouterFromCollections<T>;
+export {};

package/dist/router-utils.js

@@ -0,0 +1,73 @@
+/**
+ * Router Utility Functions
+ *
+ * Helpers for creating type-safe router definitions from procedure collections.
+ *
+ * @module router-utils
+ */
+// ============================================================================
+// Router Creation
+// ============================================================================
+/**
+ * Creates both collections array and router object from procedure collections.
+ *
+ * This helper eliminates the redundancy of defining both `collections` and `router`
+ * separately. The router object is automatically keyed by each collection's namespace.
+ *
+ * @param collections - Procedure collections to include in the router
+ * @returns Object containing both `collections` array and `router` object
+ *
+ * @example
+ * ```typescript
+ * import { createRouter, extractRoutes } from '@veloxts/router';
+ * import { healthProcedures } from './procedures/health.js';
+ * import { userProcedures } from './procedures/users.js';
+ *
+ * // Before (redundant):
+ * // export const collections = [healthProcedures, userProcedures];
+ * // export const router = {
+ * //   health: healthProcedures,
+ * //   users: userProcedures,
+ * // };
+ *
+ * // After (DRY):
+ * export const { collections, router } = createRouter(
+ *   healthProcedures,
+ *   userProcedures
+ * );
+ *
+ * export type AppRouter = typeof router;
+ * export const routes = extractRoutes(collections);
+ * ```
+ */
+export function createRouter(...collections) {
+    const router = Object.fromEntries(collections.map((collection) => [collection.namespace, collection]));
+    return {
+        // Cast required: rest params are typed as T[] but we need to preserve
+        // the exact tuple type T for proper namespace inference in RouterResult
+        collections: collections,
+        router,
+    };
+}
+/**
+ * Creates a router object from procedure collections.
+ *
+ * This is an alternative to `createRouter` when you only need the router object
+ * and not the collections array. Useful for frontend-only type imports.
+ *
+ * @param collections - Procedure collections to include in the router
+ * @returns Object mapping namespaces to procedure collections
+ *
+ * @example
+ * ```typescript
+ * import { toRouter } from '@veloxts/router';
+ *
+ * export const router = toRouter(healthProcedures, userProcedures);
+ * // Result: { health: healthProcedures, users: userProcedures }
+ *
+ * export type AppRouter = typeof router;
+ * ```
+ */
+export function toRouter(...collections) {
+    return Object.fromEntries(collections.map((collection) => [collection.namespace, collection]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/router",
-  "version": "0.6.68",
+  "version": "0.6.70",
   "description": "Procedure definitions with tRPC and REST routing for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -40,8 +40,8 @@
     "@trpc/server": "11.8.0",
     "fastify": "5.6.2",
     "zod-to-json-schema": "3.24.5",
-    "@veloxts/core": "0.6.68",
-    "@veloxts/validation": "0.6.68"
+    "@veloxts/core": "0.6.70",
+    "@veloxts/validation": "0.6.70"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.16",