@veloxts/router 0.6.97 → 0.6.99

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @veloxts/router
 
+## 0.6.99
+
+### Patch Changes
+
+- Updates to documentation and mark as beta 0.6.x
+- Updated dependencies
+  - @veloxts/core@0.6.99
+  - @veloxts/validation@0.6.99
+
+## 0.6.98
+
+### Patch Changes
+
+- feat(router): nested resource schema relations with .hasOne() / .hasMany()
+- Updated dependencies
+  - @veloxts/core@0.6.98
+  - @veloxts/validation@0.6.98
+
 ## 0.6.97
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # @veloxts/router
 
-> **Early Preview (v0.6.x)** - APIs are stabilizing but may still change. Do not use in production yet.
+> **Beta (v0.6.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

@@ -83,7 +83,7 @@ export { serve } from './expose.js';
  */
 export type { BuildParametersOptions, BuildParametersResult, GuardMappingOptions, JSONSchema, OpenAPIComponents, OpenAPIContact, OpenAPIEncoding, OpenAPIExample, OpenAPIExternalDocs, OpenAPIGeneratorOptions, OpenAPIHeader, OpenAPIHttpMethod, OpenAPIInfo, OpenAPILicense, OpenAPILink, OpenAPIMediaType, OpenAPIOAuthFlow, OpenAPIOAuthFlows, OpenAPIOperation, OpenAPIParameter, OpenAPIPathItem, OpenAPIRequestBody, OpenAPIResponse, OpenAPISecurityRequirement, OpenAPISecurityScheme, OpenAPIServer, OpenAPISpec, OpenAPITag, ParameterIn, QueryParamExtractionOptions, RouteInfo, SchemaConversionOptions, SecuritySchemeType, SwaggerUIConfig, SwaggerUIHtmlOptions, SwaggerUIPluginOptions, } from './openapi/index.js';
 export { buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath, createSecurityRequirement, createStringSchema, createSwaggerUI, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, DEFAULT_UI_CONFIG, escapeHtml, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, generateOpenApiSpec, generateSwaggerUIHtml, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, registerDocs, removeSchemaProperties, SWAGGER_UI_CDN, schemaHasProperties, swaggerUIPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';
-export type { AccessLevel, ADMIN, AdminOutput, AdminTaggedContext, ANONYMOUS, AnonymousOutput, AnonymousTaggedContext, AnyResourceOutput, AUTHENTICATED, AuthenticatedOutput, AuthenticatedTaggedContext, ContextTag, ExtractTag, HasTag, IfAdmin, IfAuthenticated, InferResourceData, InferResourceOutput, IsVisibleToTag, OutputForTag, ResourceField, ResourceSchema, RuntimeField, TaggedContext, VisibilityLevel, WithTag, } from './resource/index.js';
+export type { AccessLevel, ADMIN, AdminOutput, AdminTaggedContext, ANONYMOUS, AnonymousOutput, AnonymousTaggedContext, AnyResourceOutput, AUTHENTICATED, AuthenticatedOutput, AuthenticatedTaggedContext, BuilderField, ContextTag, ExtractTag, HasTag, IfAdmin, IfAuthenticated, InferResourceData, InferResourceOutput, IsVisibleToTag, OutputForTag, RelationField, ResourceField, ResourceSchema, RuntimeField, TaggedContext, VisibilityLevel, WithTag, } from './resource/index.js';
 /**
  * Resource API for context-dependent output types using phantom types.
  *

package/dist/procedure/builder.js

@@ -10,7 +10,7 @@
 import { ConfigurationError, logWarning } from '@veloxts/core';
 import { GuardError } from '../errors.js';
 import { createMiddlewareExecutor, executeMiddlewareChain } from '../middleware/chain.js';
-import { Resource, } from '../resource/index.js';
+import { isTaggedResourceSchema, Resource, } from '../resource/index.js';
 import { deriveParentParamName } from '../utils/pluralization.js';
 import { analyzeNamingConvention, isDevelopment, normalizeWarningOption, } from '../warnings.js';
 // ============================================================================
@@ -202,15 +202,35 @@ function createBuilder(state) {
         /**
          * Sets the output type based on a resource schema
          *
-         * This method stores the resource schema for potential OpenAPI generation
-         * and narrows the output type based on the context's phantom tag.
+         * Accepts either a plain `ResourceSchema` or a tagged schema
+         * (e.g., `UserSchema.authenticated`) for declarative auto-projection.
+         *
+         * @example
+         * ```typescript
+         * // Tagged schema — auto-projects to authenticated fields
+         * procedure()
+         *   .guard(authenticated)
+         *   .resource(UserSchema.authenticated)
+         *   .query(handler);
+         *
+         * // Plain schema — defaults to public, or derives from guardNarrow
+         * procedure()
+         *   .resource(UserSchema)
+         *   .query(handler);
+         * ```
+         */
+        /**
+         * Sets the output type based on a resource schema
+         *
+         * Accepts either a plain `ResourceSchema` or a tagged schema
+         * (e.g., `UserSchema.authenticated`) for declarative auto-projection.
          */
         resource(schema) {
-            // Store the resource schema for OpenAPI generation
-            // The actual output type is computed at the type level
+            const level = isTaggedResourceSchema(schema) ? schema._level : undefined;
             return createBuilder({
                 ...state,
                 resourceSchema: schema,
+                resourceLevel: level,
             });
         },
     };
@@ -248,6 +268,8 @@ function compileProcedure(type, handler, state) {
         _precompiledExecutor: precompiledExecutor,
         // Store resource schema for auto-projection
         _resourceSchema: state.resourceSchema,
+        // Store explicit resource level from tagged schema (e.g., UserSchema.authenticated)
+        _resourceLevel: state.resourceLevel,
     };
 }
 /**
@@ -460,17 +482,24 @@ export async function executeProcedure(procedure, rawInput, ctx) {
     // Step 4: Auto-project if resource schema is set
     if (procedure._resourceSchema) {
         const schema = procedure._resourceSchema;
-        const resourceInstance = new Resource(result, schema);
-        // Project based on access level
-        switch (accessLevel) {
-            case 'admin':
-                result = resourceInstance.forAdmin();
-                break;
-            case 'authenticated':
-                result = resourceInstance.forAuthenticated();
-                break;
-            default:
-                result = resourceInstance.forAnonymous();
+        // Prefer explicit level from tagged schema over guard-derived level
+        const finalLevel = procedure._resourceLevel ?? accessLevel;
+        const projectOne = (item) => {
+            const r = new Resource(item, schema);
+            switch (finalLevel) {
+                case 'admin':
+                    return r.forAdmin();
+                case 'authenticated':
+                    return r.forAuthenticated();
+                default:
+                    return r.forAnonymous();
+            }
+        };
+        if (Array.isArray(result)) {
+            result = result.map((item) => projectOne(item));
+        }
+        else {
+            result = projectOne(result);
         }
     }
     // Step 5: Validate output if schema provided

package/dist/procedure/types.d.ts

@@ -11,8 +11,8 @@
  */
 import type { BaseContext } from '@veloxts/core';
 import type { ZodType, ZodTypeDef } from 'zod';
