@forthix/forthic 0.7.2 → 0.8.1

package/dist/cjs/forthic/decorators/schemaUtils.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/**
+ * Registry metadata types for stack objects and class instances.
+ */
+type StackObjectMetadata = {
+    objectType: "stackObject";
+    stackObjectType: string;
+    className?: undefined;
+    OriginalClass?: undefined;
+} | {
+    objectType: "class";
+    OriginalClass: new (...args: any[]) => any;
+    className: string;
+    stackObjectType?: undefined;
+};
+/**
+ * Track metadata for schema comparison in tests and documentation.
+ * Only required for schemas that can't be compared out of the box,
+ * like custom schemas or instanceof schemas.
+ */
+export declare const stackObjectRegistry: z.core.$ZodRegistry<StackObjectMetadata, z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+/**
+ * Creates a Zod schema for stack objects that have a stackObjectType property.
+ * This is a helper to reduce boilerplate when creating custom stack object schemas.
+ * It also ensures the schema is registered in stackObjectRegistry, which enables
+ * proper type string generation in stack effects.
+ *
+ * Use this instead of z.custom() directly for stack objects.
+ *
+ * @example
+ * ```ts
+ * interface StackEmail {
+ *   stackObjectType: "email";
+ *   to: string;
+ *   subject: string;
+ *   body: string;
+ * }
+ *
+ * const stackEmailSchema = createStackObjectSchema<StackEmail>("email");
+ *
+ * // Use in stack effect:
+ * @ForthicWord(se`(email:${stackEmailSchema} -- sent:${z.boolean()})`, "Send email")
+ * async SEND(email: StackEmail): Promise<boolean> { ... }
+ * ```
+ */
+export declare function createStackObjectSchema<T extends {
+    stackObjectType: string;
+}>(stackObjectType: string, errorMessage?: string): z.ZodCustom<T>;
+/**
+ * Creates a Zod instanceof schema with automatic metadata registration.
+ * This ensures the schema is registered in stackObjectRegistry, which enables
+ * proper type string generation in stack effects.
+ *
+ * Use this instead of z.instanceof() directly.
+ *
+ * @example
+ * ```ts
+ * import { Temporal } from "temporal-polyfill";
+ *
+ * const plainDateSchema = createInstanceOfSchema(Temporal.PlainDate);
+ *
+ * // Use in stack effect:
+ * @ForthicWord(se`(date:${plainDateSchema} -- formatted:${z.string()})`, "Format date")
+ * async FORMAT(date: Temporal.PlainDate): Promise<string> { ... }
+ * ```
+ */
+export declare function createInstanceOfSchema<T extends abstract new (...args: any[]) => any>(ClassToSchematize: T, 
+/** If not passed, falls back to class.name */
+className?: string): z.ZodType<InstanceType<T>>;
+export {};

