@cfast/permissions 0.0.1 → 0.2.0

package/dist/client-ChpyEV1r.d.ts

@@ -1,62 +0,0 @@
-type DrizzleTable = {
-    _: {
-        name: string;
-    };
-};
-type DrizzleSQL = {
-    getSQL(): unknown;
-};
-type PermissionAction = "read" | "create" | "update" | "delete" | "manage";
-type CrudAction = Exclude<PermissionAction, "manage">;
-declare const CRUD_ACTIONS: readonly CrudAction[];
-type WhereClause = (columns: Record<string, unknown>, user: any) => DrizzleSQL | undefined;
-type Grant = {
-    action: PermissionAction;
-    subject: DrizzleTable | "all";
-    where?: WhereClause;
-};
-type GrantFn<TUser> = (action: PermissionAction, subject: DrizzleTable | "all", options?: {
-    where?: (columns: Record<string, unknown>, user: TUser) => DrizzleSQL | undefined;
-}) => Grant;
-type PermissionDescriptor = {
-    action: PermissionAction;
-    table: DrizzleTable;
-};
-type PermissionCheckResult = {
-    permitted: boolean;
-    denied: PermissionDescriptor[];
-    reasons: string[];
-};
-type PermissionsConfig<TRoles extends readonly string[], TUser = unknown> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]> | ((grant: GrantFn<TUser>) => Record<TRoles[number], Grant[]>);
-    hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
-};
-type Permissions<TRoles extends readonly string[] = readonly string[]> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]>;
-    resolvedGrants: Record<TRoles[number], Grant[]>;
-};
-
-type ForbiddenErrorOptions = {
-    action: PermissionAction;
-    table: DrizzleTable;
-    role: string;
-    descriptors?: PermissionDescriptor[];
-};
-declare class ForbiddenError extends Error {
-    readonly action: PermissionAction;
-    readonly table: DrizzleTable;
-    readonly role: string;
-    readonly descriptors: PermissionDescriptor[];
-    constructor(options: ForbiddenErrorOptions);
-    toJSON(): {
-        name: string;
-        message: string;
-        action: PermissionAction;
-        table: string;
-        role: string;
-    };
-}
-
-export { CRUD_ACTIONS as C, type DrizzleTable as D, ForbiddenError as F, type Grant as G, type PermissionsConfig as P, type WhereClause as W, type Permissions as a, type PermissionAction as b, type PermissionDescriptor as c, type PermissionCheckResult as d, type CrudAction as e, type GrantFn as f };

package/dist/client-CuB6igvw.d.ts