-import type { OutputForTag, ResourceSchema } from '../resource/index.js';
-import type { ContextTag, ExtractTag, TaggedContext } from '../resource/tags.js';
+import type { OutputForTag, ResourceSchema, TaggedResourceSchema } from '../resource/index.js';
+import type { ContextTag, ExtractTag, LevelToTag, TaggedContext } from '../resource/tags.js';
 import type { CompiledProcedure, GuardLike, MiddlewareFunction, ParentResourceConfig, ProcedureHandler, RestRouteOverride } from '../types.js';
 /**
  * Internal state type that accumulates type information through the builder chain
@@ -372,34 +372,31 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      */
     mutation(handler: ProcedureHandler<TInput, TOutput, TContext>): CompiledProcedure<TInput, TOutput, TContext, 'mutation'>;
     /**
-     * Sets the output type based on a resource schema and context tag
+     * Sets the output type based on a resource schema
      *
-     * This method enables context-dependent output types using phantom types.
-     * The output type is computed based on the fields visible to the context's
-     * access level (anonymous, authenticated, or admin).
+     * Accepts either a tagged schema (e.g., `UserSchema.authenticated`) for
+     * explicit auto-projection, or a plain schema for backward compatibility.
      *
-     * **IMPORTANT**: This method is for type documentation only. You must still
-     * call `.forAnonymous()`, `.forAuthenticated()`, or `.forAdmin()` on the
-     * resource instance in your handler to perform the actual field filtering.
-     *
-     * @template TSchema - The resource schema type
-     * @param schema - The resource schema defining field visibility
-     * @returns New builder with output type set based on context's tag
+     * When a tagged schema is used, the output type is computed from the
+     * tag's access level. When a plain schema is used, the output type is
+     * derived from the context's phantom tag (set by `guardNarrow`).
      *
      * @example
      * ```typescript
-     * // The output type is automatically computed from the context tag
-     * const getUser = procedure()
-     *   .guardNarrow(authenticatedNarrow) // Tags context with AUTHENTICATED
-     *   .input(z.object({ id: z.string() }))
-     *   .resource(UserSchema) // Output type: { id, name, email }
-     *   .query(async ({ input, ctx }) => {
-     *     const user = await ctx.db.user.findUnique({ where: { id: input.id } });
-     *     return resource(user, UserSchema).forAuthenticated();
-     *   });
+     * // Tagged schema — explicit projection level (recommended)
+     * procedure()
+     *   .guard(authenticated)
+     *   .resource(UserSchema.authenticated)
+     *   .query(async ({ ctx }) => ctx.db.user.findUnique(...));
+     *
+     * // Plain schema — derives level from guardNarrow or defaults to public
+     * procedure()
+     *   .guardNarrow(authenticatedNarrow)
+     *   .resource(UserSchema)
+     *   .query(async ({ ctx }) => ctx.db.user.findUnique(...));
      * ```
      */
