@cfast/actions 0.1.3 → 0.3.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { C as ClientDescriptor, S as Serializable } from './types-CJpjon5s.js';
+import { C as ClientDescriptor, S as Serializable } from './types-C1PGA5l3.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Form } from 'react-router';
 import { ComponentProps, ReactNode } from 'react';
@@ -9,8 +9,16 @@ import '@cfast/permissions';
  * Creates a ClientDescriptor for use in client code without importing
  * server modules. The action names must match the keys passed to
  * `composeActions` or the single action name from `createAction`.
+ *
+ * Pass a `readonly` tuple (`as const`) to get compile-time type-checking
+ * of action names throughout the client code:
+ *
+ * ```ts
+ * const client = clientDescriptor(["create", "delete"] as const);
+ * // client is ClientDescriptor<readonly ["create", "delete"]>
+ * ```
  */
-declare function clientDescriptor(actionNames: readonly string[]): ClientDescriptor;
+declare function clientDescriptor<const TNames extends readonly string[]>(actionNames: TNames): ClientDescriptor<TNames>;
 type ActionHookResult = {
     permitted: boolean;
     invisible: boolean;
@@ -20,7 +28,41 @@ type ActionHookResult = {
     data: unknown | undefined;
     error: unknown | undefined;
 };
-declare function useActions(descriptor: ClientDescriptor): Record<string, (input?: Serializable) => ActionHookResult>;
+declare function useActions<const TNames extends readonly string[]>(descriptor: ClientDescriptor<TNames>): {
+    [K in TNames[number]]: (input?: Serializable) => ActionHookResult;
+};
+
+/**
+ * Client hook that replaces `useLoaderData()` for routes using `cfastJson()`.
+ *
+ * Returns the same data but wraps arrays and objects that have `_can` with
+ * permission helper methods:
+ *
+ * - **Collections** (arrays with items that have `_can`): array works normally
+ *   (indexing, `.map()`, etc.) AND has `canAdd()`. Each item has `canEdit()`,
+ *   `canDelete()`, `canRead()`, `canCreate()`.
+ * - **Items** (objects with `_can`): row properties directly accessible,
+ *   plus `canEdit()`, `canDelete()`, `canRead()`, `canCreate()`.
+ * - **Other fields**: passed through unchanged.
+ *
+ * Each `can*()` method returns an {@link ActionHookResult}.
+ *
+ * @example
+ * ```tsx
+ * const { documents } = useCfastLoader<typeof loader>();
+ *
+ * // Collection-level
+ * documents.canAdd()          // -> ActionHookResult
+ *
+ * // Row fields accessible directly
+ * documents[0].title          // "Hello World"
+ *
+ * // Row-level
+ * documents[0].canEdit()      // -> ActionHookResult
+ * documents[0].canDelete()    // -> ActionHookResult
+ * ```
+ */
+declare function useCfastLoader<T extends (...args: any[]) => any = () => Record<string, unknown>>(): ReturnType<T> extends Promise<infer R> ? R : ReturnType<T>;
 
 type ActionFormProps = Omit<ComponentProps<typeof Form>, "children" | "action"> & {
     /** Object with `_action` key and input fields to inject as hidden inputs. */
@@ -47,4 +89,4 @@ type ActionFormProps = Omit<ComponentProps<typeof Form>, "children" | "action">
  */
 declare function ActionForm({ action, children, ...formProps }: ActionFormProps): react_jsx_runtime.JSX.Element;
 
-export { ActionForm, type ActionHookResult, ClientDescriptor, clientDescriptor, useActions };
+export { ActionForm, type ActionHookResult, ClientDescriptor, clientDescriptor, useActions, useCfastLoader };

package/dist/client.js

@@ -67,6 +67,117 @@ function useActions(descriptor) {
   return result;
 }
 
+// src/client/use-cfast-loader.ts
+import { useMemo } from "react";
+import { useLoaderData as useLoaderData2 } from "react-router";
+function makeResult(permitted) {
+  return {
+    permitted,
+    invisible: false,
+    reason: null,
+    submit: () => {
+    },
+    pending: false,
+    data: void 0,
+    error: void 0
+  };
+}
+function wrapItem(item) {
+  const can = item._can ?? {};
+  const wrapped = /* @__PURE__ */ Object.create(null);
+  for (const [key, value] of Object.entries(item)) {
+    if (key === "_can") continue;
+    Object.defineProperty(wrapped, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+  Object.defineProperty(wrapped, "_can", {
+    value: item._can,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  Object.defineProperty(wrapped, "canRead", {
+    value: () => makeResult(can.read ?? false),
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  Object.defineProperty(wrapped, "canCreate", {
+    value: () => makeResult(can.create ?? false),
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  Object.defineProperty(wrapped, "canEdit", {
+    value: () => makeResult(can.update ?? false),
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  Object.defineProperty(wrapped, "canDelete", {
+    value: () => makeResult(can.delete ?? false),
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  return wrapped;
+}
+function wrapCollection(arr, tablePerms) {
+  const wrappedItems = arr.map((item) => {
+    if (item && typeof item === "object" && "_can" in item) {
+      return wrapItem(item);
+    }
+    return item;
+  });
+  const tableName = arr._tableName;
+  const perms = tableName ? tablePerms[tableName] : void 0;
+  const result = [...wrappedItems];
+  if (tableName) {
+    Object.defineProperty(result, "_tableName", {
+      value: tableName,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+  }
+  Object.defineProperty(result, "canAdd", {
+    value: () => makeResult(perms?.create ?? false),
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  return result;
+}
+function useCfastLoader() {
+  const raw = useLoaderData2();
+  return useMemo(() => {
+    const tablePerms = raw._tablePerms ?? {};
+    const result = {};
+    for (const [key, value] of Object.entries(raw)) {
+      if (key === "_tablePerms") {
+        continue;
+      }
+      if (Array.isArray(value)) {
+        const hasCanItems = value.length > 0 && value[0] !== null && typeof value[0] === "object" && "_can" in value[0];
+        if (hasCanItems) {
+          result[key] = wrapCollection(value, tablePerms);
+        } else {
+          result[key] = value;
+        }
+      } else if (value !== null && typeof value === "object" && !Array.isArray(value) && "_can" in value) {
+        result[key] = wrapItem(value);
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  }, [raw]);
+}
+
 // src/client/action-form.tsx
 import { Form } from "react-router";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -81,5 +192,6 @@ function ActionForm({ action, children, ...formProps }) {
 export {
   ActionForm,
   clientDescriptor,
-  useActions
+  useActions,
+  useCfastLoader
 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { Grant, PermissionDescriptor } from '@cfast/permissions';
-import { A as ActionPermissionStatus, a as ActionServices, b as ActionsConfig, O as OperationsFn, c as ActionDefinition, d as ComposedActions } from './types-CJpjon5s.js';
-export { e as ActionContext, f as ActionPermissionsMap, C as ClientDescriptor, D as DispatchArgs, R as RequestArgs, S as Serializable } from './types-CJpjon5s.js';
+import { Grant, PermissionDescriptor, SchemaMap, CrudAction } from '@cfast/permissions';
+import { A as ActionPermissionStatus, a as ActionServices, b as ActionsConfig, O as OperationsFn, c as ActionDefinition, d as ComposedActions } from './types-C1PGA5l3.js';
+export { e as ActionContext, f as ActionPermissionsMap, C as ClientDescriptor, D as DispatchArgs, R as RequestArgs, S as Serializable } from './types-C1PGA5l3.js';
 import '@cfast/db';
 
 /**
@@ -241,6 +241,41 @@ declare function createActions<TUser = any, TServices extends ActionServices = A
     composeActions: <TActions extends Record<string, ActionDefinition<any, any, any>>>(actions: TActions) => ComposedActions<TActions>;
 };
 
+/**
+ * Server-side loader helper that wraps data with table-level permission
+ * metadata and serializes dates.
+ *
+ * Replaces the manual pattern of calling `can()` per table and `toJSON()`
+ * separately. The returned object contains:
+ *
+ * - All fields from `data`, with Dates converted to ISO strings.
+ * - `_tablePerms`: a `Record<tableName, Record<CrudAction, boolean>>` map
+ *   covering every table in the schema.
+ * - Each array value in `data` is annotated with a non-enumerable
+ *   `_tableName` property matching the first table whose SQL name appears
+ *   as the data key. This allows the client-side `useCfastLoader` hook to
+ *   look up `canAdd()` for the correct table.
+ *
+ * @param grants - The user's resolved permission grants.
+ * @param schema - A schema map (e.g. `import * as schema from "./schema"`).
+ * @param data - The loader data to wrap.
+ * @returns A serializable object with `_tablePerms` embedded.
+ *
+ * @example
+ * ```ts
+ * import { cfastJson } from "@cfast/actions";
+ * import * as schema from "../db/schema";
+ *
+ * export async function loader({ context }) {
+ *   const documents = await db.query(documentsTable).findMany().run();
+ *   return cfastJson(ctx.auth.grants, schema, { documents });
+ * }
+ * ```
+ */
+declare function cfastJson<TData extends Record<string, unknown>>(grants: Grant[], schema: SchemaMap, data: TData): TData & {
+    _tablePerms: Record<string, Record<CrudAction, boolean>>;
+};
+
 /**
  * Options accepted by {@link forwardRequest}.
  *
@@ -328,4 +363,4 @@ type ForwardRequestInit = {
  */
 declare function forwardRequest(original: Request, init?: ForwardRequestInit): Request;
 
-export { ActionDefinition, ActionPermissionStatus, ActionServices, ActionsConfig, ComposedActions, type ForwardRequestInit, type InferInput, type InputField, type InputParser, type InputSchema, InvalidInputError, OperationsFn, checkPermissionStatus, createActions, defineInput, forwardRequest, z };
+export { ActionDefinition, ActionPermissionStatus, ActionServices, ActionsConfig, ComposedActions, type ForwardRequestInit, type InferInput, type InputField, type InputParser, type InputSchema, InvalidInputError, OperationsFn, cfastJson, checkPermissionStatus, createActions, defineInput, forwardRequest, z };

package/dist/index.js

@@ -154,6 +154,51 @@ function createActions(config) {
   return { createAction, composeActions };
 }
 
+// src/cfast-json.ts
+import { resolveTablePermissions } from "@cfast/permissions";
+import { toJSON } from "@cfast/db";
+function cfastJson(grants, schema, data) {
+  const tablePerms = resolveTablePermissions(grants, schema);
+  const serialized = toJSON(data);
+  const keyToTableName = {};
+  for (const [jsKey, table] of Object.entries(schema)) {
+    const DRIZZLE_NAME_SYMBOL = /* @__PURE__ */ Symbol.for("drizzle:Name");
+    if (typeof table === "object" && table !== null) {
+      const name = Reflect.get(table, DRIZZLE_NAME_SYMBOL);
+      if (typeof name === "string") {
+        keyToTableName[jsKey] = name;
+      }
+    }
+  }
+  for (const [key, value] of Object.entries(serialized)) {
+    if (Array.isArray(value)) {
+      let tableName;
+      if (keyToTableName[key]) {
+        tableName = keyToTableName[key];
+      } else {
+        for (const sqlName of Object.values(keyToTableName)) {
+          if (sqlName === key) {
+            tableName = sqlName;
+            break;
+          }
+        }
+      }
+      if (tableName) {
+        Object.defineProperty(value, "_tableName", {
+          value: tableName,
+          enumerable: false,
+          writable: false,
+          configurable: false
+        });
+      }
+    }
+  }
+  return {
+    ...serialized,
+    _tablePerms: tablePerms
+  };
+}
+
 // src/input-schema.ts
 var InvalidInputError = class extends Error {
   /** Field-keyed map of validation errors. */
@@ -340,6 +385,7 @@ function forwardRequest(original, init = {}) {
 }
 export {
   InvalidInputError,
+  cfastJson,
   checkPermissionStatus,
   createActions,
   defineInput,

package/dist/{types-CJpjon5s.d.ts → types-C1PGA5l3.d.ts}

@@ -223,11 +223,11 @@ type ActionPermissionsMap = Record<string, ActionPermissionStatus>;
  * Created by {@link ActionDefinition.client} or {@link ComposedActions.client}.
  * Contains the action names and the key used to read permission data from loader results.
  */
-type ClientDescriptor = {
+type ClientDescriptor<TNames extends readonly string[] = readonly string[]> = {
     /** Brand field to distinguish this type at the type level. */
     _brand: "ActionClientDescriptor";
     /** The list of action names this descriptor covers. */
-    actionNames: readonly string[];
+    actionNames: TNames;
     /** The loader-data key where {@link ActionPermissionsMap} is stored. */
     permissionsKey: string;
 };

package/llms.txt

@@ -16,6 +16,21 @@ Use this package when you need React Router route actions that automatically che
 
 ### Server (`@cfast/actions`)
 
+#### `cfastJson(grants, schema, data)`
+Server-side loader helper that wraps data with table-level permission metadata and serializes dates. Replaces the manual pattern of calling `can()` per table and `toJSON()` separately.
+
+```typescript
+import { cfastJson } from "@cfast/actions";
+import * as schema from "../db/schema";
+
+export async function loader({ context }) {
+  const documents = await db.query(documentsTable).findMany().run();
+  return cfastJson(ctx.auth.grants, schema, { documents });
+}
+```
+
+Returns the data with `_tablePerms` embedded and dates serialized. Arrays whose keys match schema table names are annotated with a non-enumerable `_tableName` property so `useCfastLoader` can resolve `canAdd()` for the correct table.
+
 ```typescript
 function createActions<TUser>(config: ActionsConfig<TUser>): {
   createAction: <TInput, TResult>(
@@ -68,9 +83,31 @@ type ActionPermissionsMap = Record<string, ActionPermissionStatus>;
 
 ### Client (`@cfast/actions/client`)
 
+#### Type-safe `clientDescriptor()` and `useActions()`
+
+`clientDescriptor()` now uses `const` type parameters to infer the literal tuple
+type from the action names array. `useActions()` returns a mapped type keyed by
+those literal names instead of `Record<string, ...>`, giving compile-time
+autocomplete and error checking on action names.
+
+```typescript
+// Type-safe: actions.create and actions.delete are typed, typos are caught
+const client = clientDescriptor(["create", "delete"]);
+// client is ClientDescriptor<readonly ["create", "delete"]>
+
+const actions = useActions(client);
+// actions is { create: (input?) => ActionHookResult; delete: (input?) => ActionHookResult }
+// actions.creat → TypeScript error (typo caught at compile time)
+```
+
 ```typescript
-function useActions(descriptor: ClientDescriptor): Record<string, (input?: Serializable) => ActionHookResult>;
-function clientDescriptor(actionNames: readonly string[]): ClientDescriptor;
+function useActions<const TNames extends readonly string[]>(
+  descriptor: ClientDescriptor<TNames>,
+): { [K in TNames[number]]: (input?: Serializable) => ActionHookResult };
+
+function clientDescriptor<const TNames extends readonly string[]>(
+  actionNames: TNames,
+): ClientDescriptor<TNames>;
 
 function ActionForm(props: ActionFormProps): JSX.Element;
 
@@ -90,6 +127,36 @@ type ActionFormProps = Omit<ComponentProps<typeof Form>, "children" | "action">
 };
 ```
 
+#### `useCfastLoader<T>()`
+Client hook that replaces `useLoaderData()` for routes using `cfastJson()`. Returns the same data but wraps arrays and objects that have `_can` with permission helper methods.
+
+```typescript
+import { useCfastLoader } from "@cfast/actions/client";
+
+const { documents } = useCfastLoader<typeof loader>();
+
+// Collection-level: "can I add to this table?"
+documents.canAdd()          // -> ActionHookResult
+
+// Row fields accessible directly (no .data wrapper)
+documents[0].title          // "Hello World"
+
+// Row-level: "can I edit THIS item?"
+documents[0].canEdit()      // -> ActionHookResult
+documents[0].canDelete()    // -> ActionHookResult
+
+// Single items work too
+const { document } = useCfastLoader<typeof loader>();
+document.canEdit()          // -> ActionHookResult
+```
+
+Wrapping rules:
+- Array where items have `_can` -> collection: array + `canAdd()`, each item has `canEdit()`, `canDelete()`, `canRead()`, `canCreate()`
+- Object with `_can` -> item: row properties directly accessible + `can*()` methods
+- Otherwise -> pass through unchanged
+
+All `can*()` methods return `ActionHookResult` with `permitted`, `invisible`, `reason`, `submit` (no-op), `pending` (false), `data`, `error`.
+
 `ActionForm` is a form wrapper that auto-injects hidden fields from an action descriptor object. Replaces manual `<input type="hidden">` patterns when using `composeActions`.
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/actions",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Multi-action routes and permission-aware action definitions for React Router",
   "keywords": [
     "cfast",
@@ -39,7 +39,7 @@
   },
   "peerDependencies": {
     "@cfast/db": ">=0.3.0 <0.5.0",
-    "@cfast/permissions": ">=0.3.0 <0.6.0",
+    "@cfast/permissions": ">=0.3.0 <0.7.0",
     "react": "^19.0.0",
     "react-router": "^7.0.0"
   },
@@ -59,8 +59,8 @@
     "tsup": "^8",
     "typescript": "^5.7",
     "vitest": "^4.1.0",
-    "@cfast/db": "0.4.1",
-    "@cfast/permissions": "0.5.1"
+    "@cfast/db": "0.8.0",
+    "@cfast/permissions": "0.7.0"
   },
   "scripts": {
     "build": "tsup src/index.ts src/client.ts --format esm --dts",