@mmapp/react 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/actionCreators.ts

@@ -1,132 +0,0 @@
-/**
- * @mindmatrix/react/actionCreators — Type-safe action reference factories.
- *
- * Replaces stringly-typed `serverAction("authenticate", {...})` calls with
- * typed action creators that catch typos at compile time.
- *
- * @example
- * ```typescript
- * import { createActions } from '@mindmatrix/react';
- *
- * const actions = createActions({
- *   authenticate: { handler: 'actions/auth.server.ts' },
- *   destroySession: { handler: 'actions/auth.server.ts' },
- *   resetPassword: { handler: 'actions/auth.server.ts' },
- * });
- *
- * // Usage in models — fully typed, autocomplete on action names:
- * .do(actions.authenticate({ method: 'login' }))
- * .do(actions.destroySession())
- *
- * // Typo = TypeScript compile error:
- * .do(actions.autenticate({}))
- * //         ~~~~~~~~~~~~ Property 'autenticate' does not exist
- * ```
- *
- * @module
- */
-
-import type { ActionDefinition } from './config/defineModel';
-
-// =============================================================================
-// Action Manifest & Creators
-// =============================================================================
-
-/**
- * Configuration for a single action in the manifest.
- */
-export interface ActionManifestEntry {
-  /** The handler file path (e.g., 'actions/auth.server.ts'). */
-  handler: string;
-  /** Optional function name within the handler file. */
-  functionName?: string;
-  /** Optional description for documentation. */
-  description?: string;
-  /** Action execution mode. Default: 'auto'. */
-  mode?: 'auto' | 'manual';
-}
-
-/**
- * A manifest mapping action names to their configuration.
- */
-export type ActionManifest = Record<string, ActionManifestEntry>;
-
-/**
- * A typed action creator function returned for each manifest entry.
- * Accepts optional config and returns an ActionDefinition.
- */
-export type ActionCreator = (config?: Record<string, unknown>) => ActionDefinition;
-
-/**
- * Maps an ActionManifest to an object of typed action creators.
- * Each key from the manifest becomes a callable action creator.
- */
-export type ActionCreators<M extends ActionManifest> = {
-  readonly [K in keyof M]: ActionCreator;
-};
-
-/**
- * Convert a camelCase or PascalCase string to kebab-case.
- * @internal
- */
-function toKebab(str: string): string {
-  return str
-    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-    .replace(/[_.:\s]+/g, '-')
-    .toLowerCase();
-}
-
-/**
- * Create typed action creators from an actions manifest.
- *
- * Each key in the manifest becomes a function that returns an {@link ActionDefinition}
- * compatible with `.do()`, `onEnter`, `onExit`, and other action slots.
- *
- * The action type is `server:{kebab-case-name}` and the handler path is stored
- * in the config for the build pipeline to resolve.
- *
- * @param manifest - Object mapping action names to their configuration.
- * @returns An object with the same keys, where each value is a typed action creator.
- *
- * @example
- * ```typescript
- * const actions = createActions({
- *   authenticate: { handler: 'actions/auth.server.ts' },
- *   destroySession: { handler: 'actions/auth.server.ts' },
- *   sendWelcomeEmail: { handler: 'actions/email.server.ts', mode: 'manual' },
- * });
- *
- * // Returns ActionDefinition:
- * actions.authenticate({ method: 'login' })
- * // => { id: 'server-authenticate', type: 'server:authenticate',
- * //      mode: 'auto', config: { method: 'login', __handler: 'actions/auth.server.ts' } }
- *
- * actions.destroySession()
- * // => { id: 'server-destroy-session', type: 'server:destroySession',
- * //      mode: 'auto', config: { __handler: 'actions/auth.server.ts' } }
- * ```
- */
-export function createActions<const M extends ActionManifest>(manifest: M): ActionCreators<M> {
-  const creators = {} as Record<string, ActionCreator>;
-
-  for (const [name, entry] of Object.entries(manifest)) {
-    creators[name] = (config?: Record<string, unknown>): ActionDefinition => {
-      const actionConfig: Record<string, unknown> = {
-        ...config,
-        __handler: entry.handler,
-      };
-      if (entry.functionName) {
-        actionConfig.__functionName = entry.functionName;
-      }
-      return {
-        id: `server-${toKebab(name)}`,
-        type: `server:${name}`,
-        mode: entry.mode ?? 'auto',
-        config: actionConfig,
-      };
-    };
-  }
-
-  return creators as ActionCreators<M>;
-}
-