-    resource<TSchema extends ResourceSchema>(schema: TSchema): ProcedureBuilder<TInput, TContext extends TaggedContext<infer TTag> ? TTag extends ContextTag ? OutputForTag<TSchema, TTag> : OutputForTag<TSchema, ExtractTag<TContext>> : OutputForTag<TSchema, ExtractTag<TContext>>, TContext>;
+    resource<TSchema extends ResourceSchema>(schema: TSchema): ProcedureBuilder<TInput, TSchema extends TaggedResourceSchema<infer TFields, infer TLevel> ? OutputForTag<ResourceSchema<TFields>, LevelToTag<TLevel>> : TContext extends TaggedContext<infer TTag> ? TTag extends ContextTag ? OutputForTag<TSchema, TTag> : OutputForTag<TSchema, ExtractTag<TContext>> : OutputForTag<TSchema, ExtractTag<TContext>>, TContext>;
 }
 /**
  * Internal runtime state for the procedure builder
@@ -414,6 +411,8 @@ export interface BuilderRuntimeState {
     outputSchema?: ValidSchema;
     /** Resource schema for context-dependent output */
     resourceSchema?: ResourceSchema;
+    /** Explicit resource level from tagged schema (e.g., UserSchema.authenticated) */
+    resourceLevel?: 'public' | 'authenticated' | 'admin';
     /** Middleware chain */
     middlewares: MiddlewareFunction<unknown, BaseContext, BaseContext, unknown>[];
     /** Guards to execute before handler */

package/dist/resource/index.d.ts

@@ -60,9 +60,9 @@
  * @module resource
  */
 export { Resource, ResourceCollection, resource, resourceCollection } from './instance.js';
-export type { AdminOutput, AnonymousOutput, AuthenticatedOutput, OutputForTag, ResourceField, ResourceSchema, RuntimeField, } from './schema.js';
-export { isResourceSchema, ResourceSchemaBuilder, resourceSchema } from './schema.js';
-export type { AccessLevel, ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, HasTag, TaggedContext, WithTag, } from './tags.js';
+export type { AdminOutput, AnonymousOutput, AuthenticatedOutput, BuilderField, OutputForLevel, OutputForTag, RelationField, ResourceField, ResourceSchema, ResourceSchemaWithViews, RuntimeField, TaggedResourceSchema, } from './schema.js';
+export { isResourceSchema, isTaggedResourceSchema, ResourceSchemaBuilder, resourceSchema, } from './schema.js';
+export type { AccessLevel, ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, HasTag, LevelToTag, TaggedContext, WithTag, } from './tags.js';
 export type { AdminTaggedContext, AnonymousTaggedContext, AnyResourceOutput, AuthenticatedTaggedContext, IfAdmin, IfAuthenticated, InferResourceData, InferResourceOutput, } from './types.js';
 export type { IsVisibleToTag, VisibilityLevel } from './visibility.js';
 export { getAccessibleLevels, getVisibilityForTag, isVisibleAtLevel } from './visibility.js';

package/dist/resource/index.js

@@ -65,6 +65,6 @@
 // Resource instances
 export { Resource, ResourceCollection, resource, resourceCollection } from './instance.js';
 // Schema builder
-export { isResourceSchema, ResourceSchemaBuilder, resourceSchema } from './schema.js';
+export { isResourceSchema, isTaggedResourceSchema, ResourceSchemaBuilder, resourceSchema, } from './schema.js';
 // Visibility
 export { getAccessibleLevels, getVisibilityForTag, isVisibleAtLevel } from './visibility.js';

package/dist/resource/instance.d.ts

@@ -6,7 +6,7 @@
  *
  * @module resource/instance
  */
-import type { OutputForTag, ResourceSchema } from './schema.js';
+import type { OutputForLevel, OutputForTag, ResourceSchema, TaggedResourceSchema } from './schema.js';
 import type { ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, TaggedContext } from './tags.js';
 /**
  * A resource instance that can project data based on access level
@@ -73,12 +73,11 @@ export declare class Resource<TSchema extends ResourceSchema> {
     /**
      * Projects data for an explicit visibility level
      *
-     * This is a runtime method that filters fields based on the given level.
-     * Uses Object.create(null) and filters dangerous property names to prevent
-     * prototype pollution attacks.
+     * Delegates to the standalone `projectData()` function which supports
+     * recursive projection of nested relations.
      *
      * @param level - The visibility level to project for
-     * @returns Object with only the visible fields
+     * @returns Object with only the visible fields (null prototype)
      */
     private _project;
     /**
@@ -141,44 +140,53 @@ export declare class ResourceCollection<TSchema extends ResourceSchema> {
     isEmpty(): boolean;
 }
 /**
- * Creates a Resource instance for a single data object
+ * Creates a projected view or Resource instance for a single data object
+ *
+ * When called with a tagged schema (e.g., `UserSchema.authenticated`),
+ * returns the projected data directly. When called with an untagged schema,
+ * returns a Resource instance with `.forAnonymous()`, `.forAuthenticated()`,
+ * `.forAdmin()` methods.
  *
  * @param data - The raw data object
- * @param schema - The resource schema defining field visibility
- * @returns Resource instance with projection methods
+ * @param schema - Resource schema (tagged for direct projection, untagged for Resource instance)
+ * @returns Projected data or Resource instance
  *
  * @example
  * ```typescript
  * const user = await db.user.findUnique({ where: { id } });
- * if (!user) throw new NotFoundError();
  *
- * // In a public endpoint
- * return resource(user, UserSchema).forAnonymous();
+ * // Tagged schema → returns projected data directly
+ * return resource(user, UserSchema.authenticated);
+ * // → { id, name, email }
  *
- * // In an authenticated endpoint
+ * // Untagged schema → returns Resource with projection methods
  * return resource(user, UserSchema).forAuthenticated();
- *
- * // In an admin endpoint
- * return resource(user, UserSchema).forAdmin();
+ * // → { id, name, email }
  * ```
  */