package/dist/cjs/forthic/decorators/schemaUtils.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stackObjectRegistry = void 0;
+exports.createStackObjectSchema = createStackObjectSchema;
+exports.createInstanceOfSchema = createInstanceOfSchema;
+const zod_1 = require("zod");
+/**
+ * Track metadata for schema comparison in tests and documentation.
+ * Only required for schemas that can't be compared out of the box,
+ * like custom schemas or instanceof schemas.
+ */
+exports.stackObjectRegistry = zod_1.z.registry();
+/**
+ * Creates a Zod schema for stack objects that have a stackObjectType property.
+ * This is a helper to reduce boilerplate when creating custom stack object schemas.
+ * It also ensures the schema is registered in stackObjectRegistry, which enables
+ * proper type string generation in stack effects.
+ *
+ * Use this instead of z.custom() directly for stack objects.
+ *
+ * @example
+ * ```ts
+ * interface StackEmail {
+ *   stackObjectType: "email";
+ *   to: string;
+ *   subject: string;
+ *   body: string;
+ * }
+ *
+ * const stackEmailSchema = createStackObjectSchema<StackEmail>("email");
+ *
+ * // Use in stack effect:
+ * @ForthicWord(se`(email:${stackEmailSchema} -- sent:${z.boolean()})`, "Send email")
+ * async SEND(email: StackEmail): Promise<boolean> { ... }
+ * ```
+ */
+function createStackObjectSchema(stackObjectType, errorMessage) {
+    const schema = zod_1.z.custom((maybeStackObject) => maybeStackObject?.stackObjectType === stackObjectType, errorMessage ?? `expected ${stackObjectType} stackObjectType`);
+    // Register schema with metadata
+    exports.stackObjectRegistry.add(schema, {
+        objectType: "stackObject",
+        stackObjectType,
+    });
+    return schema;
+}
+/**
+ * Creates a Zod instanceof schema with automatic metadata registration.
+ * This ensures the schema is registered in stackObjectRegistry, which enables
+ * proper type string generation in stack effects.
+ *
+ * Use this instead of z.instanceof() directly.
+ *
+ * @example
+ * ```ts
+ * import { Temporal } from "temporal-polyfill";
+ *
+ * const plainDateSchema = createInstanceOfSchema(Temporal.PlainDate);
+ *
+ * // Use in stack effect:
+ * @ForthicWord(se`(date:${plainDateSchema} -- formatted:${z.string()})`, "Format date")
+ * async FORMAT(date: Temporal.PlainDate): Promise<string> { ... }
+ * ```
+ */
+function createInstanceOfSchema(ClassToSchematize, 
+/** If not passed, falls back to class.name */
+className) {
+    const schema = zod_1.z.instanceof(ClassToSchematize);
+    // Register schema with metadata
+    const resolvedClassName = className ?? ClassToSchematize.name;
+    exports.stackObjectRegistry.add(schema, {
+        objectType: "class",
+        OriginalClass: ClassToSchematize,
+        className: resolvedClassName,
+    });
+    return schema;
+}
+//# sourceMappingURL=schemaUtils.js.map

