Skip to content
XMachines

Function: defineCatalog()

Documentation / @xmachines/play-catalog / defineCatalog

function defineCatalog<TCatalog>(schemas): TCatalog;

Defined in: define-catalog.ts:74

Define component catalog with Zod schemas for type-safe UI projection

Creates a catalog mapping component names to their prop schemas using Zod validators. The catalog enables Strict Separation (INV-02) by defining UI vocabulary in framework-agnostic terms that the Actor can reference without coupling to React/Vue/etc.

Architectural Context: Implements Strict Separation (INV-02) where business logic (state machine) has zero framework imports. The catalog serves as the contract between Actor (which references component names in meta.view) and Infrastructure (which renders actual framework components).

Type Parameters

Type Parameter
TCatalog extends Record<string, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>

Parameters

ParameterTypeDescription
schemasTCatalogRecord mapping component names to Zod schemas

Returns

TCatalog

Typed catalog object with schema entries (frozen in development for immutability)

Examples

Basic catalog definition

import { z } from "zod";
import { defineCatalog } from "@xmachines/play-catalog";


const catalog = defineCatalog({
  Dashboard: z.object({ userId: z.string() }),
  LoginForm: z.object({ error: z.string().optional() }),
});


// TypeScript infers catalog type automatically
type CatalogType = typeof catalog;

Progressive catalog with multiple components

import { z } from "zod";
import { defineCatalog } from "@xmachines/play-catalog";


const catalog = defineCatalog({
  // Public pages
  HomePage: z.object({}),
  AboutPage: z.object({}),


  // Auth components
  LoginForm: z.object({
    error: z.string().optional(),
    returnUrl: z.string().optional(),
  }),


  // Protected pages
  Dashboard: z.object({
    userId: z.string(),
    stats: z.object({
      views: z.number(),
      clicks: z.number(),
    }),
  }),
});

See

Remarks

Primary Purpose: Type inference. The returned catalog object is primarily used for TypeScript type inference. Runtime validation happens at state entry when the Actor attempts to project a view through the renderer.

Immutability: In development mode, the catalog is frozen via Object.freeze() to prevent accidental mutation. In production, freezing is skipped for performance.