+export declare function resource<TSchema extends TaggedResourceSchema>(data: Record<string, unknown>, schema: TSchema): OutputForLevel<TSchema>;
 export declare function resource<TSchema extends ResourceSchema>(data: Record<string, unknown>, schema: TSchema): Resource<TSchema>;
 /**
- * Creates a ResourceCollection for an array of data objects
+ * Creates a projected array or ResourceCollection for an array of data objects
+ *
+ * When called with a tagged schema (e.g., `UserSchema.authenticated`),
+ * returns the projected array directly. When called with an untagged schema,
+ * returns a ResourceCollection with projection methods.
  *
  * @param items - Array of raw data objects
- * @param schema - The resource schema defining field visibility
- * @returns ResourceCollection instance with batch projection methods
+ * @param schema - Resource schema (tagged for direct projection, untagged for collection)
+ * @returns Projected array or ResourceCollection instance
  *
  * @example
  * ```typescript
  * const users = await db.user.findMany({ take: 10 });
  *
- * // In a public endpoint
- * return resourceCollection(users, UserSchema).forAnonymous();
+ * // Tagged schema → returns projected array directly
+ * return resourceCollection(users, UserSchema.authenticated);
  *
- * // In an authenticated endpoint
+ * // Untagged schema → returns ResourceCollection with methods
  * return resourceCollection(users, UserSchema).forAuthenticated();
  * ```
  */
+export declare function resourceCollection<TSchema extends TaggedResourceSchema>(items: Array<Record<string, unknown>>, schema: TSchema): Array<OutputForLevel<TSchema>>;
 export declare function resourceCollection<TSchema extends ResourceSchema>(items: Array<Record<string, unknown>>, schema: TSchema): ResourceCollection<TSchema>;

package/dist/resource/instance.js

@@ -6,6 +6,7 @@
  *
  * @module resource/instance
  */
+import { isTaggedResourceSchema } from './schema.js';
 import { isVisibleAtLevel } from './visibility.js';
 // ============================================================================
 // Security Constants
@@ -24,6 +25,71 @@ const DANGEROUS_PROPERTIES = new Set([
     '__lookupSetter__',
 ]);
 // ============================================================================
+// Recursive Projection
+// ============================================================================
+/** Maximum allowed nesting depth for recursive relation projection */
+const MAX_PROJECTION_DEPTH = 10;
+/**
+ * Recursively projects data through a resource schema, including nested relations
+ *
+ * Tracks recursion depth and visited objects to guard against circular
+ * references and excessively deep nesting.
+ *
+ * @internal
+ * @param data - The raw data object
+ * @param schema - The resource schema to project against
+ * @param level - The visibility level to project for
+ * @param depth - Current recursion depth (defaults to 0)
+ * @param visited - Set of already-visited data objects for cycle detection
+ * @returns Projected object with null prototype
+ */
+function projectData(data, schema, level, depth = 0, visited) {
+    if (depth >= MAX_PROJECTION_DEPTH) {
+        return Object.create(null);
+    }
+    const seen = visited ?? new WeakSet();
+    if (seen.has(data)) {
+        return Object.create(null);
+    }
+    seen.add(data);
+    const result = Object.create(null);
+    for (const field of schema.fields) {
+        if (!isVisibleAtLevel(field.visibility, level))
+            continue;
+        if (DANGEROUS_PROPERTIES.has(field.name))
+            continue;
+        const value = data[field.name];
+        if (field.nestedSchema && field.cardinality) {
+            // Relation field — recursive projection
+            if (field.cardinality === 'one') {
+                if (value != null && typeof value === 'object' && !Array.isArray(value)) {
+                    result[field.name] = projectData(value, field.nestedSchema, level, depth + 1, seen);
+                }
+                else {
+                    result[field.name] = null;
+                }
+            }
+            else {
+                // 'many' — only project valid object items; skip primitives / nulls
+                if (Array.isArray(value)) {
+                    const nested = field.nestedSchema;
+                    result[field.name] = value
+                        .filter((item) => item != null && typeof item === 'object' && !Array.isArray(item))
+                        .map((item) => projectData(item, nested, level, depth + 1, seen));
+                }
+                else {
+                    result[field.name] = [];
+                }
+            }
+        }
+        else if (value !== undefined) {
+            // Scalar field — existing behavior
+            result[field.name] = value;
+        }
+    }
+    return result;
+}
+// ============================================================================
 // Resource Instance
 // ============================================================================
 /**
@@ -105,29 +171,14 @@ export class Resource {
     /**
      * Projects data for an explicit visibility level
      *
-     * This is a runtime method that filters fields based on the given level.
-     * Uses Object.create(null) and filters dangerous property names to prevent
-     * prototype pollution attacks.
+     * Delegates to the standalone `projectData()` function which supports
+     * recursive projection of nested relations.
      *
      * @param level - The visibility level to project for
-     * @returns Object with only the visible fields
+     * @returns Object with only the visible fields (null prototype)
      */
     _project(level) {
-        // Use null prototype to prevent prototype pollution
-        const result = Object.create(null);
-        for (const field of this._schema.fields) {
-            if (isVisibleAtLevel(field.visibility, level)) {
-                // Skip dangerous prototype properties to prevent pollution attacks
-                if (DANGEROUS_PROPERTIES.has(field.name)) {
-                    continue;
-                }
-                const value = this._data[field.name];
-                if (value !== undefined) {
-                    result[field.name] = value;
-                }
-            }
-        }
-        return result;
+        return projectData(this._data, this._schema, level);
     }
     /**
      * Infers the visibility level from a context object
@@ -231,52 +282,33 @@ export class ResourceCollection {
         return this._items.length === 0;
     }
 }
-// ============================================================================
-// Factory Functions
-// ============================================================================
-/**
- * Creates a Resource instance for a single data object
- *
- * @param data - The raw data object
- * @param schema - The resource schema defining field visibility
- * @returns Resource instance with projection methods
- *
- * @example
- * ```typescript
- * const user = await db.user.findUnique({ where: { id } });
- * if (!user) throw new NotFoundError();
- *
- * // In a public endpoint
- * return resource(user, UserSchema).forAnonymous();
- *
- * // In an authenticated endpoint
- * return resource(user, UserSchema).forAuthenticated();
- *
- * // In an admin endpoint
- * return resource(user, UserSchema).forAdmin();
- * ```
- */
 export function resource(data, schema) {
+    if (isTaggedResourceSchema(schema)) {
+        const r = new Resource(data, schema);
+        switch (schema._level) {
+            case 'admin':
+                return r.forAdmin();
+            case 'authenticated':
+                return r.forAuthenticated();
+            default:
+                return r.forAnonymous();
+        }
+    }
     return new Resource(data, schema);
 }
