@jaypie/fabric 0.1.0

package/dist/cjs/types/elementaryTypes.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Elementary Field Types
+ *
+ * Defines the 10 elementary field types for the Fabric vocabulary.
+ * Each type has: alias, name, icon, and optional validation/format rules.
+ */
+import type { FieldDefinition } from "./fieldDefinition.js";
+/** Elementary type aliases */
+export declare const ELEMENTARY_TYPES: readonly ["boolean", "date", "datetime", "dollars", "multiselect", "number", "reference", "select", "text", "textarea"];
+export type ElementaryType = (typeof ELEMENTARY_TYPES)[number];
+/**
+ * Extended field definition for elementary types
+ */
+export interface ElementaryTypeDefinition extends FieldDefinition {
+    /** The elementary type alias */
+    alias: ElementaryType;
+    /** Display format pattern */
+    formatPattern?: string;
+    /** Input component type (for UI rendering) */
+    inputComponent?: string;
+    /** Options for select/multiselect types */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Reference model for reference types */
+    referenceModel?: string;
+}
+/**
+ * Check if a string is an elementary type
+ */
+export declare function isElementaryType(value: unknown): value is ElementaryType;
+/**
+ * Boolean - True/false toggle
+ */
+export declare const BOOLEAN_TYPE: ElementaryTypeDefinition;
+/**
+ * Date - Date picker (ISO format)
+ */
+export declare const DATE_TYPE: ElementaryTypeDefinition;
+/**
+ * Datetime - Date + time picker
+ */
+export declare const DATETIME_TYPE: ElementaryTypeDefinition;
+/**
+ * Dollars - Currency with formatting
+ */
+export declare const DOLLARS_TYPE: ElementaryTypeDefinition;
+/**
+ * Multiselect - Multiple selections from options
+ */
+export declare const MULTISELECT_TYPE: ElementaryTypeDefinition;
+/**
+ * Number - Numeric input (integer or float)
+ */
+export declare const NUMBER_TYPE: ElementaryTypeDefinition;
+/**
+ * Reference - Link to another model
+ */
+export declare const REFERENCE_TYPE: ElementaryTypeDefinition;
+/**
+ * Select - Single selection from options
+ */
+export declare const SELECT_TYPE: ElementaryTypeDefinition;
+/**
+ * Text - Single-line string input
+ */
+export declare const TEXT_TYPE: ElementaryTypeDefinition;
+/**
+ * Textarea - Multi-line string input
+ */
+export declare const TEXTAREA_TYPE: ElementaryTypeDefinition;
+/**
+ * Registry of all elementary types
+ */
+export declare const ELEMENTARY_TYPE_REGISTRY: Record<ElementaryType, ElementaryTypeDefinition>;
+/**
+ * Get an elementary type definition by alias
+ */
+export declare function getElementaryType(alias: ElementaryType): ElementaryTypeDefinition;
+/**
+ * Get all elementary type definitions
+ */
+export declare function getAllElementaryTypes(): ElementaryTypeDefinition[];

package/dist/cjs/types/fieldCategory.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Field Categories - Semantic classification of fields
+ *
+ * Categories define the semantic boundary of fields within models.
+ */
+/** Field categories defining semantic boundaries */
+export declare const FIELD_CATEGORIES: readonly ["identity", "input", "metadata", "state"];
+/**
+ * Field category - semantic classification of fields
+ *
+ * - identity: What the model IS (immutable) - id, model, ou
+ * - metadata: What the model is ABOUT (usually immutable) - alias, xid, class, type
+ * - state: What the model TRACKS (mutable) - content, status, progress
+ * - input: Request parameters (transient) - data, params, options
+ */
+export type FieldCategory = (typeof FIELD_CATEGORIES)[number];
+/**
+ * Check if a string is a valid field category
+ */
+export declare function isFieldCategory(value: unknown): value is FieldCategory;

