@6digit/mnemonics

Dynamic semantic evaluation system for Fragment data using Subscript expressions with recursive dependency resolution.

Features

• 🧠 Dynamic Evaluation: Evaluate Subscript expressions against Fragment data
• 🔄 Recursive Dependencies: Mnemonics can depend on other mnemonics
• ⚡ Request-Scoped Caching: Prevent duplicate evaluations within requests
• 🛡️ Cycle Detection: Automatic detection and prevention of circular dependencies
• 🎯 Schema Targeting: Apply mnemonics only to specific Fragment schemas
• 📊 Performance Tracking: Built-in cache statistics and monitoring
• 🔒 Type Safe: Full TypeScript support with comprehensive type definitions

Installation

npm install @6digit/mnemonics

Quick Start

import { MnemonicEvaluator, MnemonicRepository } from '@6digit/mnemonics';

// Implement your repository (connects to your data store)
class MyMnemonicRepository implements MnemonicRepository {
  async getMnemonicByName(name: string) {
    // Fetch mnemonic from your database
    return {
      name: 'luxury_item',
      expression: 'price > 1000 && brand == "Gucci"',
      description: 'Identifies luxury items'
    };
  }
  
  async getAllMnemonics() {
    // Return all mnemonics
  }
  
  async getMnemonicsForSchema(schemaId: string) {
    // Return schema-specific mnemonics
  }
}

// Create evaluator
const evaluator = new MnemonicEvaluator({
  repository: new MyMnemonicRepository(),
  defaultMaxDepth: 10,
  defaultInitialContext: { Math, Date }
});

// Evaluate a mnemonic
const fragment = {
  id: 'fragment-123',
  schemaId: 'product-schema',
  data: { price: 1200, brand: 'Gucci', category: 'handbag' }
};

const result = await evaluator.evaluate('luxury_item', fragment);
console.log(result.result); // true

Recursive Dependencies

Mnemonics can depend on other mnemonics:

// Define dependent mnemonics
const mnemonics = [
  {
    name: 'luxury_item',
    expression: 'price > 1000 && brand == "Gucci"'
  },
  {
    name: 'affordable_luxury', 
    expression: 'luxury_item && price < 5000'
  }
];

// The evaluator automatically resolves dependencies
const result = await evaluator.evaluate('affordable_luxury', fragment);
// Automatically evaluates 'luxury_item' first, then 'affordable_luxury'

Schema Targeting

Restrict mnemonics to specific Fragment schemas:

const mnemonic = {
  name: 'expensive_product',
  expression: 'price > 100',
  targetSchemaIds: ['product-schema', 'item-schema']
};

// Only evaluates if fragment.schemaId matches target schemas

Batch Evaluation

Evaluate multiple mnemonics efficiently:

const results = await evaluator.evaluateMany(
  ['luxury_item', 'affordable_luxury', 'trending'],
  fragment
);

console.log(results.luxury_item.result); // true/false
console.log(results.affordable_luxury.result); // true/false

Error Handling

The package provides specific error types:

import { 
  MnemonicNotFoundError,
  MnemonicExpressionError,
  MnemonicCyclicDependencyError,
  MnemonicMaxDepthError 
} from '@6digit/mnemonics';

try {
  const result = await evaluator.evaluate('unknown_mnemonic', fragment);
} catch (error) {
  if (error instanceof MnemonicNotFoundError) {
    console.log('Mnemonic not found');
  } else if (error instanceof MnemonicCyclicDependencyError) {
    console.log('Circular dependency detected');
  }
}

Performance Monitoring

Track cache performance and statistics:

const cache = createRequestScopedCache();
const stats = cache.getStats();

console.log(`Cache hits: ${stats.hits}`);
console.log(`Cache misses: ${stats.misses}`);
console.log(`Hit ratio: ${cache.getHitRatio()}`);

API Reference

MnemonicEvaluator

The main class for evaluating mnemonics.

Constructor

new MnemonicEvaluator(config: MnemonicEvaluatorConfig)

Methods

• evaluate(mnemonicName: string, fragment: Fragment, options?: EvaluationOptions): Promise<EvaluationResult>
• evaluateMany(mnemonicNames: string[], fragment: Fragment, options?: EvaluationOptions): Promise<Record<string, EvaluationResult>>
• getStats(): Promise<{repository: string, defaultMaxDepth: number, mnemonicCount: number}>

Types

See the types documentation for complete type definitions.

License

MIT