-/**
- * Creates a ResourceCollection for an array of data objects
- *
- * @param items - Array of raw data objects
- * @param schema - The resource schema defining field visibility
- * @returns ResourceCollection instance with batch projection methods
- *
- * @example
- * ```typescript
- * const users = await db.user.findMany({ take: 10 });
- *
- * // In a public endpoint
- * return resourceCollection(users, UserSchema).forAnonymous();
- *
- * // In an authenticated endpoint
- * return resourceCollection(users, UserSchema).forAuthenticated();
- * ```
- */
 export function resourceCollection(items, schema) {
+    if (isTaggedResourceSchema(schema)) {
+        return items.map((item) => {
+            const r = new Resource(item, schema);
+            switch (schema._level) {
+                case 'admin':
+                    return r.forAdmin();
+                case 'authenticated':
+                    return r.forAuthenticated();
+                default:
+                    return r.forAnonymous();
+            }
+        });
+    }
     return new ResourceCollection(items, schema);
 }

package/dist/resource/schema.d.ts

@@ -8,7 +8,7 @@
  * @module resource/schema
  */
 import type { ZodType, ZodTypeDef } from 'zod';
-import type { ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag } from './tags.js';
+import type { AccessLevel, ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, LevelToTag } from './tags.js';
 import type { IsVisibleToTag, VisibilityLevel } from './visibility.js';
 /**
  * A single field definition in a resource schema
@@ -25,13 +25,35 @@ export interface ResourceField<TName extends string = string, TSchema extends Zo
     /** Visibility level */
     readonly visibility: TLevel;
 }
+/**
+ * A relation field that references a nested resource schema
+ *
+ * @template TName - The field name as a literal type
+ * @template TNestedFields - The nested schema's field definitions
+ * @template TLevel - The visibility level controlling WHETHER the relation is included
+ * @template TCardinality - 'one' for nullable object, 'many' for array
+ */
+export interface RelationField<TName extends string = string, TNestedFields extends readonly BuilderField[] = readonly BuilderField[], TLevel extends VisibilityLevel = VisibilityLevel, TCardinality extends 'one' | 'many' = 'one' | 'many'> {
+    readonly name: TName;
+    readonly nestedSchema: ResourceSchema<TNestedFields>;
+    readonly visibility: TLevel;
+    readonly cardinality: TCardinality;
+    /** Brand discriminator — distinguishes from ResourceField */
+    readonly _relation: true;
+}
+/**
+ * Union of scalar and relation fields in a resource schema
+ */
+export type BuilderField = ResourceField | RelationField;
 /**
  * Runtime representation of a field (without generics for storage)
  */
 export interface RuntimeField {
     readonly name: string;
-    readonly schema: ZodType;
+    readonly schema?: ZodType;
     readonly visibility: VisibilityLevel;
+    readonly nestedSchema?: ResourceSchema;
+    readonly cardinality?: 'one' | 'many';
 }
 /**
  * A completed resource schema with all field definitions
@@ -41,12 +63,65 @@ export interface RuntimeField {
  *
  * @template TFields - Tuple of ResourceField types
  */
