@veloxts/router 0.7.5 → 0.7.6

package/dist/resource/instance.d.ts

@@ -6,8 +6,8 @@
  *
  * @module resource/instance
  */
-import type { OutputForLevel, OutputForTag, ResourceSchema, TaggedResourceSchema } from './schema.js';
-import type { ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, TaggedContext } from './tags.js';
+import type { FilterFieldsByLevel, OutputForLevel, OutputForTag, ResourceSchema, TaggedResourceSchema } from './schema.js';
+import type { ADMIN, AUTHENTICATED, ContextTag, ExtractTag, PUBLIC, TaggedContext } from './tags.js';
 /**
  * A resource instance that can project data based on access level
  *
@@ -23,7 +23,7 @@ import type { ADMIN, ANONYMOUS, AUTHENTICATED, ContextTag, ExtractTag, TaggedCon
  * const resource = new Resource(user, UserSchema);
  *
  * // Returns only public fields: { id, name }
- * const publicData = resource.forAnonymous();
+ * const publicData = resource.forPublic();
  *
  * // Returns public + authenticated fields: { id, name, email }
  * const authData = resource.forAuthenticated();
@@ -37,11 +37,13 @@ export declare class Resource<TSchema extends ResourceSchema> {
     private readonly _schema;
     constructor(data: Record<string, unknown>, schema: TSchema);
     /**
-     * Projects data for anonymous (unauthenticated) access
+     * Projects data for public (unauthenticated) access
      *
      * Returns only fields marked as 'public'.
      */
-    forAnonymous(): OutputForTag<TSchema, typeof ANONYMOUS>;
+    forPublic(): OutputForTag<TSchema, typeof PUBLIC>;
+    /** @deprecated Use forPublic() */
+    forAnonymous(): OutputForTag<TSchema, typeof PUBLIC>;
     /**
      * Projects data for authenticated user access
      *
@@ -54,6 +56,22 @@ export declare class Resource<TSchema extends ResourceSchema> {
      * Returns all fields (public, authenticated, and admin).
      */
     forAdmin(): OutputForTag<TSchema, typeof ADMIN>;
+    /**
+     * Projects data for an explicit access level string
+     *
+     * Works with both default levels ('public', 'authenticated', 'admin')
+     * and custom levels defined via `defineAccessLevels()`.
+     *
+     * @param level - The access level to project for
+     * @returns Object with only the fields visible to the given level
+     *
+     * @example
+     * ```typescript
+     * // Custom level projection
+     * const data = resource.forLevel('reviewer');
+     * ```
+     */
+    forLevel<TLevel extends string>(level: TLevel): TSchema extends ResourceSchema<infer TFields> ? FilterFieldsByLevel<TFields, TLevel> : Record<string, unknown>;
     /**
      * Projects data based on a tagged context
      *
@@ -70,16 +88,6 @@ export declare class Resource<TSchema extends ResourceSchema> {
      * ```
      */
     for<TContext extends TaggedContext<ContextTag>>(ctx: TContext): OutputForTag<TSchema, ExtractTag<TContext>>;
-    /**
-     * Projects data for an explicit visibility level
-     *
-     * 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 (null prototype)
-     */
-    private _project;
     /**
      * Infers the visibility level from a context object
      *
@@ -104,7 +112,7 @@ export declare class Resource<TSchema extends ResourceSchema> {
  * const collection = new ResourceCollection(users, UserSchema);
  *
  * // Returns array of public views
- * const publicList = collection.forAnonymous();
+ * const publicList = collection.forPublic();
  *
  * // Returns array with authenticated fields
  * const authList = collection.forAuthenticated();
@@ -115,9 +123,11 @@ export declare class ResourceCollection<TSchema extends ResourceSchema> {
     private readonly _schema;
     constructor(items: Array<Record<string, unknown>>, schema: TSchema);
     /**
-     * Projects all items for anonymous access
+     * Projects all items for public (unauthenticated) access
      */
-    forAnonymous(): Array<OutputForTag<TSchema, typeof ANONYMOUS>>;
+    forPublic(): Array<OutputForTag<TSchema, typeof PUBLIC>>;
+    /** @deprecated Use forPublic() */
+    forAnonymous(): Array<OutputForTag<TSchema, typeof PUBLIC>>;
     /**
      * Projects all items for authenticated user access
      */