package/dist/cjs/forthic/decorators/schemaUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaUtils.js","sourceRoot":"","sources":["../../../../src/forthic/decorators/schemaUtils.ts"],"names":[],"mappings":";;;AAkDA,0DAgBC;AAoBD,wDAgBC;AAtGD,6BAAwB;AAmBxB;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,OAAC,CAAC,QAAQ,EAAuB,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,uBAAuB,CACrC,eAAuB,EACvB,YAAqB;IAErB,MAAM,MAAM,GAAG,OAAC,CAAC,MAAM,CACrB,CAAC,gBAAgB,EAAE,EAAE,CAAE,gBAAkC,EAAE,eAAe,KAAK,eAAe,EAC9F,YAAY,IAAI,YAAY,eAAe,kBAAkB,CAC9D,CAAC;IAEF,gCAAgC;IAChC,2BAAmB,CAAC,GAAG,CAAC,MAAM,EAAE;QAC9B,UAAU,EAAE,aAAa;QACzB,eAAe;KAChB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,sBAAsB,CACpC,iBAAoB;AACpB,8CAA8C;AAC9C,SAAkB;IAElB,MAAM,MAAM,GAAG,OAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAE/C,gCAAgC;IAChC,MAAM,iBAAiB,GAAG,SAAS,IAAI,iBAAiB,CAAC,IAAI,CAAC;IAC9D,2BAAmB,CAAC,GAAG,CAAC,MAAM,EAAE;QAC9B,UAAU,EAAE,OAAO;QACnB,aAAa,EAAE,iBAAiB;QAChC,SAAS,EAAE,iBAAiB;KAC7B,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cjs/forthic/decorators/stackEffect.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import type { util as zodUtil } from "zod/v4/core";
+/**
+ * Map the set of Zod types to the strings we use in Forthic stack effects.
+ * Uses Zod's internal def.type for comprehensive type detection.
+ */
+export declare const mapZodToStackEffectType: (zodType: z.ZodTypeAny) => string;
+type InferTupleTypes<T extends zodUtil.TupleItems> = {
+    [K in keyof T]: T[K] extends z.ZodTypeAny ? z.infer<T[K]> : never;
+};
+/**
+ * Represents a type-safe stack effect with Zod schemas for validation.
+ *
+ * @template Args - Tuple of Zod schemas for input parameters
+ * @template Return - Zod schema for the return type
+ */
+export type TaggedStackEffect<Args extends zodUtil.TupleItems, Return extends z.core.$ZodFunctionOut = z.core.$ZodFunctionOut> = {
+    /** The human-readable stack effect string (e.g., "( a:number b:string -- result:string )") */
+    stackEffect: string;
+    /** Zod schemas for runtime validation */
+    schema: {
+        inputSchemas: z.ZodTypeAny[];
+        outputSchema: z.ZodTypeAny;
+    };
+    /**
+     * Phantom property to convey the expected function signature, constructed from the input + output types.
+     * DO NOT USE AT RUNTIME - it's only used for type inference.
+     */
+    _implType: (...args: InferTupleTypes<Args>) => Promise<z.infer<Return>>;
+};
+/**
+ * Tagged template literal for stack effects. Use with the @ForthicWord decorator to
+ * create a type-safe stack effect.
+ *
+ * @example
+ * ```ts
+ * // Type-safe stack effect with Zod validation
+ * @ForthicWord(se`(a:${z.number()} b:${z.string()} -- result:${z.string()})`, "Concatenate number and string")
+ * async CONCAT(a: number, b: string): Promise<string> {
+ *   return `${a}${b}`;
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // No parameters, returns string
+ * @ForthicWord(se`( -- message:${z.string()})`, "Get greeting")
+ * async GREET(): Promise<string> {
+ *   return "Hello!";
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Takes string, no return (void)
+ * @ForthicWord(se`(input:${z.string()} -- ${z.void()})`, "Log to console")
+ * async LOG(input: string): Promise<void> {
+ *   console.log(input);
+ * }
+ * ```
+ */
+export declare const se: <Args extends zodUtil.TupleItems, Return extends z.core.$ZodFunctionOut>(template: TemplateStringsArray, ...values: [...Args, Return]) => TaggedStackEffect<Args, Return>;
+export {};