-export interface ResourceSchema<TFields extends readonly ResourceField[] = readonly ResourceField[]> {
+export interface ResourceSchema<TFields extends readonly BuilderField[] = readonly BuilderField[]> {
     /** Runtime field definitions */
     readonly fields: readonly RuntimeField[];
     /** Phantom type for field type information */
     readonly __fields?: TFields;
 }
+/**
+ * A resource schema tagged with an explicit access level
+ *
+ * Created by accessing `.public`, `.authenticated`, or `.admin` on a built schema.
+ * Used in both procedure definitions (auto-projection) and handler-level
+ * projection via `resource(data, Schema.authenticated)`.
+ *
+ * @template TFields - The field definitions from the base schema
+ * @template TLevel - The access level for projection
+ *
+ * @example
+ * ```typescript
+ * const UserSchema = resourceSchema()
+ *   .public('id', z.string())
+ *   .authenticated('email', z.string())
+ *   .build();
+ *
+ * // Tagged views
+ * UserSchema.public        // TaggedResourceSchema<..., 'public'>
+ * UserSchema.authenticated  // TaggedResourceSchema<..., 'authenticated'>
+ * UserSchema.admin          // TaggedResourceSchema<..., 'admin'>
+ * ```
+ */
+export interface TaggedResourceSchema<TFields extends readonly BuilderField[] = readonly BuilderField[], TLevel extends AccessLevel = AccessLevel> extends ResourceSchema<TFields> {
+    readonly _level: TLevel;
+}
+/**
+ * A completed resource schema with pre-built tagged views
+ *
+ * Returned by `resourceSchema().build()`. Extends `ResourceSchema` (backward
+ * compatible) and adds `.public`, `.authenticated`, `.admin` properties
+ * for declarative projection.
+ *
+ * @template TFields - The field definitions
+ */
+export interface ResourceSchemaWithViews<TFields extends readonly BuilderField[] = readonly BuilderField[]> extends ResourceSchema<TFields> {
+    readonly public: TaggedResourceSchema<TFields, 'public'>;
+    readonly authenticated: TaggedResourceSchema<TFields, 'authenticated'>;
+    readonly admin: TaggedResourceSchema<TFields, 'admin'>;
+}
+/**
+ * Computes the output type for a tagged resource schema
+ *
+ * Maps the access level to the corresponding phantom tag and
+ * computes the projected output type.
+ *
+ * @template TSchema - A tagged resource schema
+ */
+export type OutputForLevel<TSchema extends TaggedResourceSchema> = TSchema extends TaggedResourceSchema<infer TFields, infer TLevel> ? OutputForTag<ResourceSchema<TFields>, LevelToTag<TLevel>> : never;
+/**
+ * Type guard to check if a schema is a TaggedResourceSchema (has _level)
+ */
+export declare function isTaggedResourceSchema(value: unknown): value is TaggedResourceSchema;
 /**
  * Helper to infer the output type of a Zod schema
  */
@@ -55,11 +130,14 @@ type InferZodOutput<T> = T extends ZodType<infer O, ZodTypeDef, unknown> ? O : n
  * Filters fields by visibility and extracts their types
  *
  * This type iterates over the fields tuple and includes only those
- * that are visible to the given context tag.
+ * that are visible to the given context tag. RelationField entries
+ * are recursively projected using the same tag.
  */
-type FilterFieldsByTag<TFields extends readonly ResourceField[], TTag extends ContextTag> = TFields extends readonly [infer First, ...infer Rest] ? First extends ResourceField<infer Name, infer Schema, infer Level> ? Rest extends readonly ResourceField[] ? IsVisibleToTag<Level, TTag> extends true ? {
+type FilterFieldsByTag<TFields extends readonly BuilderField[], TTag extends ContextTag> = TFields extends readonly [infer First, ...infer Rest] ? Rest extends readonly BuilderField[] ? First extends RelationField<infer Name, infer NestedFields, infer Level, infer Card> ? IsVisibleToTag<Level, TTag> extends true ? {
+    [K in Name]: Card extends 'one' ? Simplify<FilterFieldsByTag<NestedFields, TTag>> | null : Array<Simplify<FilterFieldsByTag<NestedFields, TTag>>>;
+} & FilterFieldsByTag<Rest, TTag> : FilterFieldsByTag<Rest, TTag> : First extends ResourceField<infer Name, infer Schema, infer Level> ? IsVisibleToTag<Level, TTag> extends true ? {
     [K in Name]: InferZodOutput<Schema>;
-} & FilterFieldsByTag<Rest, TTag> : FilterFieldsByTag<Rest, TTag> : unknown : unknown : unknown;
+} & FilterFieldsByTag<Rest, TTag> : FilterFieldsByTag<Rest, TTag> : FilterFieldsByTag<Rest, TTag> : unknown : unknown;
 /**
  * Simplifies an intersection type to a cleaner object type
  *
@@ -108,7 +186,7 @@ export type AdminOutput<TSchema extends ResourceSchema> = OutputForTag<TSchema,
  *   .build();
  * ```
  */
-export declare class ResourceSchemaBuilder<TFields extends readonly ResourceField[] = readonly []> {
+export declare class ResourceSchemaBuilder<TFields extends readonly BuilderField[] = readonly []> {
     private readonly _fields;
     private constructor();
     /**
@@ -139,6 +217,56 @@ export declare class ResourceSchemaBuilder<TFields extends readonly ResourceFiel
      * @returns New builder with the field added
      */
     admin<TName extends string, TSchema extends ZodType>(name: TName, schema: TSchema): ResourceSchemaBuilder<readonly [...TFields, ResourceField<TName, TSchema, 'admin'>]>;
+    /**
+     * Adds a has-one relation (nullable nested object)
+     *
+     * The relation's visibility controls WHETHER it appears in the output.
+     * The parent's projection level controls WHAT fields of the nested schema are shown.
+     *
+     * **Note:** The nested schema's generic field types are tracked at compile time
+     * for output type computation, but the runtime field stores an untyped
+     * `ResourceSchema` reference. Always pass the direct result of `.build()`
+     * to ensure the compile-time and runtime schemas stay in sync.
+     *
+     * @param name - Relation field name
+     * @param nestedSchema - The nested resource schema (result of `.build()`)
+     * @param visibility - Visibility level for this relation
+     * @returns New builder with the relation added
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = resourceSchema()
+     *   .public('id', z.string())
+     *   .hasOne('organization', OrgSchema, 'public')
+     *   .build();
+     * ```
+     */
+    hasOne<TName extends string, TNestedFields extends readonly BuilderField[], TLevel extends VisibilityLevel>(name: TName, nestedSchema: ResourceSchema<TNestedFields>, visibility: TLevel): ResourceSchemaBuilder<readonly [...TFields, RelationField<TName, TNestedFields, TLevel, 'one'>]>;
+    /**
+     * Adds a has-many relation (array of nested objects)
+     *
+     * The relation's visibility controls WHETHER it appears in the output.
+     * The parent's projection level controls WHAT fields of the nested schema are shown.
+     *
+     * **Note:** The nested schema's generic field types are tracked at compile time
+     * for output type computation, but the runtime field stores an untyped
+     * `ResourceSchema` reference. Always pass the direct result of `.build()`
+     * to ensure the compile-time and runtime schemas stay in sync.
+     *
+     * @param name - Relation field name
+     * @param nestedSchema - The nested resource schema (result of `.build()`)
+     * @param visibility - Visibility level for this relation
+     * @returns New builder with the relation added
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = resourceSchema()
+     *   .public('id', z.string())
+     *   .hasMany('posts', PostSchema, 'authenticated')
+     *   .build();
+     * ```
+     */
+    hasMany<TName extends string, TNestedFields extends readonly BuilderField[], TLevel extends VisibilityLevel>(name: TName, nestedSchema: ResourceSchema<TNestedFields>, visibility: TLevel): ResourceSchemaBuilder<readonly [...TFields, RelationField<TName, TNestedFields, TLevel, 'many'>]>;
     /**
      * Adds a field with explicit visibility level
      *
@@ -149,11 +277,28 @@ export declare class ResourceSchemaBuilder<TFields extends readonly ResourceFiel
      */
     field<TName extends string, TSchema extends ZodType, TLevel extends VisibilityLevel>(name: TName, schema: TSchema, visibility: TLevel): ResourceSchemaBuilder<readonly [...TFields, ResourceField<TName, TSchema, TLevel>]>;
     /**
-     * Builds the final resource schema
+     * Builds the final resource schema with tagged views
+     *
+     * Returns a schema with `.public`, `.authenticated`, and `.admin`
+     * properties for declarative projection in procedures.
+     *
+     * @returns Completed resource schema with tagged views
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = resourceSchema()
+     *   .public('id', z.string())
+     *   .authenticated('email', z.string())
+     *   .build();
+     *
+     * // Use tagged views in procedures
+     * procedure().resource(UserSchema.authenticated).query(handler);
      *
-     * @returns Completed resource schema with full type information
+     * // Or in handlers
+     * resource(data, UserSchema.authenticated);
+     * ```
      */
-    build(): ResourceSchema<TFields>;
+    build(): ResourceSchemaWithViews<TFields>;
 }
 /**
  * Creates a new resource schema builder

package/dist/resource/schema.js

@@ -7,6 +7,18 @@
  *
  * @module resource/schema
  */
+/**
+ * Type guard to check if a schema is a TaggedResourceSchema (has _level)
+ */
+export function isTaggedResourceSchema(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    return (Array.isArray(obj.fields) &&
+        typeof obj._level === 'string' &&
+        (obj._level === 'public' || obj._level === 'authenticated' || obj._level === 'admin'));
+}
 // ============================================================================
 // Schema Builder
 // ============================================================================
@@ -78,6 +90,76 @@ export class ResourceSchemaBuilder {
             { name, schema, visibility: 'admin' },
         ]);
     }
