@veloxts/router 0.7.9 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @veloxts/router
 
+## 0.8.1
+
+### Patch Changes
+
+- feat: add business logic primitives for B2B SaaS apps
+- Updated dependencies
+  - @veloxts/core@0.8.1
+  - @veloxts/validation@0.8.1
+
+## 0.8.0
+
+### Minor Changes
+
+- feat(router): new simplified procedure builder
+
+### Patch Changes
+
+- Updated dependencies
+  - @veloxts/core@0.8.0
+  - @veloxts/validation@0.8.0
+
 ## 0.7.9
 
 ### Patch Changes

package/GUIDE.md

@@ -28,11 +28,9 @@ export const userProcedures = procedures('users', {
 ## Procedure API
 
 - `.input(schema)` - Validate input with Zod
-- `.output(schema)` - Validate output with Zod
-- `.expose(schema)` - Context-dependent output with resource schema
+- `.output(schema)` - Validate output with Zod schema or tagged resource view
 - `.use(middleware)` - Add middleware
 - `.guard(guard)` - Add authorization guard
-- `.guardNarrow(guard)` - Add guard with TypeScript type narrowing
 - `.rest({ method, path })` - Override REST path
 - `.query(handler)` - Finalize as read operation
 - `.mutation(handler)` - Finalize as write operation
@@ -405,7 +403,7 @@ console.table(routes);
 
 ## Resource API (Context-Dependent Outputs)
 
-The Resource API provides context-dependent output types using phantom types. Pass a resource schema to `.output()` instead of a Zod schema to define field visibility per access level.
+The Resource API provides context-dependent output types using phantom types. Pass a tagged resource view to `.output()` instead of a plain Zod schema to define field visibility per access level.
 
 ### Defining a Resource Schema
 
@@ -423,28 +421,27 @@ const UserSchema = resourceSchema()
   .build();
 ```
 
-### Automatic Projection (Simple Cases)
+### Automatic Projection with `.output()` and Guards
 
-The most elegant approach is to chain `.expose()` with a narrowing guard. The procedure executor automatically projects fields based on the guard's access level:
+The most elegant approach is to chain `.guard()` with `.output()` using a tagged resource view. The procedure builder uses the guard's access level to determine which fields to include:
 
 ```typescript
-import { authenticatedNarrow, adminNarrow } from '@veloxts/auth';
+import { authenticated, hasRole } from '@veloxts/auth';
 
 export const userProcedures = procedures('users', {
-  // Authenticated endpoint - auto-projects { id, name, email, createdAt }
+  // Authenticated endpoint - projects { id, name, email, createdAt }
   getProfile: procedure()
-    .guardNarrow(authenticatedNarrow)
-    .expose(UserSchema)
+    .guard(authenticated)
+    .output(UserSchema.authenticated)
     .input(z.object({ id: z.string().uuid() }))
     .query(async ({ input, ctx }) => {
-      // Just return the full data - projection is automatic!
       return ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
     }),
 
-  // Admin endpoint - auto-projects all fields
+  // Admin endpoint - projects all fields
   getFullProfile: procedure()
-    .guardNarrow(adminNarrow)
-    .expose(UserSchema)
+    .guard(hasRole('admin'))
+    .output(UserSchema.admin)
     .input(z.object({ id: z.string().uuid() }))
     .query(async ({ input, ctx }) => {
       return ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
@@ -454,14 +451,13 @@ export const userProcedures = procedures('users', {
 
 **How it works:**
 
-1. The `guardNarrow()` method accepts guards with an `accessLevel` property (`'public'`, `'authenticated'`, or `'admin'`)
-2. After the guard passes, the procedure executor tracks the highest access level
-3. When the handler returns, the executor automatically projects the result using the resource schema
-4. No manual `.forX()` calls needed - the output type is inferred at compile time
+1. The `.output()` method accepts both plain Zod schemas and tagged resource views (e.g., `UserSchema.authenticated`)
+2. When a tagged view is passed, the procedure executor automatically projects the handler's return value
+3. The output type is inferred at compile time from the tagged view
 
 **Benefits:**
 - Clean, declarative code - no projection logic in handlers
-- Type-safe - return types are inferred from guard + schema
+- Type-safe - return types are inferred from the tagged view
 - Less boilerplate - handlers just return data
 - Consistent - impossible to forget projection
 
@@ -516,10 +512,10 @@ export const userProcedures = procedures('users', {
 For arrays of items, use `resourceCollection()`:
 
 ```typescript
-// Automatic projection (simple cases)
+// Automatic projection with .output()
 const listUsers = procedure()
-  .guardNarrow(authenticatedNarrow)
-  .expose(UserSchema)
+  .guard(authenticated)
+  .output(UserSchema.authenticated)
   .query(async ({ ctx }) => {
     return ctx.db.user.findMany({ take: 50 });
   });
@@ -539,7 +535,7 @@ For manual projection with dynamic access level, use `.for(ctx)`:
 
 ```typescript
 const getUser = procedure()
-  .guardNarrow(authenticatedNarrow)
+  .guard(authenticated)
   .input(z.object({ id: z.string().uuid() }))
   .query(async ({ input, ctx }) => {
     const user = await ctx.db.user.findUniqueOrThrow({ where: { id: input.id } });
@@ -562,10 +558,10 @@ const getUser = procedure()
 The Resource API provides compile-time type safety:
 
 ```typescript
-// Automatic projection - type inferred from guard
+// Automatic projection - type inferred from tagged view
 const getProfile = procedure()
-  .guardNarrow(authenticatedNarrow)
-  .expose(UserSchema)
+  .guard(authenticated)
+  .output(UserSchema.authenticated)
   .query(async ({ ctx }) => {
     return ctx.db.user.findFirst();
   });
@@ -586,7 +582,7 @@ const adminResult = resource(user, UserSchema.admin);
 
 | Scenario | Approach |
 |----------|----------|
-| Guard determines access level | **Automatic** (`.guardNarrow().output()`) |
+| Guard determines access level | **Automatic** (`.guard().output(Schema.level)`) |
 | Public endpoints (no guard) | Tagged view (`UserSchema.public`) |
 | Conditional/dynamic projection | Tagged view or `.for(ctx)` in handler |
 | Simple, declarative code | **Automatic** |
@@ -603,43 +599,29 @@ const getUser = procedure()
   .query(handler);
 ```
 
-## Guard Type Narrowing (Experimental)
+## Guard Type Narrowing
 
-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:
+Guards like `authenticated` and `hasRole()` both enforce authorization and narrow the context type. After a guard passes, TypeScript knows `ctx.user` is non-null:
 
 ```typescript
-import { authenticatedNarrow, hasRoleNarrow } from '@veloxts/auth';
+import { authenticated, hasRole } from '@veloxts/auth';
 
 // ctx.user is guaranteed non-null after guard passes
 const getProfile = procedure()
-  .guardNarrow(authenticatedNarrow)
+  .guard(authenticated)
   .query(({ ctx }) => {
     return { email: ctx.user.email }; // No null check needed!
   });
 
-// Chain multiple narrowing guards
+// Chain multiple guards
 const adminAction = procedure()
-  .guardNarrow(authenticatedNarrow)
-  .guardNarrow(hasRoleNarrow('admin'))
+  .guard(authenticated)
+  .guard(hasRole('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:

package/README.md

@@ -1,6 +1,6 @@
 # @veloxts/router
 
-> **Early Access (v0.7.x)**
+> **Early Access (v0.8.x)**
 
 Procedure-based routing for VeloxTS Framework - provides hybrid tRPC and REST adapters with naming convention-based HTTP method inference. Learn more at [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox).
 

package/dist/index.d.ts

@@ -39,14 +39,16 @@
  */
 /** Router package version */
 export declare const ROUTER_VERSION: string;
-export type { CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureInput, InferProcedureOutput, Middleware, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceChain, ParentResourceConfig, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, } from './types.js';
+export type { AfterHandler, CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureErrors, InferProcedureInput, InferProcedureOutput, Middleware, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceChain, ParentResourceConfig, PolicyActionLike, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, TransactionalOptions, } from './types.js';
 export { PROCEDURE_METHOD_MAP, } from './types.js';
 export type { GuardErrorResponse, RouterErrorCode } from './errors.js';
 export { GuardError, isGuardError } from './errors.js';
 export type { DefineProceduresOptions, } from './procedure/builder.js';
 export { defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection, procedure, procedures, } from './procedure/builder.js';
+export type { PipelineStep, RevertAction, StepOptions } from './procedure/pipeline.js';
+export { defineRevert, defineStep } from './procedure/pipeline.js';
 export { createProcedure, typedProcedure } from './procedure/factory.js';
-export type { BuilderRuntimeState, InferProcedures, InferSchemaOutput, ProcedureBuilder, ProcedureBuilderState, ProcedureDefinitions, ValidSchema, } from './procedure/types.js';
+export type { BuilderRuntimeState, InferOutputSchema, InferProcedures, InferSchemaOutput, PostHandlerBuilder, ProcedureBuilder, ProcedureBuilderState, ProcedureDefinitions, ValidOutputSchema, 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';
@@ -114,4 +116,4 @@ export type { AccessLevel, AccessLevelConfig, ADMIN, AdminOutput, AdminTaggedCon
  * });
  * ```
  */
-export { defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, resource, resourceCollection, resourceSchema, } from './resource/index.js';
+export { defaultAccess, defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, resource, resourceCollection, resourceSchema, } from './resource/index.js';

package/dist/index.js

@@ -51,6 +51,7 @@ export {
 // Builder functions
 defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection, procedure, procedures, // Short alias for defineProcedures
  } from './procedure/builder.js';
+export { defineRevert, defineStep } from './procedure/pipeline.js';
 // ============================================================================
 // Router Utilities
 // ============================================================================
@@ -110,7 +111,7 @@ swaggerPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/ind
  */
 export { 
 // Access level configuration
-defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, 
+defaultAccess, defineAccessLevels, getAccessibleLevels, getVisibilityForTag, isFieldVisibleToLevel, isResourceSchema, 
 // Visibility
 isVisibleAtLevel, Resource, ResourceCollection, ResourceSchemaBuilder, 
 // Resource instances

package/dist/openapi/generator.js

@@ -7,7 +7,7 @@
  */
 import { generateRestRoutes } from '../rest/adapter.js';
 import { buildParameters, convertToOpenAPIPath, joinPaths } from './path-extractor.js';
-import { removeSchemaProperties, resourceSchemaToJsonSchema, zodSchemaToJsonSchema, } from './schema-converter.js';
+import { removeSchemaProperties, resourceSchemaToJsonSchema, resourceSchemaToJsonSchemaForBranching, zodSchemaToJsonSchema, } from './schema-converter.js';
 import { extractUsedSecuritySchemes, filterUsedSecuritySchemes, guardsToSecurity, mergeSecuritySchemes, } from './security-mapper.js';
 // ============================================================================
 // Main Generator
@@ -150,6 +150,10 @@ function generateOperation(route, namespace, options) {
     if (procedure.outputSchema) {
         outputSchema = zodSchemaToJsonSchema(procedure.outputSchema);
     }
+    else if (procedure._handlerMap && procedure._resourceSchema) {
+        // Level 3: branched procedure — include all fields, non-public fields optional
+        outputSchema = resourceSchemaToJsonSchemaForBranching(procedure._resourceSchema);
+    }
     else if (procedure._resourceSchema) {
         const level = procedure._resourceLevel ?? 'public';
         outputSchema = resourceSchemaToJsonSchema(procedure._resourceSchema, level);

package/dist/openapi/schema-converter.d.ts

@@ -113,3 +113,14 @@ export declare function schemaHasProperties(schema: JSONSchema | undefined): boo
  * @returns JSON Schema with only the fields visible at the given level
  */
 export declare function resourceSchemaToJsonSchema(schema: ResourceSchema, level?: string): JSONSchema;
+/**
+ * Converts a resource schema to JSON Schema for Level 3 branched procedures
+ *
+ * Includes ALL fields from the resource schema. Fields visible at the
+ * lowest level (first in the levels array) are marked as required;
+ * higher-level-only fields are optional.
+ *
+ * @param schema - The resource schema (must have _levelConfig for custom levels)
+ * @returns JSON Schema with all fields, non-public fields optional
+ */
+export declare function resourceSchemaToJsonSchemaForBranching(schema: ResourceSchema): JSONSchema;

package/dist/openapi/schema-converter.js

@@ -308,3 +308,50 @@ export function resourceSchemaToJsonSchema(schema, level = 'public') {
         ...(required.length > 0 ? { required } : {}),
     };
 }
+/**
+ * Converts a resource schema to JSON Schema for Level 3 branched procedures
+ *
+ * Includes ALL fields from the resource schema. Fields visible at the
+ * lowest level (first in the levels array) are marked as required;
+ * higher-level-only fields are optional.
+ *
+ * @param schema - The resource schema (must have _levelConfig for custom levels)
+ * @returns JSON Schema with all fields, non-public fields optional
+ */
+export function resourceSchemaToJsonSchemaForBranching(schema) {
+    const properties = {};
+    const required = [];
+    // Determine the lowest (most accessible) level
+    const schemaWithConfig = schema;
+    const lowestLevel = schemaWithConfig._levelConfig?.levels[0] ?? 'public';
+    for (const field of schema.fields) {
+        const runtimeField = field;
+        if (field.nestedSchema) {
+            const nestedJsonSchema = resourceSchemaToJsonSchemaForBranching(field.nestedSchema);
+            if (field.cardinality === 'many') {
+                properties[field.name] = { type: 'array', items: nestedJsonSchema };
+            }
+            else {
+                properties[field.name] = { ...nestedJsonSchema, nullable: true };
+            }
+        }
+        else if (field.schema) {
+            const fieldJsonSchema = zodSchemaToJsonSchema(field.schema);
+            if (fieldJsonSchema) {
+                properties[field.name] = fieldJsonSchema;
+            }
+        }
+        else {
+            properties[field.name] = {};
+        }
+        // Only public/lowest-level fields are required
+        if (isFieldVisibleToLevel(runtimeField, lowestLevel)) {
+            required.push(field.name);
+        }
+    }
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    };
+}

package/dist/procedure/builder.d.ts

@@ -41,7 +41,7 @@ import type { InferProcedures, ProcedureBuilder, ProcedureDefinitions } from './
  *   });
  * ```
  */
-export declare function procedure<TContext extends BaseContext = BaseContext>(): ProcedureBuilder<unknown, unknown, TContext>;
+export declare function procedure<TContext extends BaseContext = BaseContext>(): ProcedureBuilder<unknown, unknown, TContext, never>;
 /**
  * Options for defining a procedure collection
  */