@@ -1,195 +0,0 @@
-/**
- * Minimal structural type for a Drizzle ORM table reference.
- *
- * Drizzle stores table metadata via Symbols (e.g., `Symbol('drizzle:Name')`).
- * This loose type avoids importing `drizzle-orm` directly into the permissions package.
- */
-type DrizzleTable = Record<string | symbol, any>;
-/**
- * Minimal structural type for a Drizzle SQL expression.
- *
- * Matches any object with a `getSQL()` method, which includes Drizzle's
- * `SQL`, `SQLWrapper`, and condition builder results.
- */
-type DrizzleSQL = {
-    getSQL(): unknown;
-};
-/**
- * Extracts the table name string from a Drizzle table reference.
- *
- * @param table - A Drizzle table object containing the `drizzle:Name` symbol.
- * @returns The table name, or `"unknown"` if the symbol is not present.
- */
-declare function getTableName(table: DrizzleTable): string;
-/**
- * A permission action: one of the four CRUD operations, or `"manage"` for all.
- *
- * - `"read"` maps to `SELECT` queries.
- * - `"create"` maps to `INSERT` statements.
- * - `"update"` maps to `UPDATE` statements.
- * - `"delete"` maps to `DELETE` statements.
- * - `"manage"` is shorthand for granting all four CRUD actions.
- */
-type PermissionAction = "read" | "create" | "update" | "delete" | "manage";
-/**
- * A CRUD-only permission action (excludes `"manage"`).
- *
- * Useful when you need to iterate over concrete operations without the
- * `"manage"` shorthand. See also {@link CRUD_ACTIONS}.
- */
-type CrudAction = Exclude<PermissionAction, "manage">;
-/**
- * Readonly array of the four CRUD action strings, useful for iteration.
- *
- * @example
- * ```typescript
- * import { CRUD_ACTIONS } from "@cfast/permissions";
- *
- * for (const action of CRUD_ACTIONS) {
- *   console.log(action); // "read", "create", "update", "delete"
- * }
- * ```
- */
-declare const CRUD_ACTIONS: readonly CrudAction[];
-/**
- * A function that produces a Drizzle `WHERE` clause for row-level permission filtering.
- *
- * @param columns - The table's column references for building filter expressions.
- * @param user - The current user object (from `@cfast/auth`).
- * @returns A Drizzle SQL expression to restrict matching rows, or `undefined` for no restriction.
- */
-type WhereClause = (columns: Record<string, unknown>, user: any) => DrizzleSQL | undefined;
-/**
- * A single permission grant: an action on a subject, optionally restricted by a `where` clause.
- */
-type Grant = {
-    /** The permitted operation. `"manage"` is shorthand for all four CRUD actions. */
-    action: PermissionAction;
-    /** The Drizzle table this grant applies to, or `"all"` for every table. */
-    subject: DrizzleTable | "all";
-    /** Optional row-level filter that restricts which rows this grant covers. */
-    where?: WhereClause;
-};
-/**
- * Type-safe grant builder function, parameterized by the user type.
- *
- * Used when `grants` is provided as a callback in {@link PermissionsConfig}
- * so that `where` clauses receive a correctly typed `user` parameter.
- *
- * @typeParam TUser - The user type passed to `where` clause callbacks.
- */
-type GrantFn<TUser> = (action: PermissionAction, subject: DrizzleTable | "all", options?: {
-    where?: (columns: Record<string, unknown>, user: TUser) => DrizzleSQL | undefined;
-}) => Grant;
-/**
- * Structural description of a permission requirement.
- *
- * Describes *what kind* of operation on *which table* without specifying concrete row values.
- * This is what makes client-side permission introspection possible: you can check whether a
- * role has the right grants without knowing the specific row being accessed.
- *
- * @example
- * ```typescript
- * const descriptor: PermissionDescriptor = {
- *   action: "update",
- *   table: posts,
- * };
- * ```
- */
-type PermissionDescriptor = {
-    /** The operation being checked. */
-    action: PermissionAction;
-    /** The Drizzle table the operation targets. */
-    table: DrizzleTable;
-};
-/**
- * Result of a permission check via {@link checkPermissions}.
- */
-type PermissionCheckResult = {
-    /** `true` only if every descriptor in the check was satisfied. */
-    permitted: boolean;
-    /** The descriptors that were not satisfied. */
-    denied: PermissionDescriptor[];
-    /** Human-readable reasons for each denial. */
-    reasons: string[];
-};
-/**
- * Configuration object for {@link definePermissions}.
- *
- * @typeParam TRoles - Tuple of role name string literals (use `as const`).
- * @typeParam TUser - The user type for typed `where` clauses (defaults to `unknown`).
- */
-type PermissionsConfig<TRoles extends readonly string[], TUser = unknown> = {
-    /** All roles in the application, declared with `as const` for type inference. */
-    roles: TRoles;
-    /** A map from role to grant arrays, or a callback that receives a typed `grant` function. */
-    grants: Record<TRoles[number], Grant[]> | ((grant: GrantFn<TUser>) => Record<TRoles[number], Grant[]>);
-    /** Optional role hierarchy declaring which roles inherit from which. */
-    hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
-};
-/**
- * The resolved permissions object returned by {@link definePermissions}.
- *
- * Contains the original roles and grants, plus the hierarchy-expanded `resolvedGrants`.
- * Pass this to `createDb()` for server-side enforcement or import it on the client
- * for UI-level permission introspection.
- *
- * @typeParam TRoles - Tuple of role name string literals.
- */
-type Permissions<TRoles extends readonly string[] = readonly string[]> = {
-    /** The role names from the configuration. */
-    roles: TRoles;
-    /** The raw grants as declared (before hierarchy expansion). */
-    grants: Record<TRoles[number], Grant[]>;
-    /** Grants expanded with inherited grants from the role hierarchy. */
-    resolvedGrants: Record<TRoles[number], Grant[]>;
-};
-
-/** Options for constructing a {@link ForbiddenError}. */
-type ForbiddenErrorOptions = {
-    /** The action that was denied. */
-    action: PermissionAction;
-    /** The Drizzle table the action targeted. */
-    table: DrizzleTable;
-    /** The role that lacked the permission, if known. */
-    role?: string;
-    /** The full list of permission descriptors that were checked. */
-    descriptors?: PermissionDescriptor[];
-};
-/**
- * Error thrown when a permission check fails during an operation.
- *
- * Extends `Error` with structured fields for the denied action, target table,
- * and role. Includes a `toJSON()` method so it can be serialized across the
- * server/client boundary.
- */
-declare class ForbiddenError extends Error {
-    /** The action that was denied (e.g., `"delete"`). */
-    readonly action: PermissionAction;
-    /** The Drizzle table the action targeted. */
-    readonly table: DrizzleTable;
-    /** The role that lacked the permission, or `undefined` if not specified. */
-    readonly role: string | undefined;
-    /** The full list of permission descriptors that were checked. */
-    readonly descriptors: PermissionDescriptor[];
-    /**
-     * Creates a new `ForbiddenError`.
-     *
-     * @param options - The action, table, and optional role/descriptors for the error.
-     */
-    constructor(options: ForbiddenErrorOptions);
-    /**
-     * Serializes the error to a JSON-safe object for server-to-client transfer.
-     *
-     * @returns A plain object with `name`, `message`, `action`, `table`, and `role` fields.
-     */
-    toJSON(): {
-        name: string;
-        message: string;
-        action: PermissionAction;
-        table: string;
-        role: string | undefined;
-    };
-}
-
-export { CRUD_ACTIONS as C, type DrizzleTable as D, ForbiddenError as F, type Grant as G, type PermissionsConfig as P, type WhereClause as W, type Permissions as a, type PermissionAction as b, type PermissionDescriptor as c, type PermissionCheckResult as d, type CrudAction as e, type GrantFn as f, getTableName as g };