+    /**
+     * Adds a has-one relation (nullable nested object)
+     *
+     * The relation's visibility controls WHETHER it appears in the output.
+     * The parent's projection level controls WHAT fields of the nested schema are shown.
+     *
+     * **Note:** The nested schema's generic field types are tracked at compile time
+     * for output type computation, but the runtime field stores an untyped
+     * `ResourceSchema` reference. Always pass the direct result of `.build()`
+     * to ensure the compile-time and runtime schemas stay in sync.
+     *
+     * @param name - Relation field name
+     * @param nestedSchema - The nested resource schema (result of `.build()`)
+     * @param visibility - Visibility level for this relation
+     * @returns New builder with the relation added
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = resourceSchema()
+     *   .public('id', z.string())
+     *   .hasOne('organization', OrgSchema, 'public')
+     *   .build();
+     * ```
+     */
+    hasOne(name, nestedSchema, visibility) {
+        return new ResourceSchemaBuilder([
+            ...this._fields,
+            {
+                name,
+                visibility,
+                nestedSchema: nestedSchema,
+                cardinality: 'one',
+            },
+        ]);
+    }
+    /**
+     * Adds a has-many relation (array of nested objects)
+     *
+     * The relation's visibility controls WHETHER it appears in the output.
+     * The parent's projection level controls WHAT fields of the nested schema are shown.
+     *
+     * **Note:** The nested schema's generic field types are tracked at compile time
+     * for output type computation, but the runtime field stores an untyped
+     * `ResourceSchema` reference. Always pass the direct result of `.build()`
+     * to ensure the compile-time and runtime schemas stay in sync.
+     *
+     * @param name - Relation field name
+     * @param nestedSchema - The nested resource schema (result of `.build()`)
+     * @param visibility - Visibility level for this relation
+     * @returns New builder with the relation added
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = resourceSchema()
+     *   .public('id', z.string())
+     *   .hasMany('posts', PostSchema, 'authenticated')
+     *   .build();
+     * ```
+     */
+    hasMany(name, nestedSchema, visibility) {
+        return new ResourceSchemaBuilder([
+            ...this._fields,
+            {
+                name,
+                visibility,
+                nestedSchema: nestedSchema,
+                cardinality: 'many',
+            },
+        ]);
+    }
     /**
      * Adds a field with explicit visibility level
      *
@@ -93,14 +175,35 @@ export class ResourceSchemaBuilder {
         ]);
     }
     /**
-     * Builds the final resource schema
+     * Builds the final resource schema with tagged views
+     *
+     * Returns a schema with `.public`, `.authenticated`, and `.admin`
+     * properties for declarative projection in procedures.
+     *
+     * @returns Completed resource schema with tagged views
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = resourceSchema()
+     *   .public('id', z.string())
+     *   .authenticated('email', z.string())
+     *   .build();
+     *
+     * // Use tagged views in procedures
+     * procedure().resource(UserSchema.authenticated).query(handler);
      *
-     * @returns Completed resource schema with full type information
+     * // Or in handlers
+     * resource(data, UserSchema.authenticated);
+     * ```
      */
     build() {
-        return {
-            fields: [...this._fields],
-        };
+        const fields = [...this._fields];
+        const base = { fields };
+        return Object.assign(base, {
+            public: Object.assign({ fields }, { _level: 'public' }),
+            authenticated: Object.assign({ fields }, { _level: 'authenticated' }),
+            admin: Object.assign({ fields }, { _level: 'admin' }),
+        });
     }
 }
 // ============================================================================