package/dist/cjs/types/fieldDefinition.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Field Definition - Describes a field's structure and behavior
+ *
+ * Field definitions are the building blocks of model definitions,
+ * specifying type, validation, and metadata for each field.
+ */
+/**
+ * Validation rule for a field
+ */
+export interface ValidationRule {
+    /** Error message if validation fails */
+    message?: string;
+    /** Rule type (required, min, max, pattern, etc.) */
+    type: string;
+    /** Rule value (varies by type) */
+    value?: unknown;
+}
+/**
+ * Field definition - describes a field's structure and behavior
+ */
+export interface FieldDefinition {
+    /** Field identifier (unique within model) */
+    alias: string;
+    /** Default value */
+    defaultValue?: unknown;
+    /** Description */
+    description?: string;
+    /** Fallback chain for value resolution */
+    fallback?: string[];
+    /** Icon (lucide name or custom) */
+    icon?: string;
+    /** Display name */
+    name: string;
+    /** Field type (text, number, dollars, etc.) */
+    type: string;
+    /** Validation rules */
+    validation?: ValidationRule[];
+}
+/**
+ * Field reference - either an alias string or inline definition
+ */
+export type FieldRef = FieldDefinition | string;
+/**
+ * Check if a field ref is an inline definition
+ */
+export declare function isFieldDefinition(ref: FieldRef): ref is FieldDefinition;

package/dist/cjs/types/index.d.ts

@@ -0,0 +1,4 @@
+export { BOOLEAN_TYPE, DATE_TYPE, DATETIME_TYPE, DOLLARS_TYPE, ELEMENTARY_TYPE_REGISTRY, ELEMENTARY_TYPES, getAllElementaryTypes, getElementaryType, isElementaryType, MULTISELECT_TYPE, NUMBER_TYPE, REFERENCE_TYPE, SELECT_TYPE, TEXT_TYPE, TEXTAREA_TYPE, } from "./elementaryTypes.js";
+export type { ElementaryType, ElementaryTypeDefinition, } from "./elementaryTypes.js";
+export { isFieldDefinition } from "./fieldDefinition.js";
+export type { FieldDefinition, FieldRef, ValidationRule, } from "./fieldDefinition.js";

package/dist/cjs/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Log levels for messages
+ * @default "info"
+ */
+export type MessageLevel = "debug" | "error" | "info" | "trace" | "warn";
+/**
+ * Standard message structure for callbacks and notifications
+ */
+export interface Message {
+    content: string;
+    level?: MessageLevel;
+}
+export type ScalarType = typeof Boolean | typeof Number | typeof String | "boolean" | "number" | "string";
+export type CompositeType = typeof Array | typeof Object | "array" | "object";
+export type ArrayElementType = typeof Boolean | typeof Number | typeof Object | typeof String | "boolean" | "number" | "object" | "string" | "" | Record<string, never>;
+export type TypedArrayType = [] | [typeof Boolean] | [typeof Number] | [typeof Object] | [typeof String] | ["boolean"] | ["number"] | ["object"] | ["string"] | [""] | [Record<string, never>];
+export type ValidatedStringType = Array<string | RegExp>;
+export type ValidatedNumberType = Array<number>;
+export type RegExpType = RegExp;
+export type DateConversionType = typeof Date;
+export type ConversionType = CompositeType | DateConversionType | RegExpType | ScalarType | TypedArrayType | ValidatedNumberType | ValidatedStringType;
+export interface InputFieldDefinition {
+    default?: unknown;
+    description?: string;
+    /** Override the long flag name for Commander.js (e.g., "user" for --user) */
+    flag?: string;
+    /** Short switch letter for Commander.js (e.g., "u" for -u) */
+    letter?: string;
+    required?: boolean;
+    type: ConversionType;
+    validate?: ValidateFunction | RegExp | Array<unknown>;
+}
+export type ValidateFunction = (value: unknown) => boolean | void | Promise<boolean | void>;
+/**
+ * Context passed to service functions for callbacks and utilities
+ */
+export interface ServiceContext {
+    /** Report a recoverable error during service execution (does not throw) */
+    onError?: (error: unknown) => void | Promise<void>;
+    /** Report a fatal error during service execution (does not throw) */
+    onFatal?: (error: unknown) => void | Promise<void>;
+    /** Send a message during service execution (connects to onMessage callback) */
+    sendMessage?: (message: Message) => void | Promise<void>;
+}
+export type ServiceFunction<TInput, TOutput> = (input: TInput, context?: ServiceContext) => TOutput | Promise<TOutput>;
+export interface ServiceConfig<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown> {
+    alias?: string;
+    description?: string;
+    input?: Record<string, InputFieldDefinition>;
+    service?: ServiceFunction<TInput, TOutput>;
+}
+export interface Service<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown> extends ServiceConfig<TInput, TOutput> {
+    (input?: Partial<TInput> | string, context?: ServiceContext): Promise<TOutput>;
+    /** Fabric version identifier - used to detect pre-instantiated Services */
+    $fabric?: string;
+}