package/dist/cjs/forthic/decorators/stackEffect.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.se = exports.mapZodToStackEffectType = void 0;
+const schemaUtils_js_1 = require("./schemaUtils.js");
+/**
+ * Map the set of Zod types to the strings we use in Forthic stack effects.
+ * Uses Zod's internal def.type for comprehensive type detection.
+ */
+const mapZodToStackEffectType = (zodType) => {
+    const def = zodType.def;
+    switch (def.type) {
+        case "string":
+            return "string";
+        case "int":
+        case "bigint":
+            return "number";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "undefined":
+        case "void":
+            return "";
+        case "date":
+            return "date";
+        case "symbol":
+            return "symbol";
+        case "object": {
+            const objectDef = def;
+            const objectShape = objectDef.shape;
+            // Get all property types
+            const properties = Object.entries(objectShape).map(([key, fieldSchema]) => {
+                const fieldType = (0, exports.mapZodToStackEffectType)(fieldSchema);
+                return `${key}: ${fieldType}`;
+            });
+            // Return formatted object type
+            return properties.length > 0 ? `{ ${properties.join(", ")} }` : "{}";
+        }
+        case "literal": {
+            const literalDef = def;
+            const value = literalDef.values[0];
+            // Quote string literals
+            return typeof value === "string" ? `"${value}"` : String(value);
+        }
+        case "enum": {
+            const enumDef = def;
+            const enumEntries = Object.values(enumDef.entries);
+            // Return union of quoted values - zod enums are always strings
+            return enumEntries.map((entry) => `"${entry}"`).join("|");
+        }
+        case "optional": {
+            const optionalDef = def;
+            const innerType = (0, exports.mapZodToStackEffectType)(optionalDef.innerType);
+            // Optional is a union with undefined
+            return innerType ? `${innerType}|undefined` : "undefined";
+        }
+        case "nullable": {
+            const nullableDef = def;
+            const innerType = (0, exports.mapZodToStackEffectType)(nullableDef.innerType);
+            // Nullable is a union with null
+            return innerType ? `${innerType}|null` : "null";
+        }
+        case "union": {
+            const unionDef = def;
+            const unionOptions = unionDef.options;
+            // Recursively get types for all union options
+            const optionTypes = unionOptions.map((option) => (0, exports.mapZodToStackEffectType)(option));
+            // Dedupe
+            return [...new Set(optionTypes)].join("|");
+        }
+        case "tuple": {
+            const tupleDef = def;
+            const tupleItems = tupleDef.items;
+            const elementTypes = tupleItems.map((item) => (0, exports.mapZodToStackEffectType)(item));
+            return `[${elementTypes.join(", ")}]`;
+        }
+        case "array": {
+            const arrayDef = def;
+            const elementType = (0, exports.mapZodToStackEffectType)(arrayDef.element);
+            // If the element is a union (contains "|") but not already an array type (doesn't end with "]"),
+            // wrap it in parentheses
+            const needsParens = elementType.includes("|") && !elementType.endsWith("]");
+            const wrappedType = needsParens ? `(${elementType})` : elementType;
+            return `${wrappedType}[]`;
+        }
+        case "custom": {
+            const metadata = schemaUtils_js_1.stackObjectRegistry.get(zodType);
+            if (!metadata) {
+                throw new Error(`Custom schema found without stack object registry entry. Consider using createStackObjectSchema or createInstanceOfSchema or manually registering the schema.`);
+            }
+            return metadata.stackObjectType ?? metadata.className ?? "object";
+        }
+        case "any":
+            return "any";
+        case "record":
+        case "function":
+        case "promise":
+        case "map":
+        case "set":
+        case "lazy":
+        case "never":
+        case "unknown":
+        case "file":
+        case "nonoptional":
+        case "success":
+        case "transform":
+        case "prefault":
+        case "nan":
+        case "pipe":
+        case "template_literal":
+        case "intersection":
+        case "catch":
+        case "default":
+        case "readonly":
+            // Unsupported types - throw error to ensure we handle everything
+            throw new Error(`Stack effect string generation not supported for type: "${def.type}" - you may either update mapZodToStackEffectType or use a simpler type (e.g. use createStackObjectSchema)`);
+        default:
+            throw new Error(`Unknown type: "${def.type}". You either need to update mapZodToStackEffectType, or zod is doing something unexpected.`);
+    }
+};
+exports.mapZodToStackEffectType = mapZodToStackEffectType;
+/**
+ * Tagged template literal for stack effects. Use with the @ForthicWord decorator to
+ * create a type-safe stack effect.
+ *
+ * @example
+ * ```ts
+ * // Type-safe stack effect with Zod validation
+ * @ForthicWord(se`(a:${z.number()} b:${z.string()} -- result:${z.string()})`, "Concatenate number and string")
+ * async CONCAT(a: number, b: string): Promise<string> {
+ *   return `${a}${b}`;
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // No parameters, returns string
+ * @ForthicWord(se`( -- message:${z.string()})`, "Get greeting")
+ * async GREET(): Promise<string> {
+ *   return "Hello!";
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Takes string, no return (void)
+ * @ForthicWord(se`(input:${z.string()} -- ${z.void()})`, "Log to console")
+ * async LOG(input: string): Promise<void> {
+ *   console.log(input);
+ * }
+ * ```
+ */
+const se = (template, ...values) => {
+    const stackEffectTypes = values.map((value) => (0, exports.mapZodToStackEffectType)(value));
+    // Outputs the template string as if it weren't tagged, e.g. "( a:string b:number -- c:number )"
+    const parts = [];
+    for (let i = 0; i < template.length; i++) {
+        parts.push(template[i]);
+        if (i < stackEffectTypes.length) {
+            parts.push(stackEffectTypes[i]);
+        }
+    }
+    const outStr = parts.join("");
+    const taggedStackEffect = {
+        stackEffect: outStr,
+        schema: {
+            inputSchemas: values.slice(0, -1),
+            outputSchema: values[values.length - 1],
+        },
+        _implType: async () => {
+            throw new Error("This function should not be called at runtime, it's only used for type inference");
+        },
+    };
+    return taggedStackEffect;
+};
+exports.se = se;
+//# sourceMappingURL=stackEffect.js.map