@@ -126,6 +136,14 @@ export declare class ResourceCollection<TSchema extends ResourceSchema> {
      * Projects all items for admin access
      */
     forAdmin(): Array<OutputForTag<TSchema, typeof ADMIN>>;
+    /**
+     * Projects all items for an explicit access level string
+     *
+     * Works with both default and custom access levels.
+     *
+     * @param level - The access level to project for
+     */
+    forLevel<TLevel extends string>(level: TLevel): TSchema extends ResourceSchema<infer TFields> ? Array<FilterFieldsByLevel<TFields, TLevel>> : Array<Record<string, unknown>>;
     /**
      * Projects all items based on a tagged context
      */
@@ -144,8 +162,8 @@ export declare class ResourceCollection<TSchema extends ResourceSchema> {
  *
  * 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.
+ * returns a Resource instance with `.forPublic()`, `.forAuthenticated()`,
+ * `.forAdmin()`, `.forLevel()` methods.
  *
  * @param data - The raw data object
  * @param schema - Resource schema (tagged for direct projection, untagged for Resource instance)

package/dist/resource/instance.js

@@ -7,7 +7,7 @@
  * @module resource/instance
  */
 import { isTaggedResourceSchema } from './schema.js';
-import { isVisibleAtLevel } from './visibility.js';
+import { isFieldVisibleToLevel } from './visibility.js';
 // ============================================================================
 // Security Constants
 // ============================================================================
@@ -38,7 +38,7 @@ const MAX_PROJECTION_DEPTH = 10;
  * @internal
  * @param data - The raw data object
  * @param schema - The resource schema to project against
- * @param level - The visibility level to project for
+ * @param level - The access level to project for (any string)
  * @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
@@ -54,7 +54,7 @@ function projectData(data, schema, level, depth = 0, visited) {
     seen.add(data);
     const result = Object.create(null);
     for (const field of schema.fields) {
-        if (!isVisibleAtLevel(field.visibility, level))
+        if (!isFieldVisibleToLevel(field, level))
             continue;
         if (DANGEROUS_PROPERTIES.has(field.name))
             continue;
@@ -107,7 +107,7 @@ function projectData(data, schema, level, depth = 0, visited) {
  * const resource = new Resource(user, UserSchema);
  *
  * // Returns only public fields: { id, name }
- * const publicData = resource.forAnonymous();
+ * const publicData = resource.forPublic();
  *
  * // Returns public + authenticated fields: { id, name, email }
  * const authData = resource.forAuthenticated();
@@ -124,12 +124,16 @@ export class Resource {
         this._schema = schema;
     }
     /**
-     * Projects data for anonymous (unauthenticated) access
+     * Projects data for public (unauthenticated) access
      *
      * Returns only fields marked as 'public'.
      */
+    forPublic() {
+        return this.forLevel('public');
+    }
+    /** @deprecated Use forPublic() */
     forAnonymous() {
-        return this._project('public');
+        return this.forPublic();
     }
     /**
      * Projects data for authenticated user access
@@ -137,7 +141,7 @@ export class Resource {
      * Returns fields marked as 'public' or 'authenticated'.
      */
     forAuthenticated() {
-        return this._project('authenticated');
+        return this.forLevel('authenticated');
     }
     /**
      * Projects data for admin access
@@ -145,7 +149,25 @@ export class Resource {
      * Returns all fields (public, authenticated, and admin).
      */
     forAdmin() {
-        return this._project('admin');
+        return this.forLevel('admin');
+    }
+    /**
+     * Projects data for an explicit access level string
+     *
+     * Works with both default levels ('public', 'authenticated', 'admin')
+     * and custom levels defined via `defineAccessLevels()`.
+     *
+     * @param level - The access level to project for
+     * @returns Object with only the fields visible to the given level
+     *
+     * @example
+     * ```typescript
+     * // Custom level projection
+     * const data = resource.forLevel('reviewer');
+     * ```
+     */
+    forLevel(level) {
+        return projectData(this._data, this._schema, level);
     }
     /**
      * Projects data based on a tagged context
@@ -166,19 +188,7 @@ export class Resource {
         // At runtime, we need to determine the level from context properties
         // Since the tag is phantom (doesn't exist at runtime), we use heuristics
         const level = this._inferLevelFromContext(ctx);
-        return this._project(level);
-    }
-    /**
-     * Projects data for an explicit visibility level
-     *
-     * 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 (null prototype)
-     */
-    _project(level) {
-        return projectData(this._data, this._schema, level);
+        return this.forLevel(level);
     }
     /**
      * Infers the visibility level from a context object
@@ -232,7 +242,7 @@ export class Resource {
  * const collection = new ResourceCollection(users, UserSchema);
  *
  * // Returns array of public views
- * const publicList = collection.forAnonymous();
+ * const publicList = collection.forPublic();
  *
  * // Returns array with authenticated fields
  * const authList = collection.forAuthenticated();
@@ -246,10 +256,14 @@ export class ResourceCollection {
         this._schema = schema;
     }
     /**
-     * Projects all items for anonymous access
+     * Projects all items for public (unauthenticated) access
      */
+    forPublic() {
+        return this._items.map((item) => new Resource(item, this._schema).forPublic());
+    }
+    /** @deprecated Use forPublic() */
     forAnonymous() {
-        return this._items.map((item) => new Resource(item, this._schema).forAnonymous());
+        return this.forPublic();
     }
     /**
      * Projects all items for authenticated user access
@@ -263,6 +277,16 @@ export class ResourceCollection {
     forAdmin() {
         return this._items.map((item) => new Resource(item, this._schema).forAdmin());
     }
+    /**
+     * Projects all items for an explicit access level string
+     *
+     * Works with both default and custom access levels.
+     *
+     * @param level - The access level to project for
+     */
+    forLevel(level) {
+        return this._items.map((item) => new Resource(item, this._schema).forLevel(level));
+    }
     /**
      * Projects all items based on a tagged context
      */
@@ -284,31 +308,14 @@ export class ResourceCollection {
 }
 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).forLevel(schema._level);
     }
     return new Resource(data, schema);
 }
 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();
-            }
-        });
+        const level = schema._level;
+        return items.map((item) => new Resource(item, schema).forLevel(level));
     }
     return new ResourceCollection(items, schema);
 }