package/dist/client-DduKFZmk.d.ts

@@ -1,59 +0,0 @@
-type DrizzleTable = Record<string | symbol, any>;
-type DrizzleSQL = {
-    getSQL(): unknown;
-};
-declare function getTableName(table: DrizzleTable): string;
-type PermissionAction = "read" | "create" | "update" | "delete" | "manage";
-type CrudAction = Exclude<PermissionAction, "manage">;
-declare const CRUD_ACTIONS: readonly CrudAction[];
-type WhereClause = (columns: Record<string, unknown>, user: any) => DrizzleSQL | undefined;
-type Grant = {
-    action: PermissionAction;
-    subject: DrizzleTable | "all";
-    where?: WhereClause;
-};
-type GrantFn<TUser> = (action: PermissionAction, subject: DrizzleTable | "all", options?: {
-    where?: (columns: Record<string, unknown>, user: TUser) => DrizzleSQL | undefined;
-}) => Grant;
-type PermissionDescriptor = {
-    action: PermissionAction;
-    table: DrizzleTable;
-};
-type PermissionCheckResult = {
-    permitted: boolean;
-    denied: PermissionDescriptor[];
-    reasons: string[];
-};
-type PermissionsConfig<TRoles extends readonly string[], TUser = unknown> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]> | ((grant: GrantFn<TUser>) => Record<TRoles[number], Grant[]>);
-    hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
-};
-type Permissions<TRoles extends readonly string[] = readonly string[]> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]>;
-    resolvedGrants: Record<TRoles[number], Grant[]>;
-};
-
-type ForbiddenErrorOptions = {
-    action: PermissionAction;
-    table: DrizzleTable;
-    role?: string;
-    descriptors?: PermissionDescriptor[];
-};
-declare class ForbiddenError extends Error {
-    readonly action: PermissionAction;
-    readonly table: DrizzleTable;
-    readonly role: string | undefined;
-    readonly descriptors: PermissionDescriptor[];
-    constructor(options: ForbiddenErrorOptions);
-    toJSON(): {
-        name: string;
-        message: string;
-        action: PermissionAction;
-        table: string;
-        role: string | undefined;
-    };
-}
-
-export { CRUD_ACTIONS as C, type DrizzleTable as D, ForbiddenError as F, type Grant as G, type PermissionsConfig as P, type WhereClause as W, type Permissions as a, type PermissionAction as b, type PermissionDescriptor as c, type PermissionCheckResult as d, type CrudAction as e, type GrantFn as f, getTableName as g };

package/dist/client-FbortuK3.d.ts

@@ -1,53 +0,0 @@
-import { Table, SQL } from 'drizzle-orm';
-
-type PermissionAction = "read" | "create" | "update" | "delete" | "manage";
-type CrudAction = Exclude<PermissionAction, "manage">;
-declare const CRUD_ACTIONS: readonly CrudAction[];
-type WhereClause<TUser = unknown> = (columns: Record<string, unknown>, user: TUser) => SQL | undefined;
-type Grant<TUser = unknown> = {
-    action: PermissionAction;
-    subject: Table | "all";
-    where?: WhereClause<TUser>;
-};
-type PermissionDescriptor = {
-    action: PermissionAction;
-    table: Table;
-};
-type PermissionCheckResult = {
-    permitted: boolean;
-    denied: PermissionDescriptor[];
-    reasons: string[];
-};
-type PermissionsConfig<TRoles extends readonly string[], TUser = unknown> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant<TUser>[]>;
-    hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
-};
-type Permissions<TRoles extends readonly string[] = readonly string[], TUser = unknown> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant<TUser>[]>;
-    resolvedGrants: Record<TRoles[number], Grant<TUser>[]>;
-};
-
-type ForbiddenErrorOptions = {
-    action: PermissionAction;
-    table: Table;
-    role: string;
-    descriptors?: PermissionDescriptor[];
-};
-declare class ForbiddenError extends Error {
-    readonly action: PermissionAction;
-    readonly table: Table;
-    readonly role: string;
-    readonly descriptors: PermissionDescriptor[];
-    constructor(options: ForbiddenErrorOptions);
-    toJSON(): {
-        name: string;
-        message: string;
-        action: PermissionAction;
-        table: string;
-        role: string;
-    };
-}
-
-export { CRUD_ACTIONS as C, ForbiddenError as F, type Grant as G, type PermissionsConfig as P, type WhereClause as W, type Permissions as a, type PermissionAction as b, type PermissionDescriptor as c, type PermissionCheckResult as d, type CrudAction as e };