package/dist/cjs/forthic/decorators/stackEffect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stackEffect.js","sourceRoot":"","sources":["../../../../src/forthic/decorators/stackEffect.ts"],"names":[],"mappings":"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"}

package/dist/cjs/forthic/interpreter.d.ts

@@ -1,6 +1,7 @@
 import { Token, Tokenizer, CodeLocation } from "./tokenizer.js";
 import { Module, Word } from "./module.js";
 import { LiteralHandler } from "./literals.js";
+import { StackValue } from "../websocket/serializer.js";
 type Timestamp = {
     label: string;
     time_ms: number;
@@ -55,6 +56,7 @@ export declare class Interpreter {
     private is_compiling;
     private is_memo_definition;
     private cur_definition;
+    private definition_start_input_pos;
     private string_location?;
     private word_counts;
     private is_profiling;
@@ -164,6 +166,25 @@ export declare class Interpreter {
     endStream(): void;
 }
 export declare function dup_interpreter(interp: Interpreter): Interpreter;
+/**
+ * Serializable interpreter state for preserving variables, words, and stack
+ * across interpreter instantiations (e.g., multiturn chat sessions).
+ */
+export interface InterpreterState {
+    stack: StackValue[];
+    variables: Record<string, StackValue>;
+    word_definitions: string[];
+}
+/**
+ * Export the app module state and stack from an interpreter as a serializable object.
+ * The caller is responsible for persisting the returned state.
+ */
+export declare function export_state(interp: Interpreter): InterpreterState;
+/**
+ * Import previously exported state into an interpreter.
+ * Replays word definitions, restores variable values, and sets the stack.
+ */
+export declare function import_state(interp: Interpreter, state: InterpreterState): Promise<void>;
 /**
  * Interpreter - Full-featured interpreter with standard library
  *

package/dist/cjs/forthic/interpreter.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StandardInterpreter = exports.Interpreter = exports.Stack = void 0;
 exports.dup_interpreter = dup_interpreter;
+exports.export_state = export_state;
+exports.import_state = import_state;
 const tokenizer_js_1 = require("./tokenizer.js");
 const module_js_1 = require("./module.js");
 const tokenizer_js_2 = require("./tokenizer.js");
@@ -15,6 +17,7 @@ const math_module_js_1 = require("./modules/standard/math_module.js");
 const boolean_module_js_1 = require("./modules/standard/boolean_module.js");
 const json_module_js_1 = require("./modules/standard/json_module.js");
 const datetime_module_js_1 = require("./modules/standard/datetime_module.js");
+const serializer_js_1 = require("../websocket/serializer.js");
 /**
  * StartModuleWord - Handles module creation and switching
  *
@@ -183,6 +186,7 @@ class Interpreter {
     is_compiling;
     is_memo_definition;
     cur_definition;
+    definition_start_input_pos;
     string_location;
     word_counts;
     is_profiling;
@@ -206,6 +210,7 @@ class Interpreter {
         this.is_compiling = false;
         this.is_memo_definition = false;
         this.cur_definition = null;
+        this.definition_start_input_pos = 0;
         // Debug support
         this.string_location = undefined;
         // Profiling support
@@ -724,6 +729,8 @@ class Interpreter {
         this.cur_definition = new module_js_1.DefinitionWord(token.string);
         this.is_compiling = true;
         this.is_memo_definition = false;
+        // Record the position right after the definition name for source capture
+        this.definition_start_input_pos = this.get_tokenizer().input_pos;
     }
     handle_start_memo_token(token) {
         if (this.is_compiling) {
@@ -732,13 +739,22 @@ class Interpreter {
         this.cur_definition = new module_js_1.DefinitionWord(token.string);
         this.is_compiling = true;
         this.is_memo_definition = true;
+        // Record the position right after the memo name for source capture
+        this.definition_start_input_pos = this.get_tokenizer().input_pos;
     }
     handle_end_definition_token(token) {
         if (!this.is_compiling || !this.cur_definition) {
             throw new errors_js_1.ExtraSemicolonError(this.get_top_input_string(), token.location);
         }
+        // Construct the source text for serialization
+        const tokenizer = this.get_tokenizer();
+        const body = tokenizer.input_string.substring(this.definition_start_input_pos, tokenizer.input_pos);
+        const prefix = this.is_memo_definition ? "@:" : ":";
+        const source = `${prefix} ${this.cur_definition.name} ${body}`;
+        this.cur_definition.source = source;
         if (this.is_memo_definition) {
-            this.cur_module().add_memo_words(this.cur_definition);
+            const memoWord = this.cur_module().add_memo_words(this.cur_definition);
+            memoWord.source = source;
         }
         else {
             this.cur_module().add_word(this.cur_definition);
@@ -860,6 +876,65 @@ function dup_interpreter(interp) {
     }
     return result_interp;
 }
+/**
+ * Export the app module state and stack from an interpreter as a serializable object.
+ * The caller is responsible for persisting the returned state.
+ */
+function export_state(interp) {
+    const internal = interp;
+    // Serialize the stack
+    const stack = (0, serializer_js_1.serializeStack)(internal.stack.get_items());
+    // Serialize variables
+    const variables = {};
+    const appModule = internal.app_module;
+    for (const [name, variable] of Object.entries(appModule.variables)) {
+        variables[name] = (0, serializer_js_1.serializeValue)(variable.get_value());
+    }
+    // Collect source text from user-defined words
+    const word_definitions = [];
+    const seen = new Set();
+    for (const word of appModule.words) {
+        if (word instanceof module_js_1.DefinitionWord && word.source) {
+            // For DefinitionWords, use the source directly (avoids duplicates from memo bang variants)
+            if (!seen.has(word.name)) {
+                seen.add(word.name);
+                word_definitions.push(word.source);
+            }
+        }
+        else if (word instanceof module_js_1.ModuleMemoWord && word.source) {
+            if (!seen.has(word.name)) {
+                seen.add(word.name);
+                word_definitions.push(word.source);
+            }
+        }
+    }
+    return { stack, variables, word_definitions };
+}
+/**
+ * Import previously exported state into an interpreter.
+ * Replays word definitions, restores variable values, and sets the stack.
+ */
+async function import_state(interp, state) {
+    const internal = interp;
+    // 1. Replay word definitions (this may also create variables via VARIABLES word)
+    for (const def of state.word_definitions) {
+        await interp.run(def);
+    }
+    // 2. Restore variable values (overwriting any defaults from definitions)
+    const appModule = internal.app_module;
+    for (const [name, serializedValue] of Object.entries(state.variables)) {
+        const value = (0, serializer_js_1.deserializeValue)(serializedValue);
+        if (appModule.variables[name]) {
+            appModule.variables[name].set_value(value);
+        }
+        else {
+            appModule.add_variable(name, value);
+        }
+    }
+    // 3. Restore the stack
+    const stackItems = (0, serializer_js_1.deserializeStack)(state.stack);
+    internal.stack.set_raw_items(stackItems);
+}
 /**
  * Interpreter - Full-featured interpreter with standard library
  *