package/dist/resource/levels.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Access level configuration for custom visibility systems
+ *
+ * Provides `defineAccessLevels()` for creating custom access level
+ * hierarchies with named groups. The default 3-level system
+ * (public/authenticated/admin) is a special case of this.
+ *
+ * @module resource/levels
+ */
+/**
+ * The built-in 3-level hierarchy used when `resourceSchema()` is called
+ * without arguments.
+ */
+export declare const DEFAULT_LEVELS: readonly ["public", "authenticated", "admin"];
+export type DefaultLevels = typeof DEFAULT_LEVELS;
+/**
+ * Configuration object returned by `defineAccessLevels()`.
+ *
+ * Holds the defined levels, named groups, and a `resolve()` method
+ * that expands a group name to the concrete set of levels it covers.
+ *
+ * @template TLevels - Tuple of level name literals
+ * @template TGroups - Record mapping group names to `'*'` or level arrays
+ */
+export interface AccessLevelConfig<TLevels extends readonly string[] = readonly string[], TGroups extends Record<string, '*' | readonly string[]> = Record<string, never>> {
+    readonly levels: TLevels;
+    readonly groups: TGroups;
+    /** Resolves a group name to the concrete set of levels */
+    resolve(ref: keyof TGroups & string): ReadonlySet<string>;
+    /** Returns the set containing all defined levels */
+    allLevels(): ReadonlySet<string>;
+}
+/**
+ * Defines custom access levels and optional named groups.
+ *
+ * Groups become fluent builder methods on `resourceSchema(config)`.
+ * The `'*'` wildcard resolves to all defined levels.
+ *
+ * @example
+ * ```typescript
+ * const access = defineAccessLevels(
+ *   ['public', 'reviewer', 'authenticated', 'moderator', 'admin'],
+ *   {
+ *     everyone: '*',
+ *     internal: ['reviewer', 'moderator', 'admin'],
+ *     staff: ['moderator', 'admin'],
+ *   }
+ * );
+ * ```
+ */
+export declare function defineAccessLevels<const TLevels extends readonly [string, ...string[]]>(levels: TLevels): AccessLevelConfig<TLevels, Record<string, never>>;
+export declare function defineAccessLevels<const TLevels extends readonly [string, ...string[]], const TGroups extends Record<string, '*' | readonly NoInfer<TLevels[number]>[]>>(levels: TLevels, groups: TGroups): AccessLevelConfig<TLevels, TGroups>;
+/**
+ * Pre-built config for the default 3-level system.
+ *
+ * Used internally by the default `resourceSchema()` builder.
+ * The default levels use a hierarchical model where higher levels
+ * include all fields visible to lower levels.
+ */
+export declare const DEFAULT_ACCESS_LEVELS: AccessLevelConfig<DefaultLevels, Record<string, never>>;
+/**
+ * Converts a default hierarchical level to the set of levels that can see
+ * a field at that visibility.
+ *
+ * - `'public'` → `Set(['public', 'authenticated', 'admin'])`
+ * - `'authenticated'` → `Set(['authenticated', 'admin'])`
+ * - `'admin'` → `Set(['admin'])`
+ *
+ * @internal
+ */
+export declare function defaultLevelToSet(level: string): ReadonlySet<string>;