package/dist/esm/commander/FabricCommander.d.ts

@@ -0,0 +1,94 @@
+import { Command } from "commander";
+import type { InputFieldDefinition, Service, ServiceFunction } from "../types.js";
+import type { OnCompleteCallback, OnErrorCallback, OnFatalCallback, OnMessageCallback } from "./types.js";
+/**
+ * Inline service definition for FabricCommander
+ * Allows defining services directly in the services array
+ */
+export interface InlineServiceDefinition {
+    /** Service alias (used as command name) */
+    alias: string;
+    /** Service description */
+    description?: string;
+    /** Input field definitions */
+    input?: Record<string, InputFieldDefinition>;
+    /** The service function */
+    service: ServiceFunction<Record<string, unknown>, unknown>;
+}
+/**
+ * Service entry - either a pre-instantiated Service or an inline definition
+ */
+export type ServiceEntry = Service | InlineServiceDefinition;
+/**
+ * Configuration for FabricCommander
+ */
+export interface FabricCommanderConfig {
+    /** CLI description */
+    description?: string;
+    /** CLI name (defaults to process.argv script name) */
+    name?: string;
+    /** Default callback called when any command completes successfully */
+    onComplete?: OnCompleteCallback;
+    /** Default callback called when any command encounters an error */
+    onError?: OnErrorCallback;
+    /** Default callback called when any command encounters a fatal error */
+    onFatal?: OnFatalCallback;
+    /** Default callback called to report progress messages */
+    onMessage?: OnMessageCallback;
+    /** Services to register as commands */
+    services: ServiceEntry[];
+    /** CLI version */
+    version?: string;
+}
+/**
+ * FabricCommander - Convenient wrapper for creating multi-command CLIs
+ *
+ * Creates a Commander program with multiple service commands in a single call.
+ *
+ * @example
+ * ```typescript
+ * // Array form - simple list of services
+ * const cli = new FabricCommander([greetService, farewellService]);
+ * cli.parse();
+ *
+ * // Config form - with description and version
+ * const cli = new FabricCommander({
+ *   name: "my-cli",
+ *   description: "My CLI application",
+ *   version: "1.0.0",
+ *   services: [greetService, farewellService],
+ * });
+ * cli.parse();
+ *
+ * // With inline service definitions
+ * const cli = new FabricCommander({
+ *   description: "My CLI",
+ *   version: "1.0.0",
+ *   services: [
+ *     existingService,
+ *     {
+ *       alias: "greet",
+ *       description: "Greet a user",
+ *       input: { name: { type: String } },
+ *       service: ({ name }) => `Hello, ${name}!`,
+ *     },
+ *   ],
+ * });
+ * cli.parse();
+ * ```
+ */
+export declare class FabricCommander {
+    /** The underlying Commander Command instance */
+    readonly command: Command;
+    constructor(config: ServiceEntry[] | FabricCommanderConfig);
+    /**
+     * Parse command-line arguments
+     * Delegates to Commander's parse method
+     */
+    parse(argv?: readonly string[]): this;
+    /**
+     * Parse command-line arguments asynchronously
+     * Delegates to Commander's parseAsync method
+     */
+    parseAsync(argv?: readonly string[]): Promise<this>;
+}

