@cfast/actions 0.2.0 → 0.3.1

package/dist/client.d.ts

@@ -32,6 +32,60 @@ declare function useActions<const TNames extends readonly string[]>(descriptor:
     [K in TNames[number]]: (input?: Serializable) => ActionHookResult;
 };
 
+/** Permission methods added to items with `_can`. */
+type CfastItemMethods = {
+    canRead: () => ActionHookResult;
+    canCreate: () => ActionHookResult;
+    canEdit: () => ActionHookResult;
+    canDelete: () => ActionHookResult;
+};
+/** An item with `_can` gets permission methods mixed in. */
+type CfastItem<T> = T & CfastItemMethods;
+/** A collection gets `canAdd()` plus each item gets permission methods. */
+type CfastCollection<T> = CfastItem<T>[] & {
+    canAdd: () => ActionHookResult;
+};
+/**
+ * Transforms a loader return type:
+ * - Arrays of objects with `_can` -> {@link CfastCollection}
+ * - Objects with `_can` -> {@link CfastItem}
+ * - Other values -> unchanged
+ */
+type CfastLoaderData<T> = {
+    [K in keyof T]: T[K] extends (infer U)[] ? U extends Record<string, unknown> ? CfastCollection<U> : T[K] : T[K] extends Record<string, unknown> ? CfastItem<T[K]> : T[K];
+};
+/**
+ * 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>>(): CfastLoaderData<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. */
     action: Record<string, string | number | boolean | null | undefined>;
@@ -57,4 +111,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, type CfastCollection, type CfastItem, type CfastItemMethods, type CfastLoaderData, 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,4 +1,4 @@
-import { Grant, PermissionDescriptor } from '@cfast/permissions';
+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/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>(
@@ -112,6 +127,76 @@ 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. The return type is `CfastLoaderData<...>`, which automatically adds permission methods to the TypeScript types so consumers get full autocomplete without local type helpers.
+
+```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`.
+
+#### Permission helper types
+
+Exported from `@cfast/actions/client` for consumers who need to annotate variables or build custom abstractions:
+
+```typescript
+import type {
+  CfastItem,
+  CfastCollection,
+  CfastItemMethods,
+  CfastLoaderData,
+} from "@cfast/actions/client";
+
+/** Permission methods added to items with _can */
+type CfastItemMethods = {
+  canRead: () => ActionHookResult;
+  canCreate: () => ActionHookResult;
+  canEdit: () => ActionHookResult;
+  canDelete: () => ActionHookResult;
+};
+
+/** An item with _can gets permission methods mixed in */
+type CfastItem<T> = T & CfastItemMethods;
+
+/** A collection gets canAdd() plus each item gets permission methods */
+type CfastCollection<T> = CfastItem<T>[] & {
+  canAdd: () => ActionHookResult;
+};
+
+/** Transforms a loader return type -- arrays become CfastCollection, objects become CfastItem, primitives pass through */
+type CfastLoaderData<T> = {
+  [K in keyof T]: T[K] extends (infer U)[]
+    ? U extends Record<string, unknown>
+      ? CfastCollection<U>
+      : T[K]
+    : T[K] extends Record<string, unknown>
+      ? CfastItem<T[K]>
+      : T[K];
+};
+```
+
 `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.2.0",
+  "version": "0.3.1",
   "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.5.0",
-    "@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",