@cfast/actions 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Schmidt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# @cfast/actions
+
+Reusable, type-safe, permission-aware actions for React Router. Define operations once — permissions and execution come from the same place.
+
+## Setup
+
+Create a factory that provides context (db, user, grants) for all actions:
+
+```typescript
+// app/actions.server.ts
+import { createActions } from "@cfast/actions";
+
+export const { createAction, composeActions } = createActions({
+  getContext: async ({ request }) => {
+    const ctx = await requireAuthContext(request);
+    const db = createCfDb(env.DB, ctx);
+    return { db, user: ctx.user, grants: ctx.grants };
+  },
+});
+```
+
+`createActions` returns two functions scoped to your context provider: `createAction` and `composeActions`.
+
+## Defining Actions
+
+`createAction<TInput, TResult>(operationsFn)` takes an operations function and returns an action definition with four facets:
+
+- `.action` — React Router action handler
+- `.loader(loaderFn)` — wraps a loader to inject `_actionPermissions`
+- `.client` — descriptor for the `useActions` hook
+- `.buildOperation(db, input, ctx)` — builds the raw `Operation` (for composition)
+
+```typescript
+// app/actions/posts.ts
+import { compose } from "@cfast/db";
+import { eq } from "drizzle-orm";
+import { createAction } from "~/actions.server";
+import { posts, auditLogs } from "~/db/schema";
+
+export const deletePost = createAction<{ postId: string }, Response>(
+  (db, input, ctx) =>
+    compose(
+      [
+        db.delete(posts).where(eq(posts.id, input.postId)),
+        db.insert(auditLogs).values({
+          id: nanoid(),
+          userId: ctx.user.id,
+          action: "post.deleted",
+          targetType: "post",
+          targetId: input.postId,
+          metadata: JSON.stringify({ title: input.title }),
+        }),
+      ],
+      async (runDelete, runAudit) => {
+        await runDelete({});
+        await runAudit({});
+        return redirect("/");
+      },
+    ),
+);
+```
+
+The operations function receives `(db, input, ctx)` where `ctx` has `{ db, user, grants }`. It returns an `Operation<TResult>` from `@cfast/db` — either a single operation or a `compose()`'d workflow.
+
+## Composing Multiple Actions
+
+When a route needs multiple actions, use `composeActions` with a named object:
+
+```typescript
+// app/routes/posts.$slug.tsx
+import { composeActions } from "~/actions.server";
+import { deletePost, publishPost, unpublishPost, addComment } from "~/actions/posts";
+
+const composed = composeActions({
+  deletePost,
+  publishPost,
+  unpublishPost,
+  addComment,
+});
+
+export const action = composed.action;
+```
+
+The object keys become the action discriminators. When a form submits with `<input type="hidden" name="_action" value="deletePost" />`, `composeActions` routes to the correct handler. JSON requests use `{ _action: "deletePost", ...input }`.
+
+`composeActions` returns the same four facets as `createAction`: `.action`, `.loader()`, `.client`, and `.actions` (the original definitions).
+
+## Loader Integration
+
+Wrap your loader with `.loader()` to inject permission status for the client:
+
+```typescript
+// Single action
+export const loader = deletePost.loader(async ({ request, params }) => {
+  // ... your normal loader logic
+  return { post, author };
+});
+
+// Composed actions
+export const loader = composed.loader(async ({ request, params }) => {
+  return { post, author };
+});
+```
+
+The wrapper calls `getContext`, builds each action's `Operation` to extract permission descriptors, checks them against the user's grants, and merges `_actionPermissions` into the loader data. The client never receives raw permission descriptors.
+
+## Client Usage
+
+The `useActions` hook reads `_actionPermissions` from loader data and provides submission controls per action:
+
+```typescript
+import { useActions } from "@cfast/actions/client";
+
+function PostActions({ postId }: { postId: string }) {
+  const actions = useActions(composed.client);
+
+  const remove = actions.deletePost({ postId });
+  const publish = actions.publishPost({ postId });
+
+  return (
+    <>
+      <button
+        onClick={publish.submit}
+        disabled={!publish.permitted || publish.pending}
+        hidden={publish.invisible}
+      >
+        Publish
+      </button>
+      <button
+        onClick={remove.submit}
+        disabled={!remove.permitted || remove.pending}
+      >
+        Delete
+      </button>
+    </>
+  );
+}
+```
+
+Each action function returns:
+
+| Property | Type | Description |
+|---|---|---|
+| `permitted` | `boolean` | Whether the user has the required structural permissions |
+| `invisible` | `boolean` | `true` when the user lacks all permissions (hide the UI entirely) |
+| `reason` | `string \| null` | Human-readable explanation when `permitted` is `false` |
+| `submit` | `() => void` | Submits the action via fetcher with `_action` discriminator |
+| `pending` | `boolean` | `true` while the fetcher is in flight |
+| `data` | `unknown` | The action's return value after execution |
+| `error` | `unknown` | Error if the action failed |
+
+## Input Parsing
+
+Actions accept input from both FormData and JSON. The `_action` field is stripped automatically:
+
+- **FormData**: `<input name="_action" value="deletePost" />` + other fields
+- **JSON**: `{ _action: "deletePost", postId: "123" }`
+
+## Exports
+
+Server (`@cfast/actions`):
+
+```typescript
+export { createActions, checkPermissionStatus } from "./create-actions.js";
+export type {
+  Serializable, ActionContext, RequestArgs, ActionsConfig,
+  OperationsFn, ActionPermissionStatus, ActionPermissionsMap,
+  ClientDescriptor, ActionDefinition, ComposedActions,
+} from "./types.js";
+```
+
+Client (`@cfast/actions/client`):
+
+```typescript
+export { useActions } from "./client/use-actions.js";
+export type { ActionHookResult } from "./client/use-actions.js";
+```
+
+## Integration
+
+- **`@cfast/db`** — Actions use `Operation` and `compose()` from `@cfast/db`. Permission descriptors are extracted from operations.
+- **`@cfast/permissions`** — Grants flow through `getContext`. `checkPermissionStatus` matches grants against operation permission descriptors.
+- **`@cfast/ui`** — UI components can consume `useActions()` for automatic permission-aware rendering.

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { C as ClientDescriptor, S as Serializable } from './types-Dolh-eut.js';
+import '@cfast/db';
+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`.
+ */
+declare function clientDescriptor(actionNames: readonly string[]): ClientDescriptor;
+type ActionHookResult = {
+    permitted: boolean;
+    invisible: boolean;
+    reason: string | null;
+    submit: () => void;
+    pending: boolean;
+    data: unknown | undefined;
+    error: unknown | undefined;
+};
+declare function useActions(descriptor: ClientDescriptor): Record<string, (input?: Serializable) => ActionHookResult>;
+
+export { type ActionHookResult, ClientDescriptor, clientDescriptor, useActions };

package/dist/client.js

@@ -0,0 +1,72 @@
+// src/client/use-actions.ts
+import { useLoaderData, useFetcher } from "react-router";
+function clientDescriptor(actionNames) {
+  return {
+    _brand: "ActionClientDescriptor",
+    actionNames,
+    permissionsKey: "_actionPermissions"
+  };
+}
+function asRecord(value) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  return {};
+}
+function isPermissionStatus(v) {
+  if (v === null || typeof v !== "object") return false;
+  const obj = v;
+  return typeof obj.permitted === "boolean" && typeof obj.invisible === "boolean" && (obj.reason === null || typeof obj.reason === "string");
+}
+function extractPermissions(loaderData) {
+  const raw = loaderData._actionPermissions;
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return {};
+  }
+  const map = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (isPermissionStatus(value)) {
+      map[key] = value;
+    }
+  }
+  return map;
+}
+function useActions(descriptor) {
+  const loaderData = asRecord(useLoaderData());
+  const permissions = extractPermissions(loaderData);
+  const fetchers = descriptor.actionNames.map(() => useFetcher());
+  const result = {};
+  for (let i = 0; i < descriptor.actionNames.length; i++) {
+    const name = descriptor.actionNames[i];
+    const fetcher = fetchers[i];
+    const status = permissions[name] ?? {
+      permitted: true,
+      invisible: false,
+      reason: null
+    };
+    result[name] = (input) => ({
+      ...status,
+      submit: () => {
+        const formData = new FormData();
+        formData.set("_action", name);
+        if (input && typeof input === "object" && !Array.isArray(input)) {
+          const entries = Object.entries(input);
+          for (const [key, value] of entries) {
+            if (value !== null && value !== void 0) {
+              formData.set(key, String(value));
+            }
+          }
+        }
+        fetcher.submit(formData, { method: "POST" });
+      },
+      pending: fetcher.state !== "idle",
+      data: fetcher.data,
+      error: void 0
+    });
+  }
+  return result;
+}
+export {
+  clientDescriptor,
+  useActions
+};

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { Grant, PermissionDescriptor } from '@cfast/permissions';
+import { A as ActionPermissionStatus, a as ActionsConfig, O as OperationsFn, b as ActionDefinition, c as ComposedActions } from './types-Dolh-eut.js';
+export { d as ActionContext, e as ActionPermissionsMap, C as ClientDescriptor, R as RequestArgs, S as Serializable } from './types-Dolh-eut.js';
+import '@cfast/db';
+
+/**
+ * Checks a user's {@link Grant | grants} against a set of permission descriptors
+ * and returns an {@link ActionPermissionStatus}.
+ *
+ * If no descriptors are provided the action is unconditionally permitted.
+ * When some descriptors are denied, `permitted` is `false` and `reason`
+ * lists the missing permissions. When *all* descriptors are denied,
+ * `invisible` is also `true` (indicating the UI should hide the control entirely).
+ *
+ * @param grants - The user's resolved permission grants.
+ * @param descriptors - Permission descriptors extracted from an operation.
+ * @returns The resolved {@link ActionPermissionStatus} for the action.
+ *
+ * @example
+ * ```ts
+ * import { checkPermissionStatus } from "@cfast/actions";
+ *
+ * const status = checkPermissionStatus(user.grants, operation.permissions);
+ * if (!status.permitted) {
+ *   console.log(status.reason); // "Missing permissions: delete on posts"
+ * }
+ * ```
+ */
+declare function checkPermissionStatus(grants: Grant[], descriptors: PermissionDescriptor[]): ActionPermissionStatus;
+/**
+ * Creates a scoped action factory bound to a shared context provider.
+ *
+ * Returns two functions — `createAction` and `composeActions` — that share the
+ * same `getContext` callback. This ensures every action in the application resolves
+ * its database, user, and grants consistently.
+ *
+ * @typeParam TUser - The shape of the authenticated user object.
+ * @param config - The {@link ActionsConfig} providing the `getContext` callback.
+ * @returns An object with `createAction` and `composeActions` functions.
+ *
+ * @example
+ * ```ts
+ * import { createActions } from "@cfast/actions";
+ *
+ * export const { createAction, composeActions } = createActions({
+ *   getContext: async ({ request }) => {
+ *     const ctx = await requireAuthContext(request);
+ *     const db = createCfDb(env.DB, ctx);
+ *     return { db, user: ctx.user, grants: ctx.grants };
+ *   },
+ * });
+ * ```
+ */
+declare function createActions<TUser = any>(config: ActionsConfig<TUser>): {
+    createAction: <TInput, TResult>(operationsFn: OperationsFn<TInput, TResult, TUser>) => ActionDefinition<TInput, TResult, TUser>;
+    composeActions: <TActions extends Record<string, ActionDefinition<any, any, any>>>(actions: TActions) => ComposedActions<TActions>;
+};
+
+export { ActionDefinition, ActionPermissionStatus, ActionsConfig, ComposedActions, OperationsFn, checkPermissionStatus, createActions };

package/dist/index.js

@@ -0,0 +1,141 @@
+// src/create-actions.ts
+import { getTableName } from "@cfast/permissions";
+
+// src/parse-input.ts
+async function parseBody(request) {
+  const contentType = request.headers.get("Content-Type") ?? "";
+  if (contentType.includes("application/json")) {
+    const body = await request.clone().json();
+    const { _action, ...input2 } = body;
+    return { actionName: typeof _action === "string" ? _action : null, input: input2 };
+  }
+  const formData = await request.clone().formData();
+  const input = {};
+  let actionName = null;
+  for (const [key, value] of formData.entries()) {
+    if (key === "_action") {
+      actionName = typeof value === "string" ? value : null;
+    } else {
+      input[key] = value;
+    }
+  }
+  return { actionName, input };
+}
+async function parseInput(request) {
+  const { input } = await parseBody(request);
+  return input;
+}
+async function extractActionName(request) {
+  const { actionName } = await parseBody(request);
+  return actionName;
+}
+
+// src/create-actions.ts
+function checkPermissionStatus(grants, descriptors) {
+  if (descriptors.length === 0) {
+    return { permitted: true, invisible: false, reason: null };
+  }
+  const denied = [];
+  for (const desc of descriptors) {
+    const matched = grants.some((grant) => {
+      const actionMatch = grant.action === "manage" || grant.action === desc.action;
+      const subjectMatch = grant.subject === "all" || typeof grant.subject === "object" && getTableName(grant.subject) === getTableName(desc.table);
+      return actionMatch && subjectMatch;
+    });
+    if (!matched) {
+      denied.push(desc);
+    }
+  }
+  if (denied.length === 0) {
+    return { permitted: true, invisible: false, reason: null };
+  }
+  const reason = denied.map((d) => `${d.action} on ${getTableName(d.table)}`).join(", ");
+  return {
+    permitted: false,
+    invisible: denied.length === descriptors.length,
+    reason: `Missing permissions: ${reason}`
+  };
+}
+function createActions(config) {
+  let counter = 0;
+  function createAction(operationsFn) {
+    const actionId = `action_${++counter}`;
+    const action = async (args) => {
+      const ctx = await config.getContext(args);
+      const input = await parseInput(args.request);
+      const operation = operationsFn(ctx.db, input, ctx);
+      return operation.run({});
+    };
+    const loader = (loaderFn) => {
+      return async (args) => {
+        const [loaderData, ctx] = await Promise.all([
+          loaderFn(args),
+          config.getContext(args)
+        ]);
+        const operation = operationsFn(ctx.db, {}, ctx);
+        const status = checkPermissionStatus(ctx.grants, operation.permissions);
+        const permissions = {
+          [actionId]: status
+        };
+        return {
+          ...loaderData,
+          _actionPermissions: permissions
+        };
+      };
+    };
+    const client = {
+      _brand: "ActionClientDescriptor",
+      actionNames: [actionId],
+      permissionsKey: "_actionPermissions"
+    };
+    const buildOperation = (db, input, ctx) => {
+      return operationsFn(db, input, ctx);
+    };
+    return { action, loader, client, buildOperation };
+  }
+  function composeActions(actions) {
+    const actionNames = Object.keys(actions);
+    const composedAction = async (args) => {
+      const actionName = await extractActionName(args.request);
+      if (!actionName || !(actionName in actions)) {
+        throw new Error(
+          `Unknown action: "${actionName}". Available actions: ${actionNames.join(", ")}`
+        );
+      }
+      return actions[actionName].action(args);
+    };
+    const composedLoader = (loaderFn) => {
+      return async (args) => {
+        const [loaderData, ctx] = await Promise.all([
+          loaderFn(args),
+          config.getContext(args)
+        ]);
+        const permissions = {};
+        for (const [name, actionDef] of Object.entries(actions)) {
+          const operation = actionDef.buildOperation(ctx.db, {}, ctx);
+          permissions[name] = checkPermissionStatus(ctx.grants, operation.permissions);
+        }
+        return {
+          ...loaderData,
+          _actionPermissions: permissions
+        };
+      };
+    };
+    const client = {
+      _brand: "ActionClientDescriptor",
+      actionNames,
+      permissionsKey: "_actionPermissions"
+    };
+    return {
+      action: composedAction,
+      loader: composedLoader,
+      client,
+      actions
+    };
+  }
+  return { createAction, composeActions };
+}
+export {
+  checkPermissionStatus,
+  createActions
+};

package/dist/types-CNqDBI0X.d.ts

@@ -0,0 +1,49 @@
+import { Db, Operation } from '@cfast/db';
+import { Grant } from '@cfast/permissions';
+
+type Serializable = string | number | boolean | null | Serializable[] | {
+    [key: string]: Serializable;
+};
+type ActionContext<TUser> = {
+    db: Db;
+    user: TUser;
+    grants: Grant[];
+};
+type RequestArgs = {
+    request: Request;
+    params: Record<string, string | undefined>;
+    context?: unknown;
+};
+type ActionsConfig<TUser> = {
+    getContext: (args: RequestArgs) => Promise<ActionContext<TUser>>;
+};
+type OperationsFn<TInput, TResult, TUser> = (db: Db, input: TInput, ctx: ActionContext<TUser>) => Operation<TResult>;
+type ActionPermissionStatus = {
+    permitted: boolean;
+    invisible: boolean;
+    reason: string | null;
+};
+type ActionPermissionsMap = Record<string, ActionPermissionStatus>;
+type ClientDescriptor = {
+    _brand: "ActionClientDescriptor";
+    actionNames: readonly string[];
+    permissionsKey: string;
+};
+type ActionDefinition<TInput, TResult, TUser> = {
+    action: (args: RequestArgs) => Promise<TResult>;
+    loader: <TLoaderData extends Record<string, Serializable>>(loaderFn: (args: RequestArgs) => Promise<TLoaderData>) => (args: RequestArgs) => Promise<TLoaderData & {
+        _actionPermissions: ActionPermissionsMap;
+    }>;
+    client: ClientDescriptor;
+    buildOperation: (db: Db, input: TInput, ctx: ActionContext<TUser>) => Operation<TResult>;
+};
+type ComposedActions<TActions extends Record<string, ActionDefinition<any, any, any>>> = {
+    action: (args: RequestArgs) => Promise<unknown>;
+    loader: <TLoaderData extends Record<string, Serializable>>(loaderFn: (args: RequestArgs) => Promise<TLoaderData>) => (args: RequestArgs) => Promise<TLoaderData & {
+        _actionPermissions: ActionPermissionsMap;
+    }>;
+    client: ClientDescriptor;
+    actions: TActions;
+};
+
+export type { ActionPermissionStatus as A, ClientDescriptor as C, OperationsFn as O, RequestArgs as R, Serializable as S, ActionsConfig as a, ActionDefinition as b, ComposedActions as c, ActionContext as d, ActionPermissionsMap as e };

package/dist/types-Dolh-eut.d.ts

@@ -0,0 +1,220 @@
+import { Db, Operation } from '@cfast/db';
+import { Grant } from '@cfast/permissions';
+
+/**
+ * A JSON-serializable value that can safely cross the server/client boundary.
+ *
+ * Used to constrain loader data so that {@link ActionDefinition.loader} and
+ * {@link ComposedActions.loader} can merge `_actionPermissions` into it.
+ */
+type Serializable = string | number | boolean | null | Serializable[] | {
+    [key: string]: Serializable;
+};
+/**
+ * Context provided to every action's {@link OperationsFn}.
+ *
+ * Created by the `getContext` callback in {@link ActionsConfig} and passed
+ * alongside the database instance and parsed input to each action.
+ *
+ * @typeParam TUser - The shape of the authenticated user object.
+ *
+ * @example
+ * ```ts
+ * const ctx: ActionContext<{ id: string; role: string }> = {
+ *   db,
+ *   user: { id: "u_1", role: "author" },
+ *   grants: [{ action: "manage", subject: "all" }],
+ * };
+ * ```
+ */
+type ActionContext<TUser> = {
+    /** The Drizzle database instance from `@cfast/db`. */
+    db: Db;
+    /** The authenticated user for the current request. */
+    user: TUser;
+    /** The user's permission {@link Grant | grants}, used for permission checking. */
+    grants: Grant[];
+};
+/**
+ * Subset of React Router loader/action arguments consumed by `@cfast/actions`.
+ *
+ * Mirrors the shape React Router passes to `loader` and `action` exports,
+ * trimmed to only the fields the actions system needs.
+ */
+type RequestArgs = {
+    /** The incoming HTTP request. */
+    request: Request;
+    /** URL parameters from the route pattern (e.g., `{ postId: "abc" }`). */
+    params: Record<string, string | undefined>;
+    /** Optional context object (e.g., Cloudflare Workers env via `context.cloudflare.env`). */
+    context?: unknown;
+};
+/**
+ * Configuration for the {@link createActions} factory.
+ *
+ * Provides a `getContext` callback that resolves the per-request
+ * {@link ActionContext} (database, user, grants) for every action invocation.
+ *
+ * @typeParam TUser - The shape of the authenticated user object.
+ *
+ * @example
+ * ```ts
+ * const config: ActionsConfig<AppUser> = {
+ *   getContext: async ({ request }) => {
+ *     const ctx = await requireAuthContext(request);
+ *     const db = createCfDb(env.DB, ctx);
+ *     return { db, user: ctx.user, grants: ctx.grants };
+ *   },
+ * };
+ * ```
+ */
+type ActionsConfig<TUser> = {
+    /** Resolves the per-request action context from the route handler arguments. */
+    getContext: (args: RequestArgs) => Promise<ActionContext<TUser>>;
+};
+/**
+ * A function that builds a database {@link Operation} for an action.
+ *
+ * Receives the Drizzle database, the parsed input, and the full
+ * {@link ActionContext}. Returns an `Operation` (from `@cfast/db`) that
+ * encapsulates both the query/mutation and its permission descriptors.
+ *
+ * @typeParam TInput - The expected input shape for this action.
+ * @typeParam TResult - The return type of the operation.
+ * @typeParam TUser - The shape of the authenticated user object.
+ *
+ * @example
+ * ```ts
+ * const deletePostOps: OperationsFn<{ postId: string }, Response, AppUser> =
+ *   (db, input, ctx) =>
+ *     compose(
+ *       [db.delete(posts).where(eq(posts.id, input.postId))],
+ *       async (runDelete) => {
+ *         await runDelete({});
+ *         return redirect("/");
+ *       },
+ *     );
+ * ```
+ */
+type OperationsFn<TInput, TResult, TUser> = (db: Db, input: TInput, ctx: ActionContext<TUser>) => Operation<TResult>;
+/**
+ * The resolved permission status for a single action.
+ *
+ * Computed by {@link checkPermissionStatus} and sent to the client
+ * via `_actionPermissions` in loader data.
+ */
+type ActionPermissionStatus = {
+    /** Whether the user has all required permissions for this action. */
+    permitted: boolean;
+    /** `true` when the user lacks every permission — the UI should hide the control entirely. */
+    invisible: boolean;
+    /** Human-readable explanation when `permitted` is `false`, otherwise `null`. */
+    reason: string | null;
+};
+/**
+ * A map from action name to its {@link ActionPermissionStatus}.
+ *
+ * Injected into loader data under the `_actionPermissions` key by
+ * {@link ActionDefinition.loader} or {@link ComposedActions.loader}.
+ */
+type ActionPermissionsMap = Record<string, ActionPermissionStatus>;
+/**
+ * An opaque descriptor passed to the client to configure the `useActions` hook.
+ *
+ * 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 = {
+    /** Brand field to distinguish this type at the type level. */
+    _brand: "ActionClientDescriptor";
+    /** The list of action names this descriptor covers. */
+    actionNames: readonly string[];
+    /** The loader-data key where {@link ActionPermissionsMap} is stored. */
+    permissionsKey: string;
+};
+/**
+ * A single action definition returned by `createAction()`.
+ *
+ * Provides four facets: a React Router action handler, a loader wrapper
+ * that injects permission status, a client descriptor for `useActions`,
+ * and a `buildOperation` method for advanced composition.
+ *
+ * @typeParam TInput - The expected input shape for this action.
+ * @typeParam TResult - The return type of the action handler.
+ * @typeParam TUser - The shape of the authenticated user object.
+ *
+ * @example
+ * ```ts
+ * const deletePost = createAction<{ postId: string }, Response>(
+ *   (db, input, ctx) =>
+ *     compose(
+ *       [db.delete(posts).where(eq(posts.id, input.postId))],
+ *       async (runDelete) => { await runDelete({}); return redirect("/"); },
+ *     ),
+ * );
+ *
+ * // Use as a route action
+ * export const action = deletePost.action;
+ * // Wrap a loader to inject permissions
+ * export const loader = deletePost.loader(myLoader);
+ * ```
+ */
+type ActionDefinition<TInput, TResult, TUser> = {
+    /** React Router action handler. Parses input, resolves context, and runs the operation. */
+    action: (args: RequestArgs) => Promise<TResult>;
+    /**
+     * Wraps a loader function to inject {@link ActionPermissionsMap} into its return value.
+     *
+     * The wrapper resolves the action context, builds the operation to extract
+     * permission descriptors, checks them against the user's grants, and merges
+     * the result as `_actionPermissions`.
+     */
+    loader: <TLoaderData extends Record<string, Serializable>>(loaderFn: (args: RequestArgs) => Promise<TLoaderData>) => (args: RequestArgs) => Promise<TLoaderData & {
+        _actionPermissions: ActionPermissionsMap;
+    }>;
+    /** Opaque descriptor for the `useActions` client hook. */
+    client: ClientDescriptor;
+    /** Builds the raw {@link Operation} for this action, useful for cross-action composition. */
+    buildOperation: (db: Db, input: TInput, ctx: ActionContext<TUser>) => Operation<TResult>;
+};
+/**
+ * The result of combining multiple {@link ActionDefinition | action definitions}
+ * via `composeActions()`.
+ *
+ * Provides a single action handler that dispatches by the `_action` discriminator,
+ * a loader wrapper that checks permissions for all actions at once, a client
+ * descriptor covering all action names, and the original action map.
+ *
+ * @typeParam TActions - A record mapping action names to their {@link ActionDefinition} types.
+ *
+ * @example
+ * ```ts
+ * const composed = composeActions({
+ *   deletePost,
+ *   publishPost,
+ *   unpublishPost,
+ * });
+ *
+ * export const action = composed.action;
+ * export const loader = composed.loader(myLoader);
+ * ```
+ */
+type ComposedActions<TActions extends Record<string, ActionDefinition<any, any, any>>> = {
+    /** Combined action handler that dispatches to the correct action based on `_action` field. */
+    action: (args: RequestArgs) => Promise<unknown>;
+    /**
+     * Wraps a loader function to inject {@link ActionPermissionsMap} for all composed actions.
+     *
+     * Checks permissions for every action in the map and merges the results
+     * into loader data under `_actionPermissions`.
+     */
+    loader: <TLoaderData extends Record<string, Serializable>>(loaderFn: (args: RequestArgs) => Promise<TLoaderData>) => (args: RequestArgs) => Promise<TLoaderData & {
+        _actionPermissions: ActionPermissionsMap;
+    }>;
+    /** Opaque descriptor covering all composed action names, for the `useActions` client hook. */
+    client: ClientDescriptor;
+    /** The original action definitions, keyed by name. */
+    actions: TActions;
+};
+
+export type { ActionPermissionStatus as A, ClientDescriptor as C, OperationsFn as O, RequestArgs as R, Serializable as S, ActionsConfig as a, ActionDefinition as b, ComposedActions as c, ActionContext as d, ActionPermissionsMap as e };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@cfast/actions",
+  "version": "0.0.1",
+  "description": "Multi-action routes and permission-aware action definitions for React Router",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DanielMSchmidt/cfast.git",
+    "directory": "packages/actions"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-router": "^7.0.0"
+  },
+  "dependencies": {
+    "@cfast/db": "0.0.1",
+    "@cfast/permissions": "0.0.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260305.1",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "react-router": "^7.6.0",
+    "tsup": "^8",
+    "typescript": "^5.7",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/client.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run"
+  }
+}