package/dist/resource/tags.d.ts

@@ -16,6 +16,20 @@
  * automatic resource projection in the procedure builder.
  */
 export type AccessLevel = 'public' | 'authenticated' | 'admin';
+/**
+ * Maps an AccessLevel string to its corresponding phantom ContextTag
+ *
+ * Used to bridge the runtime level declarations (e.g., `UserSchema.authenticated`)
+ * to the compile-time phantom type system for output type computation.
+ *
+ * @example
+ * ```typescript
+ * type Tag = LevelToTag<'authenticated'>; // typeof AUTHENTICATED
+ * type Tag = LevelToTag<'admin'>;         // typeof ADMIN
+ * type Tag = LevelToTag<'public'>;        // typeof ANONYMOUS
+ * ```
+ */
+export type LevelToTag<TLevel extends AccessLevel> = TLevel extends 'admin' ? typeof ADMIN : TLevel extends 'authenticated' ? typeof AUTHENTICATED : typeof ANONYMOUS;
 /**
  * Phantom symbol for anonymous (unauthenticated) context
  * @internal Compile-time only - never used at runtime

package/dist/types.d.ts

@@ -343,6 +343,15 @@ export interface CompiledProcedure<TInput = unknown, TOutput = unknown, TContext
      * @internal
      */
     readonly _resourceSchema?: any;
+    /**
+     * Explicit resource projection level from tagged schema
+     *
+     * Set when using `.resource(UserSchema.authenticated)` etc.
+     * Takes precedence over guard-derived access level.
+     *
+     * @internal
+     */
+    readonly _resourceLevel?: 'public' | 'authenticated' | 'admin';
 }
 /**
  * Record of named procedures

package/package.json

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