Quickstart

Install @fabricorg/platform, declare a module, register it, and invoke your first action.

This walkthrough shows the smallest end-to-end example: declare an action, register it via a module, and invoke it.

1. Install

pnpm add @fabricorg/platform
# or
npm install @fabricorg/platform

The platform has zero runtime dependencies. You bring your own database client and bind it via the TDb type parameter.

2. Declare an action

// src/actions/greet.ts
import type { ActionDefinition } from "@fabricorg/platform/actions";
import { z } from "zod";

const greetSchema = z.object({
  partyId: z.string(),
  message: z.string().min(1),
});

export const greetAction: ActionDefinition = {
  actionId: "demo.greet",
  namespace: "demo",
  version: 1,
  schema: greetSchema,
  handler: async (ctx, params) => {
    const parsed = greetSchema.parse(params);
    // ...your domain write goes here, on ctx.db...
    return {
      success: true,
      data: { greeted: parsed.partyId },
    };
  },
  emitsEvents: ["GreetingSent"],
  idempotent: false,
  mutatesDomain: true,
};

3. Declare a module

// src/module.ts
import type { FabricModule } from "@fabricorg/platform/modules";

import { greetAction } from "./actions/greet";

export const demoModule: FabricModule = {
  namespace: "demo",
  objectTypes: ["Greeting"],
  eventTypes: [
    { eventType: "GreetingSent", version: 1 },
  ],
  actions: [greetAction],
};

4. Register modules at boot

// src/main.ts
import { registerFabricModules } from "@fabricorg/platform/modules";

import { demoModule } from "./module";

registerFabricModules([demoModule]);

After this call, the platform's registries contain the demo namespace, the Greeting object type, the GreetingSent event type, and the demo.greet action. Any subsequent attempt to invoke the action will pass through the full pipeline:

invokeAction
  → ActionInvocation row created (status: pending)
  → evaluatePolicies   (none on this action — passes silently)
  → state-machine validation (none — skipped)
  → handler runs in transaction
  → AssetEvent appended
  → adapter steps (none — skipped)
  → ActionInvocation status: completed

5. Wire your own runtime

@fabricorg/platform defines the contracts and the pipeline shape. It does not ship a worker. You wire it into your runtime — for example:

A simple in-process executor (synchronous calls, no durability — fine for tests).
A Temporal-based worker for production durability.
A queue + worker pool of your choice.

The platform's executeWithAdapterRetry (@fabricorg/platform/adapters) and replay primitives (@fabricorg/platform/projections) work with whatever runtime you pick.

1. Install

2. Declare an action

3. Declare a module

4. Register modules at boot

5. Wire your own runtime

What to read next

On this page