package/dist/esm/commander/createCommanderOptions.d.ts

@@ -0,0 +1,25 @@
+import type { InputFieldDefinition } from "../types.js";
+import type { CreateCommanderOptionsConfig, CreateCommanderOptionsResult } from "./types.js";
+/**
+ * Create Commander.js Option objects from a service config
+ *
+ * @param input - The input field definitions from a service config
+ * @param config - Optional configuration for excluding fields or overriding options
+ * @returns An object containing an array of Commander Option objects
+ *
+ * @example
+ * ```typescript
+ * const handler = createService({
+ *   input: {
+ *     name: { type: String, description: "User name" },
+ *     age: { type: Number, default: 25 },
+ *     verbose: { type: Boolean },
+ *   },
+ *   service: (input) => input,
+ * });
+ *
+ * const { options } = createCommanderOptions(handler.input);
+ * options.forEach(opt => command.addOption(opt));
+ * ```
+ */
+export declare function createCommanderOptions(input?: Record<string, InputFieldDefinition>, config?: CreateCommanderOptionsConfig): CreateCommanderOptionsResult;

package/dist/esm/commander/fabricCommand.d.ts

@@ -0,0 +1,43 @@
+import type { FabricCommandConfig, FabricCommandResult } from "./types.js";
+/**
+ * Fabric a service as a Commander.js command
+ *
+ * This function creates a command from a service, automatically:
+ * - Creating the command with the service's alias (or custom name)
+ * - Adding a description from the service's description (or custom)
+ * - Converting input definitions to Commander options
+ * - Wiring up the action to call the service with parsed input
+ *
+ * Error handling:
+ * - Services can call context.onError() for recoverable errors
+ * - Services can call context.onFatal() for fatal errors
+ * - Any error that throws out of the service is treated as fatal
+ *
+ * @param config - Configuration including service, program, and optional overrides
+ * @returns An object containing the created command
+ *
+ * @example
+ * ```typescript
+ * import { Command } from "commander";
+ * import { fabricService } from "@jaypie/fabric";
+ * import { fabricCommand } from "@jaypie/fabric/commander";
+ *
+ * const myService = fabricService({
+ *   alias: "greet",
+ *   description: "Greet a user",
+ *   input: {
+ *     userName: { type: String, description: "User name" },
+ *     loud: { type: Boolean, description: "Shout greeting" },
+ *   },
+ *   service: ({ userName, loud }) => {
+ *     const greeting = `Hello, ${userName}!`;
+ *     return loud ? greeting.toUpperCase() : greeting;
+ *   },
+ * });
+ *
+ * const program = new Command();
+ * fabricCommand({ program, service: myService });
+ * program.parse();
+ * ```
+ */
+export declare function fabricCommand({ alias, description, exclude, input, name, onComplete, onError, onFatal, onMessage, overrides, program, service: serviceOrFunction, }: FabricCommandConfig): FabricCommandResult;

package/dist/esm/commander/index.d.ts

@@ -0,0 +1,6 @@
+export { createCommanderOptions } from "./createCommanderOptions.js";
+export { fabricCommand } from "./fabricCommand.js";
+export { FabricCommander } from "./FabricCommander.js";
+export { parseCommanderOptions } from "./parseCommanderOptions.js";
+export type { FabricCommanderConfig, InlineServiceDefinition, ServiceEntry, } from "./FabricCommander.js";
+export type { CommanderOptionOverride, CreateCommanderOptionsConfig, CreateCommanderOptionsResult, FabricCommandConfig, FabricCommandResult, OnCompleteCallback, OnErrorCallback, OnFatalCallback, OnMessageCallback, ParseCommanderOptionsConfig, } from "./types.js";