@zanzojs/core 0.1.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,407 @@
+/**
+ * Represents a parsed, validated Zanzo entity reference.
+ * All entity identifiers in Zanzo follow the "Type:ID" convention.
+ */
+interface EntityRef {
+    readonly type: string;
+    readonly id: string;
+}
+/**
+ * The canonical separator used to join EntityRef parts into a string.
+ * Both expandTuples and the Drizzle adapter depend on this constant.
+ * Never hardcode ':' for entity refs anywhere else in the codebase.
+ */
+declare const ENTITY_REF_SEPARATOR: ":";
+/**
+ * The canonical separator used to join nested relation path segments.
+ * Both expandTuples and the Drizzle adapter depend on this constant.
+ * Never hardcode '.' for relation paths anywhere else in the codebase.
+ */
+declare const RELATION_PATH_SEPARATOR: ".";
+/**
+ * Parses a "Type:ID" string into a structured EntityRef.
+ * Validates format strictly at the boundary.
+ *
+ * @throws Error if the string does not contain exactly one ':' separator,
+ * or if type or id segments are empty.
+ */
+declare function parseEntityRef(raw: string): EntityRef;
+/**
+ * Serializes an EntityRef back to its canonical "Type:ID" string form.
+ */
+declare function serializeEntityRef(entityRef: EntityRef): string;
+/**
+ * Convenience factory. Equivalent to parseEntityRef but named for ergonomics.
+ * Use this at API boundaries when constructing entity identifiers.
+ *
+ * @example
+ * ref('User:123')     // { type: 'User', id: '123' }
+ * ref('Project:A')    // { type: 'Project', id: 'A' }
+ */
+declare function ref(raw: string): EntityRef;
+
+/**
+ * ZANZO-REVIEW: Hemos eliminado los aliases opacos (Resource, Action, Relation, Role) en favor de `string` puro.
+ * Usar Branded Types habría roto la ergonomía del API Builder al exigir aserciones manuales
+ * de tipos literales en los genéricos (ej. '.entity("User" as Resource)').
+ * El formato esperado se documenta nativamente.
+ */
+/**
+ * Strict Permission format mapping a Resource to an Action.
+ * Automatically infers specific strings from string literals.
+ *
+ * @example
+ * type MyPerm = Permission<'Project', 'read' | 'write'>;
+ * // 'Project:read' | 'Project:write'
+ */
+type Permission<R extends string, A extends string> = `${R}:${A}`;
+/**
+ * Extracts the Action type from a given Permission string type.
+ */
+type ExtractAction<P extends string> = P extends `${string}:${infer A}` ? A : never;
+/**
+ * Extracts the Resource type from a given Permission string type.
+ */
+type ExtractResource<P extends string> = P extends `${infer R}:${string}` ? R : never;
+
+/**
+ * Definition for an entity in the ReBAC schema.
+ */
+interface EntityDefinition<A extends string = string, R extends Record<string, string> = Record<string, string>> {
+    actions: A[];
+    relations?: R;
+    permissions?: Partial<Record<A, Array<Extract<keyof R, string> | `${Extract<keyof R, string>}.${string}`>>>;
+}
+/**
+ * Internal representation of the ReBAC schema.
+ */
+type SchemaData = Record<string, EntityDefinition<any, any>>;
+/**
+ * A fluent API builder for constructing a ReBAC schema.
+ * Uses advanced generics to carry type information through chained calls
+ * for maximum type safety and inference.
+ */
+declare class ZanzoBuilder<TSchema extends SchemaData = {}> {
+    private schema;
+    constructor(initialSchema?: TSchema);
+    /**
+     * Defines a new entity (resource) in the schema.
+     *
+     * @param name The name of the entity resource (e.g., 'User', 'Project')
+     * @param definition The definition containing allowed actions and relations.
+     * @returns A new ZanzoBuilder instance carrying the expanded type information.
+     */
+    entity<TName extends string, TActions extends string, TRelations extends Record<string, keyof TSchema | string> = Record<never, never>>(name: TName, definition: {
+        actions: readonly TActions[];
+        relations?: TRelations;
+        permissions?: Partial<Record<TActions, readonly (keyof TRelations | `${Extract<keyof TRelations, string>}.${string}`)[]>>;
+    }): ZanzoBuilder<TSchema & {
+        [K in TName]: {
+            actions: TActions[];
+            relations: TRelations;
+            permissions: Partial<Record<TActions, (keyof TRelations | `${Extract<keyof TRelations, string>}.${string}`)[]>>;
+        };
+    }>;
+    /**
+     * Builds and freezes the schema, preventing further modifications.
+     *
+     * @returns The immutable, frozen ReBAC schema.
+     */
+    build(): Readonly<TSchema>;
+}
+/**
+ * UnionToIntersection is a TypeScript utility that converts a union of types into an intersection.
+ * Example: `UnionToIntersection<{A: 1} | {B: 2}>` becomes `{A: 1} & {B: 2}`
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Extracts the tuple types array into a union of their elements.
+ */
+type TupleTypes<T extends readonly any[]> = T[number];
+/**
+ * Merges multiple frozen SchemaData objects into a single cohesive Schema.
+ * It enforces strict typings so the resulting Schema is an Intersection of all provided subsets.
+ *
+ * It validates at runtime that no two domain-schemas define the same entity,
+ * preventing silent overwrites and "God Object" collisions.
+ *
+ * @param schemas A rest array of individual built schemas to be merged.
+ * @returns A strictly merged and deep-frozen unified SchemaData intersection.
+ * @throws Error if overlapping entity definitions are found.
+ */
+declare function mergeSchemas<T extends Readonly<SchemaData>[]>(...schemas: T): Readonly<UnionToIntersection<TupleTypes<T>>>;
+
+/**
+ * Represents a logical combination of multiple conditions in the AST.
+ */
+interface QueryAST {
+    operator: 'OR' | 'AND';
+    conditions: Condition[];
+}
+/**
+ * A condition evaluating a single relation path towards a generic target subject.
+ */
+type Condition = DirectCondition | NestedCondition;
+/**
+ * Represents a direct, 1-level relation requirement.
+ * e.g. "We need to find if this resource has the given `targetSubject` as its `relation`".
+ */
+interface DirectCondition {
+    type: 'direct';
+    relation: string;
+    targetSubject: string;
+}
+/**
+ * Represents an inherited relation requirement.
+ * e.g. "We need to find an intermediate entity linked via `relation` that can satisfy `nextRelationPath` to reach `targetSubject`".
+ */
+interface NestedCondition {
+    type: 'nested';
+    relation: string;
+    nextRelationPath: string[];
+    targetSubject: string;
+}
+
+/**
+ * Represents a logical ReBAC relational tuple binding a Subject to an Object via a Relation.
+ * Example: User:1 is the 'owner' of Project:A
+ */
+interface RelationTuple {
+    /**
+     * The actor or subject Entity, typically format 'Type:ID' (e.g. 'User:123')
+     */
+    subject: string;
+    /**
+     * The relationship linking the subject to the object (e.g. 'owner', 'viewer')
+     */
+    relation: string;
+    /**
+     * The target object Entity, typically format 'Type:ID' (e.g. 'Project:456')
+     */
+    object: string;
+}
+/**
+ * Extracts all valid Entity Types (Resources) defined in the provided Schema
+ */
+type ExtractSchemaResources<TSchema extends SchemaData> = keyof TSchema;
+/**
+ * Extracts all Action string unions allowed for a specific Resource type
+ * from the provided Schema.
+ */
+type ExtractSchemaActions<TSchema extends SchemaData, TResource extends keyof TSchema> = TSchema[TResource]['actions'][number];
+/**
+ * Advanced Generic ReBAC Engine.
+ * Takes a Schema initialized by ZanzoBuilder as its type base to offer strict autocomplete.
+ */
+declare class ZanzoEngine<TSchema extends SchemaData> {
+    private schema;
+    private index;
+    constructor(schema: Readonly<TSchema>);
+    /**
+     * Retreives the readonly schema structure.
+     */
+    getSchema(): Readonly<TSchema>;
+    /**
+     * Retrieves the read-only relation-graph maps indexing memory objects.
+     * Exposing strictly for flat compilers.
+     */
+    getIndex(): ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>>;
+    private validateInput;
+    /**
+     * Injects a relation tuple into the in-memory store.
+     * Issue #3: Validates all tuple fields before storing to prevent graph poisoning.
+     */
+    addTuple(tuple: RelationTuple): void;
+    /**
+     * Injects multiple relation tuples into the in-memory store.
+     */
+    addTuples(tuples: RelationTuple[]): void;
+    /**
+     * Clears all relation tuples in the memory store.
+     */
+    clearTuples(): void;
+    /**
+     * PERF-2: Evaluates ALL actions for a given actor on a specific resource in a
+     * single pass. Returns the list of granted actions.
+     *
+     * This is more efficient than calling can() per action because:
+     * - Identical routes shared by multiple actions are evaluated only once
+     * - Early exit when all actions are already resolved
+     * - Only one validation pass per (actor, resource) pair
+     *
+     * @internal This method is public solely because `createZanzoSnapshot` (in compiler/)
+     * requires access to it. It is NOT part of the public API contract and may change
+     * without notice in any minor version. Making it private would require moving
+     * `createZanzoSnapshot` into ZanzoEngine as a method, which would break the current
+     * modular architecture where the compiler is a standalone pure function.
+     */
+    evaluateAllActions(actor: string, resource: string): string[];
+    /**
+     * Evaluates if a given actor has permission to perform an action on a specific resource.
+     * Leverages TypeScript assertions to provide strict autocompletion based on the schema.
+     *
+     * @param actor The subject entity string identifier (e.g., 'User:1')
+     * @param action The specific action to perform (e.g., 'edit'), strictly typed.
+     * @param resource The target resource entity string identifier (e.g., 'Project:A')
+     * @returns boolean True if authorized, false otherwise.
+     */
+    can<TResourceName extends Extract<ExtractSchemaResources<TSchema>, string>, TAction extends ExtractSchemaActions<TSchema, TResourceName>>(actor: string, action: TAction, resource: `${TResourceName}:${string}`): boolean;
+    /**
+     * Internal recursive relation evaluation algorithm via Map Indexes.
+     *
+     * @param actor The original actor trying to accomplish the task
+     * @param allowedRoutes Array of relation chains (pre-splitted parts) that grant access
+     * @param currentTarget The current entity node in the graph being evaluated
+     * @param visited Set of visited nodes to prevent cycles in graph evaluation
+     * @returns True if relation path connects target to actor
+     */
+    private checkRelationsRecursive;
+    /**
+     * Generates a database-agnostic Abstract Syntax Tree (AST) representing
+     * the logical query needed to verify if the given actor is authorized to
+     * perform action on a specific resourceType.
+     *
+     * Useful for "Query Pushdown", allowing ORMs or databases to evaluate permissions
+     * directly across their own relational tables instead of loading data into memory.
+     *
+     * @param actor The subject entity string identifier (e.g., 'User:1')
+     * @param action The specific action to perform (e.g., 'read'), strictly typed.
+     * @param resourceType The target resource entity TYPE (e.g., 'Project')
+     * @returns QueryAST block if action is valid and has mapped relations, null otherwise.
+     */
+    buildDatabaseQuery<TResourceName extends Extract<ExtractSchemaResources<TSchema>, string>, TAction extends ExtractSchemaActions<TSchema, TResourceName>>(actor: string, action: TAction, resourceType: TResourceName): QueryAST | null;
+}
+
+/**
+ * A compiled, flat JSON representation of authorized actions for a given actor over specific resources.
+ * Output Format: Record<ResourceID, string[]>
+ * Example: { "Project:A": ["read", "write"] }
+ */
+type CompiledPermissions = Record<string, string[]>;
+/**
+ * Compiles a flat JSON object containing all authorized actions a specific actor
+ * can perform over every resource currently present in the engine's memory.
+ *
+ * This strips away all the relational ReBAC graph complexity, allowing lightweight
+ * clients (Browsers, Mobile Apps, Edge workers) to do fast O(1) checks.
+ *
+ * @param engine The initialized ZanzoEngine containing the rules and graph memory
+ * @param actor The subject entity string identifier (e.g., 'User:1')
+ * @returns CompiledPermissions A flat JSON map answering "what can I do and where?"
+ */
+declare function createZanzoSnapshot<TSchema extends SchemaData>(engine: ZanzoEngine<TSchema>, actor: string): CompiledPermissions;
+
+/**
+ * A lightweight, ultra-fast O(1) ReBAC Client intended for Frontend applications
+ * or Edge Environments.
+ *
+ * It operates solely on a pre-compiled JSON mask. It forces 0 dependencies
+ * and requires no knowledge of schemas, graph recursion, or Rebac Engines.
+ *
+ * Issue #5: Uses Map<string, Set<string>> internally for true O(1) lookups.
+ * Issue #12: Deep-copies incoming snapshot to prevent external mutation.
+ */
+declare class ZanzoClient {
+    private permissions;
+    private snapshotCache;
+    /**
+     * Initializes the client with a strictly flat JSON representation of permissions.
+     * The input is deep-copied internally to prevent Prototype Pollution
+     * or external mutation attacks.
+     *
+     * @param compiledPermissions The Record<ResourceID, string[]> derived from `createZanzoSnapshot`
+     */
+    constructor(compiledPermissions: CompiledPermissions);
+    /**
+     * True O(1) constant time evaluation of permissions via Set.has().
+     *
+     * @param action The specific action to evaluate
+     * @param resource The target resource entity identifier
+     * @returns boolean True if authorized, False otherwise
+     */
+    can(action: string, resource: string): boolean;
+    /**
+     * Returns the compiled snapshot state as a plain JSON object.
+     * Result is cached after first call to avoid re-serialization.
+     * Useful for persisting it locally or dumping to Redux/Vuex inside Client apps.
+     */
+    getSnapshot(): CompiledPermissions;
+}
+
+/**
+ * Callback que el usuario debe implementar para proveer los objetos hijos
+ * de un objeto padre dado una relación específica.
+ *
+ * Ejemplo: para el tuple `User:1 → admin → Org:A`, el engine necesita saber
+ * qué Projects pertenecen a `Org:A` via la relación `org` para poder derivar
+ * `User:1 → org.admin → Project:X`.
+ *
+ * @param parentObject El objeto padre (e.g. "Org:A")
+ * @param relationToChildren El nombre de la relación inversa (e.g. "org")
+ * @returns Array de identificadores de objetos hijos (e.g. ["Project:1", "Project:2"])
+ */
+type FetchChildrenCallback = (parentObject: string, relationToChildren: string) => Promise<string[]> | string[];
+interface ExpansionContext {
+    schema: Readonly<SchemaData>;
+    newTuple: RelationTuple;
+    fetchChildren: FetchChildrenCallback;
+    /**
+     * Maximum number of derived tuples allowed before aborting expansion.
+     * Prevents denial-of-service via unbounded queue growth in pathological schemas.
+     * @default 500
+     */
+    maxExpansionSize?: number;
+}
+/**
+ * Dado un nuevo tuple base, calcula todas las tuplas derivadas implícitas
+ * que deben ser materializadas en la base de datos para que las nested
+ * permission paths funcionen correctamente en el adapter SQL.
+ *
+ * Esta función es PURA en su lógica: solo lee el schema y delega
+ * el acceso a datos al callback provisto. No tiene side effects.
+ *
+ * @remarks
+ * **Resolución Transitiva (Nested de múltiples niveles):**
+ * Para schemas con paths de más de dos niveles (e.g. `parent.org.admin`), los
+ * tuples intermedios también deben ser expandidos. Esta función maneja la
+ * propagación completa automáticamente mediante una cola (queue) interna,
+ * procesando iterativamente cada nuevo tuple derivado hasta agotar las rutas dinámicas.
+ * No requiere llamadas manuales recurrentes por parte del desarrollador.
+ *
+ * @returns Array de RelationTuple derivados que deben ser insertados
+ * junto al tuple original. Si no hay derivaciones, retorna [].
+ */
+declare function expandTuples(ctx: ExpansionContext): Promise<RelationTuple[]>;
+
+interface CollapseContext {
+    schema: Readonly<SchemaData>;
+    /**
+     * El tuple base que se está revocando.
+     * Debe ser idéntico al tuple base que se pasó a expandTuples originalmente.
+     */
+    revokedTuple: RelationTuple;
+    fetchChildren: FetchChildrenCallback;
+    /**
+     * Límite máximo de tuples a procesar en la cola de colapso.
+     * Debe ser igual al maxExpansionSize usado al expandir.
+     * @default 500
+     */
+    maxCollapseSize?: number;
+}
+/**
+ * Calcula todos los tuples derivados que deben ser eliminados de la DB
+ * cuando se revoca un tuple base previamente expandido con `expandTuples`.
+ *
+ * Esta función es el inverso simétrico de `expandTuples`. Usa el mismo
+ * algoritmo de queue-based traversal y el mismo `fetchChildren` callback
+ * para reconstruir qué tuples derivados existen y deben ser borrados.
+ *
+ * Es PURA: no elimina nada. Retorna los tuples a eliminar para que
+ * el caller decida cómo ejecutar el DELETE en su base de datos.
+ *
+ * @returns Array de RelationTuple que deben ser eliminados,
+ * NO incluye el revokedTuple base (el caller lo elimina por separado).
+ */
+declare function collapseTuples(ctx: CollapseContext): Promise<RelationTuple[]>;
+
+export { type CollapseContext, type CompiledPermissions, type Condition, type DirectCondition, ENTITY_REF_SEPARATOR, type EntityDefinition, type EntityRef, type ExpansionContext, type ExtractAction, type ExtractResource, type ExtractSchemaActions, type ExtractSchemaResources, type FetchChildrenCallback, type NestedCondition, type Permission, type QueryAST, RELATION_PATH_SEPARATOR, type RelationTuple, type SchemaData, type TupleTypes, type UnionToIntersection, ZanzoBuilder, ZanzoClient, ZanzoEngine, collapseTuples, createZanzoSnapshot, expandTuples, mergeSchemas, parseEntityRef, ref, serializeEntityRef };