package/dist/resource/levels.js

@@ -0,0 +1,109 @@
+/**
+ * Access level configuration for custom visibility systems
+ *
+ * Provides `defineAccessLevels()` for creating custom access level
+ * hierarchies with named groups. The default 3-level system
+ * (public/authenticated/admin) is a special case of this.
+ *
+ * @module resource/levels
+ */
+// ============================================================================
+// Default Levels
+// ============================================================================
+/**
+ * The built-in 3-level hierarchy used when `resourceSchema()` is called
+ * without arguments.
+ */
+export const DEFAULT_LEVELS = ['public', 'authenticated', 'admin'];
+export function defineAccessLevels(levels, groups) {
+    // Validation: at least 2 levels
+    if (levels.length < 2) {
+        throw new Error('defineAccessLevels requires at least 2 levels');
+    }
+    // Validation: no duplicate levels
+    const seen = new Set();
+    for (const level of levels) {
+        if (seen.has(level)) {
+            throw new Error(`Duplicate level: "${level}"`);
+        }
+        seen.add(level);
+    }
+    const levelSet = new Set(levels);
+    const resolvedGroups = new Map();
+    const safeGroups = (groups ?? {});
+    if (groups) {
+        for (const [name, ref] of Object.entries(groups)) {
+            // Group names must not collide with level names
+            if (levelSet.has(name)) {
+                throw new Error(`Group name "${name}" collides with a level name. ` +
+                    'Group names and level names must be distinct.');
+            }
+            if (ref === '*') {
+                resolvedGroups.set(name, levelSet);
+            }
+            else if (Array.isArray(ref)) {
+                // Validate that all referenced levels exist
+                for (const member of ref) {
+                    if (!levelSet.has(member)) {
+                        throw new Error(`Group "${name}" references unknown level "${member}". ` +
+                            `Valid levels: ${levels.join(', ')}`);
+                    }
+                }
+                if (ref.length === 0) {
+                    throw new Error(`Group "${name}" must contain at least one level`);
+                }
+                resolvedGroups.set(name, new Set(ref));
+            }
+        }
+    }
+    return {
+        levels,
+        groups: safeGroups,
+        resolve(ref) {
+            const resolved = resolvedGroups.get(ref);
+            if (!resolved) {
+                throw new Error(`Unknown group: "${ref}"`);
+            }
+            return resolved;
+        },
+        allLevels() {
+            return levelSet;
+        },
+    };
+}
+// ============================================================================
+// Default Config
+// ============================================================================
+/**
+ * Pre-built config for the default 3-level system.
+ *
+ * Used internally by the default `resourceSchema()` builder.
+ * The default levels use a hierarchical model where higher levels
+ * include all fields visible to lower levels.
+ */
+export const DEFAULT_ACCESS_LEVELS = defineAccessLevels(DEFAULT_LEVELS);
+// ============================================================================
+// Runtime Helpers
+// ============================================================================
+/**
+ * Converts a default hierarchical level to the set of levels that can see
+ * a field at that visibility.
+ *
+ * - `'public'` → `Set(['public', 'authenticated', 'admin'])`
+ * - `'authenticated'` → `Set(['authenticated', 'admin'])`
+ * - `'admin'` → `Set(['admin'])`
+ *
+ * @internal
+ */
+export function defaultLevelToSet(level) {
+    switch (level) {
+        case 'public':
+            return new Set(['public', 'authenticated', 'admin']);
+        case 'authenticated':
+            return new Set(['authenticated', 'admin']);
+        case 'admin':
+            return new Set(['admin']);
+        default:
+            return new Set([level]);
+    }
+}