v0.5.0 - Per-Word Error Handlers & Enhanced Datetime Support

What's New in v0.5.0

🎯 Per-Word Error Handlers

You can now attach custom error handlers to individual Forthic words, enabling fine-grained error handling and recovery strategies. This allows for more robust error management in complex Forthic applications.

📅 Zoned Datetime Literals

Added support for zoned datetime literals using bracket notation, making it easier to work with timezone-aware dates and times directly in Forthic code.

🔧 Improvements

• Enhanced literal handling - Refined literal handler priority system for more predictable parsing behavior
• Better error propagation - Improved wrap/rethrow mechanisms for clearer error traces during word execution
• Deno compatibility - Added .js extension support for seamless Deno runtime integration
• Robust error messages - Revised Error class to handle edge cases and provide more helpful error information

📊 Testing

• 573 tests passing across all modules
• Full compatibility maintained with existing code

---

For detailed changes, see the v0.4.0...v0.5.0.

v0.4.0

Forthic TypeScript Runtime v0.4.0

Overview

Version 0.4.0 introduces multi-runtime execution capabilities for Forthic, allowing TypeScript to seamlessly call code in other language runtimes (Python, Ruby, etc.) and vice versa. This release also includes significant architectural improvements to the module and decorator systems.

🚀 Major Features

Multi-Runtime Execution

Call Forthic words across different language runtimes using gRPC or WebSocket protocols:

import { GrpcClient, RemoteModule } from '@forthix/forthic/grpc';

const client = new GrpcClient('localhost:50051');
const pandas = new RemoteModule('pandas', client, 'python');
await pandas.initialize();

interp.register_module(pandas);
// Now use Python pandas from TypeScript!

New exports:

• @forthix/forthic/grpc - Node.js-only gRPC client/server for multi-runtime
• @forthix/forthic/websocket - Browser-compatible WebSocket support (ActionCable)

Key capabilities:

• gRPC-based communication for Node.js ↔ Python ↔ Ruby
• WebSocket (ActionCable) support for browser ↔ Rails
• YAML-based runtime configuration
• Type-safe serialization across runtimes
• Automatic connection management

📦 Package Improvements

Enhanced Package Exports

The package now provides environment-aware exports:

• Main (@forthix/forthic): Core interpreter (Node.js + Browser)
• WebSocket (@forthix/forthic/websocket): Browser-compatible multi-runtime
• gRPC (@forthix/forthic/grpc): Node.js-only multi-runtime with browser stubs

🏗️ Architecture Changes

Unified Word Decorator System

Simplified decorator API across all runtimes (forthic-ts/src/forthic/decorators/word.ts:1):

• Consistent @Word() decorator interface
• Improved metadata extraction for documentation
• Better TypeScript type inference

Module Reorganization

Standard library modules moved to src/forthic/modules/standard/:

• array_module.ts
• boolean_module.ts
• core_module.ts
• datetime_module.ts
• json_module.ts
• math_module.ts
• record_module.ts
• string_module.ts

Runtime-specific modules in src/forthic/modules/typescript/:

• fs_module.ts (filesystem operations)

📚 Documentation

New Documentation

• Multi-Runtime Overview - Complete guide to cross-runtime execution
• gRPC Setup - Server and client configuration
• WebSocket Setup - Browser-compatible communication
• Configuration Guide - YAML-based runtime management
• TESTING.md - Comprehensive testing guidelines

🔧 Developer Experience

Documentation Generation

Enhanced doc generation script (forthic-ts/scripts/generate-docs.ts:1):

• Works with new decorator system
• Generates module-level documentation
• Extracts word signatures and examples

Testing Infrastructure

• New integration tests for gRPC and WebSocket
• Runtime manager tests
• Serialization compatibility tests
• Improved test organization

🐛 Bug Fixes

• Fixed documentation generation with new decorators (forthic-ts/fda12b3)
• Fixed examples to work with updated API (forthic-ts/e9c5e71)
• Ensured runtime can execute outside of Node.js (forthic-ts/a562655)

📝 Breaking Changes

Module Paths

Standard library module imports have moved:

// Before (v0.3.0)
import { ArrayModule } from '@forthix/forthic/modules/array_module';

// After (v0.4.0)
import { ArrayModule } from '@forthix/forthic/modules/standard/array_module';

Note: This only affects direct module imports. Using the standard Interpreter constructor automatically registers all standard modules.

Word Naming Convention

Reverted to hyphenated word names for consistency (forthic-ts/ed6e219):

• FILTER-OUTLIERS (not FILTER_OUTLIERS)
• USE-MODULES (not USE_MODULES)

🔄 Migration Guide

For most users upgrading from v0.3.0, no changes are required:

// This still works exactly the same
import { Interpreter } from '@forthix/forthic';
const interp = new Interpreter();
await interp.run('[1 2 3] "2 *" MAP');

To use new multi-runtime features:

// Add optional gRPC dependencies
npm install @grpc/grpc-js @grpc/proto-loader

// Import and use
import { GrpcClient, RemoteModule } from '@forthix/forthic/grpc';

📊 Dependencies

New Optional Dependencies

• @grpc/grpc-js: ^1.12.0 - gRPC client/server (Node.js only)
• @grpc/proto-loader: ^0.7.0 - Protocol buffer loader

Updated Dependencies

• typescript: ^5.7.2
• temporal-polyfill: ^0.2.5 (for Temporal API support)

v0.3.0

Go back to hyphenated words

v0.2.0

Permit one character dot symbols
Rename .s to PEEK!
Rename .S to STACK!

v0.1.2

Config fixes to support forthix-cli

v0.1.0

Initial Public Release

This is the first public release of the Forthic TypeScript/JavaScript runtime, published to npm as @forthix/forthic.

🎉 What's New

Core Features

• Stack-based Interpreter: Full-featured Forthic interpreter with support for:

  • Variable management with auto-creation
  • Module system with imports

• Standard Library Modules:

  • CoreModule: Stack operations, variables, module system, printing
  • ArrayModule: Comprehensive array operations (MAP, SELECT, REDUCE, etc.)
  • RecordModule: Record/object manipulation (REC, REC@, REC!, etc.)
  • StringModule: String operations (SPLIT, JOIN, UPPERCASE, etc.)
  • MathModule: Mathematical operations and statistics
  • BooleanModule: Logical operations (AND, OR, NOT, etc.)
  • JsonModule: JSON serialization/deserialization
  • DateTimeModule: Temporal date/time operations

Language Features

• Enhanced Module System: USE_MODULES now imports without prefix by default

  • Before: ['math'] USE_MODULES → required math.SQRT
  • After: ['math'] USE_MODULES → can use SQRT directly
  • Explicit prefixes still supported: [['math' 'm']] USE_MODULES → m.SQRT

• Improved PRINT Word: Now handles any value type

  • Strings: Variable interpolation with .varname syntax
  • Non-strings: Direct formatting with options support
  • Options: separator, null_text, json for customization

• CLI & REPL:

  • npm run forthic <file> - Run Forthic scripts
  • npm run repl - Interactive REPL with stack inspection
  • REPL commands: .stack, .reset, .exit
  • Debug words: .s (print top), .S (print full stack)

Developer Experience

• TypeScript Decorator-based API: Clean module definition with @Word decorator
• Comprehensive Test Suite: 481 tests covering all modules and features
• Full Documentation:
  • README with quick start guide
  • CONTRIBUTING guide for developers
  • Examples demonstrating key features
  • PUBLISHING guide for maintainers