package/src/actions.ts

@@ -1,547 +0,0 @@
-/**
- * @mindmatrix/react/actions — Typed action factory functions.
- *
- * Provides ergonomic helpers that produce {@link ActionDefinition} objects
- * for use in model definitions (states and transitions). Every function
- * returns a valid `ActionDefinition` that works with `defineModel()`.
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { setField, logEvent, notify, spawn } from '@mindmatrix/react/actions';
- *
- * export default defineModel({
- *   slug: 'order',
- *   fields: { status: { type: 'string', default: 'draft' } },
- *   states: {
- *     draft: { type: 'initial' },
- *     submitted: {
- *       onEnter: [
- *         setField('status', '"submitted"'),
- *         logEvent('order.submitted', { orderId: '{{ state_data.id }}' }),
- *       ],
- *     },
- *     fulfilled: { type: 'end' },
- *   },
- *   transitions: {
- *     submit: { from: 'draft', to: 'submitted' },
- *     fulfill: { from: 'submitted', to: 'fulfilled' },
- *   },
- * });
- * ```
- *
- * @module
- */
-
-import type { ActionDefinition } from './config/defineModel';
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-/**
- * Convert a string to kebab-case for auto-generated action IDs.
- *
- * @internal
- */
-function toKebab(str: string): string {
-  return str
-    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-    .replace(/[_.:\s]+/g, '-')
-    .toLowerCase();
-}
-
-/**
- * Generate a deterministic action ID from a type and an optional qualifier.
- *
- * @internal
- */
-function makeId(type: string, qualifier?: string): string {
-  const base = toKebab(type);
-  if (qualifier) {
-    return `${base}-${toKebab(qualifier)}`;
-  }
-  return base;
-}
-
-// =============================================================================
-// Core Field Mutations
-// =============================================================================
-
-/**
- * Set a single field via an expression.
- *
- * Produces a `set_field` action with auto-generated ID based on the field name.
- *
- * @param field - The field name to set.
- * @param expression - An expression string evaluated at runtime.
- * @returns An `ActionDefinition` of type `set_field`.
- *
- * @example
- * ```typescript
- * // Clear an error message
- * setField('errorMessage', '""')
- * // => { id: 'set-field-error-message', type: 'set_field', mode: 'auto',
- * //      config: { field: 'errorMessage', expression: '""' } }
- *
- * // Set timestamp to current time
- * setField('lastMessageAt', 'NOW()')
- *
- * // Set from input
- * setField('name', 'input.name')
- * ```
- */
-export function setField(field: string, expression: string): ActionDefinition {
-  return {
-    id: makeId('set-field', field),
-    type: 'set_field',
-    mode: 'auto',
-    config: { field, expression },
-  };
-}
-
-/**
- * Set multiple fields at once via expressions.
- *
- * Produces a `set_fields` action. Each value in the record is an expression
- * string that will be evaluated at runtime.
- *
- * @param fields - A record mapping field names to expression strings.
- * @returns An `ActionDefinition` of type `set_fields`.
- *
- * @example
- * ```typescript
- * // Populate message fields on send
- * setFields({
- *   senderId: 'context.actor_id',
- *   senderName: 'context.actor_name',
- *   timestamp: 'NOW()',
- *   content: 'input.content',
- * })
- * // => { id: 'set-fields', type: 'set_fields', mode: 'auto',
- * //      config: { fields: { senderId: { expression: 'context.actor_id' }, ... } } }
- *
- * // Clear multiple fields on retry
- * setFields({
- *   errorMessage: '""',
- *   artifact: 'null',
- *   summary: '""',
- * })
- * ```
- */
-export function setFields(fields: Record<string, string>): ActionDefinition {
-  const mapped: Record<string, { expression: string }> = {};
-  for (const [key, expr] of Object.entries(fields)) {
-    mapped[key] = { expression: expr };
-  }
-  return {
-    id: 'set-fields',
-    type: 'set_fields',
-    mode: 'auto',
-    config: { fields: mapped },
-  };
-}
-
-// =============================================================================
-// Logging
-// =============================================================================
-
-/**
- * Emit an event to the workflow audit log.
- *
- * Produces a `log_event` action. The event name is typically dot-delimited
- * (e.g., `'auth.success'`, `'message.sent'`).
- *
- * @param event - The event name to log.
- * @param data - Optional key-value data to include in the log entry.
- *   Values are template strings evaluated at runtime (e.g., `'{{ state_data.id }}'`).
- * @returns An `ActionDefinition` of type `log_event`.
- *
- * @example
- * ```typescript
- * // Simple event
- * logEvent('auth.logout')
- * // => { id: 'log-event-auth-logout', type: 'log_event', mode: 'auto',
- * //      config: { event: 'auth.logout' } }
- *
- * // Event with data
- * logEvent('message.sent', {
- *   channelId: '{{ state_data.channelId }}',
- *   senderId: '{{ state_data.senderId }}',
- * })
- * ```
- */
-export function logEvent(event: string, data?: Record<string, string>): ActionDefinition {
-  const config: Record<string, unknown> = { event };
-  if (data) {
-    config.data = data;
-  }
-  return {
-    id: makeId('log-event', event),
-    type: 'log_event',
-    mode: 'auto',
-    config,
-  };
-}
-
-// =============================================================================
-// Notifications
-// =============================================================================
-
-/**
- * Options for the {@link notify} action factory.
- */
-export interface ActionNotifyOptions {
-  /**
-   * Template expression for notification recipients.
-   * Use `recipients` for multi-recipient expressions (e.g., `'{{ state_data.members }}'`).
-   */
-  recipients?: string;
-  /**
-   * Shorthand for a single recipient expression.
-   * Alias for `recipients` when sending to one target.
-   */
-  to?: string;
-  /**
-   * Key-value data interpolated into the notification template.
-   * Values are template strings evaluated at runtime.
-   */
-  data?: Record<string, string>;
-}
-
-/**
- * Send a notification to one or more recipients.
- *
- * Produces a `send_notification` action. Uses either `recipients` or `to`
- * (whichever is provided) as the recipient expression.
- *
- * @param template - The notification template name.
- * @param options - Recipient and data options.
- * @returns An `ActionDefinition` of type `send_notification`.
- *
- * @example
- * ```typescript
- * // Notify channel members about archival
- * notify('channel_archived', {
- *   recipients: '{{ state_data.members }}',
- *   data: { channel: '{{ state_data.name }}' },
- * })
- *
- * // Notify a single user about a mention
- * notify('message_mention', {
- *   to: '{{ state_data.senderId }}',
- *   data: { content: '{{ SUBSTR(state_data.content, 0, 100) }}' },
- * })
- * ```
- */
-export function notify(template: string, options: ActionNotifyOptions = {}): ActionDefinition {
-  const config: Record<string, unknown> = { template };
-  const recipient = options.recipients ?? options.to;
-  if (recipient) {
-    config.recipients = recipient;
-  }
-  if (options.data) {
-    config.data = options.data;
-  }
-  return {
-    id: makeId('notify', template),
-    type: 'send_notification',
-    mode: 'auto',
-    config,
-  };
-}
-
-// =============================================================================
-// Sub-workflow Spawning
-// =============================================================================
-
-/**
- * Options for the {@link spawn} action factory.
- */
-export interface SpawnActionOptions {
-  /**
-   * Whether the parent workflow waits for the child to complete.
-   * Default: `false`.
-   */
-  blocking?: boolean;
-}
-
-/**
- * Spawn a child workflow instance.
- *
- * Produces a `spawn_subworkflow` action. The child workflow is created
- * from the given definition slug, with optional input field mapping.
- *
- * @param definitionSlug - The slug of the workflow definition to spawn.
- * @param inputMapping - Optional mapping of child input fields to parent expressions.
- *   Keys are child field names, values are expression strings evaluated in the parent context.
- * @param options - Optional spawn configuration.
- * @returns An `ActionDefinition` of type `spawn_subworkflow`.
- *
- * @example
- * ```typescript
- * // Spawn a non-blocking reaction workflow
- * spawn('chat-reaction', {
- *   messageId: 'state_data.id',
- *   channelId: 'state_data.channelId',
- *   userId: 'context.actor_id',
- *   emoji: 'input.emoji',
- * })
- *
- * // Spawn a blocking payment processor
- * spawn('payment-process', {
- *   amount: 'state_data.totalAmount',
- *   currency: 'state_data.currency',
- * }, { blocking: true })
- * ```
- */
-export function spawn(
-  definitionSlug: string,
-  inputMapping?: Record<string, string>,
-  options?: SpawnActionOptions,
-): ActionDefinition {
-  const config: Record<string, unknown> = {
-    definition_slug: definitionSlug,
-    blocking: options?.blocking ?? false,
-  };
-  if (inputMapping) {
-    config.input_mapping = inputMapping;
-  }
-  return {
-    id: makeId('spawn', definitionSlug),
-    type: 'spawn_subworkflow',
-    mode: 'auto',
-    config,
-  };
-}
-
-// =============================================================================
-// Server / Device Actions
-// =============================================================================
-
-/**
- * Execute an opaque server-side action.
- *
- * Produces a `server:{type}` action. Server actions are implemented in
- * `actions.server.ts` files and run on the backend.
- *
- * @param type - The server action type (appended to `server:` prefix).
- * @param config - Optional action configuration passed to the server handler.
- * @returns An `ActionDefinition` of type `server:{type}`.
- *
- * @example
- * ```typescript
- * // Authenticate via server
- * serverAction('authenticate', {
- *   method: 'login',
- *   email: '{{ input.email }}',
- *   password: '{{ input.password }}',
- * })
- * // => { id: 'server-authenticate', type: 'server:authenticate', mode: 'auto',
- * //      config: { method: 'login', ... } }
- *
- * // Destroy a session
- * serverAction('destroy_session')
- * // => { id: 'server-destroy-session', type: 'server:destroy_session', mode: 'auto', config: {} }
- * ```
- */
-export function serverAction(type: string, config?: Record<string, unknown>): ActionDefinition {
-  return {
-    id: makeId('server', type),
-    type: `server:${type}`,
-    mode: 'auto',
-    config: config ?? {},
-  };
-}
-
-/**
- * Execute an opaque device-side action.
- *
- * Produces a `device:{type}` action. Device actions run on the client
- * (browser, mobile, etc.) and are implemented in `actions.device.ts` files.
- *
- * @param type - The device action type (appended to `device:` prefix).
- * @param config - Optional action configuration passed to the device handler.
- * @returns An `ActionDefinition` of type `device:{type}`.
- *
- * @example
- * ```typescript
- * // Trigger haptic feedback on mobile
- * deviceAction('haptic', { pattern: 'success' })
- * // => { id: 'device-haptic', type: 'device:haptic', mode: 'auto',
- * //      config: { pattern: 'success' } }
- *
- * // Open native share dialog
- * deviceAction('share', {
- *   title: '{{ state_data.name }}',
- *   url: '{{ state_data.shareUrl }}',
- * })
- * ```
- */
-export function deviceAction(type: string, config?: Record<string, unknown>): ActionDefinition {
-  return {
-    id: makeId('device', type),
-    type: `device:${type}`,
-    mode: 'auto',
-    config: config ?? {},
-  };
-}
-
-// =============================================================================
-// Connector Actions
-// =============================================================================
-
-/**
- * Execute an external service connector action.
- *
- * Produces a `connector.{provider}.{operation}` action. Connector actions
- * integrate with third-party services like Xero, Stripe, Slack, etc.
- *
- * @param provider - The connector provider name (e.g., `'xero'`, `'stripe'`).
- * @param operation - The operation to perform (e.g., `'query'`, `'create'`).
- * @param config - Optional configuration passed to the connector handler.
- * @returns An `ActionDefinition` of type `connector.{provider}.{operation}`.
- *
- * @example
- * ```typescript
- * // Query Xero invoices
- * connector('xero', 'query', {
- *   tenant_id: '{{ state_data.tenantId }}',
- *   entity: 'invoices',
- * })
- * // => { id: 'connector-xero-query', type: 'connector.xero.query', mode: 'auto',
- * //      config: { tenant_id: '...', entity: 'invoices' } }
- *
- * // Create a Stripe charge
- * connector('stripe', 'create_charge', {
- *   amount: '{{ state_data.amount }}',
- *   currency: '{{ state_data.currency }}',
- *   customer: '{{ state_data.stripeCustomerId }}',
- * })
- * ```
- */
-export function connector(
-  provider: string,
-  operation: string,
-  config?: Record<string, unknown>,
-): ActionDefinition {
-  return {
-    id: makeId('connector', `${provider}-${operation}`),
-    type: `connector.${provider}.${operation}`,
-    mode: 'auto',
-    config: config ?? {},
-  };
-}
-
-// =============================================================================
-// LLM Actions
-// =============================================================================
-
-/**
- * Execute an LLM / AI action.
- *
- * Produces an `llm.{operation}` action. LLM actions are registered globally
- * as custom action handlers and support operations like chat completions,
- * embeddings, classification, etc.
- *
- * @param operation - The LLM operation (e.g., `'chat'`, `'embed'`, `'classify'`).
- * @param config - Optional configuration for the LLM call.
- * @returns An `ActionDefinition` of type `llm.{operation}`.
- *
- * @example
- * ```typescript
- * // Call LLM for chat completion
- * llm('chat', {
- *   system_prompt: 'DATA_AGENT_SYSTEM_PROMPT',
- *   user_message: '{{ state_data.dataContext }}\n\nUser intent: {{ state_data.intentText }}',
- *   max_tokens: 8192,
- *   temperature: 0.3,
- * })
- * // => { id: 'llm-chat', type: 'llm.chat', mode: 'auto',
- * //      config: { system_prompt: '...', ... } }
- *
- * // Generate embeddings
- * llm('embed', {
- *   input: '{{ state_data.content }}',
- *   model: 'text-embedding-3-small',
- * })
- * ```
- */
-export function llm(operation: string, config?: Record<string, unknown>): ActionDefinition {
-  return {
-    id: makeId('llm', operation),
-    type: `llm.${operation}`,
-    mode: 'auto',
-    config: config ?? {},
-  };
-}
-
-// =============================================================================
-// Generic Custom Action
-// =============================================================================
-
-/**
- * Options for the generic {@link action} factory.
- */
-export interface ActionOptions {
-  /**
-   * Whether this action runs automatically or requires manual trigger.
-   * Default: `'auto'`.
-   */
-  mode?: 'auto' | 'manual';
-  /**
-   * Expression that must be truthy for this action to execute.
-   */
-  condition?: string;
-}
-
-/**
- * Create a generic custom action with explicit ID and type.
- *
- * Use this when none of the specialized factories (`setField`, `logEvent`,
- * `notify`, `spawn`, etc.) fit your use case. Provides full control over
- * the action ID, type, config, and options.
- *
- * @param id - Unique identifier for the action within its state/transition.
- * @param type - The action type string.
- * @param config - Optional action configuration.
- * @param options - Optional mode and condition.
- * @returns An `ActionDefinition` with the specified parameters.
- *
- * @example
- * ```typescript
- * // Custom webhook action
- * action('post-webhook', 'server:webhook', {
- *   url: 'https://hooks.example.com/orders',
- *   method: 'POST',
- *   body: '{{ state_data }}',
- * })
- *
- * // Conditional manual action
- * action('approve-order', 'server:approve', {
- *   orderId: '{{ state_data.id }}',
- * }, {
- *   mode: 'manual',
- *   condition: 'state_data.amount > 1000',
- * })
- * ```
- */
-export function action(
-  id: string,
-  type: string,
-  config?: Record<string, unknown>,
-  options?: ActionOptions,
-): ActionDefinition {
-  const def: ActionDefinition = {
-    id,
-    type,
-    mode: options?.mode ?? 'auto',
-  };
-  if (config) {
-    def.config = config;
-  }
-  if (options?.condition) {
-    def.condition = options.condition;
-  }
-  return def;
-}