@mmapp/player-core 0.1.0-alpha.1

package/src/__tests__/events.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { EventBus } from '../events/event-bus';
+import { compilePattern, matchTopic, clearPatternCache } from '../events/pattern-matcher';
+
+describe('Pattern Matcher', () => {
+  beforeEach(() => {
+    clearPatternCache();
+  });
+
+  describe('compilePattern', () => {
+    it('compiles exact match patterns', () => {
+      const regex = compilePattern('workflow.order:state_enter');
+      expect(matchTopic(regex, 'workflow.order:state_enter')).toBe(true);
+      expect(matchTopic(regex, 'workflow.order:state_exit')).toBe(false);
+    });
+
+    it('compiles single wildcard (*) patterns', () => {
+      const regex = compilePattern('workflow.*:state_enter');
+      expect(matchTopic(regex, 'workflow.order:state_enter')).toBe(true);
+      expect(matchTopic(regex, 'workflow.task:state_enter')).toBe(true);
+      expect(matchTopic(regex, 'workflow.order:state_exit')).toBe(false);
+    });
+
+    it('wildcard does not cross segment boundaries', () => {
+      const regex = compilePattern('*:completed');
+      expect(matchTopic(regex, 'workflow:completed')).toBe(true);
+      expect(matchTopic(regex, 'workflow.order:completed')).toBe(false); // * doesn't cross .
+    });
+
+    it('compiles double wildcard (**) patterns', () => {
+      const regex = compilePattern('workflow.**');
+      expect(matchTopic(regex, 'workflow.order')).toBe(true);
+      expect(matchTopic(regex, 'workflow.order:state_enter')).toBe(true);
+      expect(matchTopic(regex, 'workflow.a.b.c:deep')).toBe(true);
+      expect(matchTopic(regex, 'other.thing')).toBe(false);
+    });
+
+    it('handles multiple wildcards', () => {
+      const regex = compilePattern('*:*:completed');
+      expect(matchTopic(regex, 'workflow:order:completed')).toBe(true);
+      expect(matchTopic(regex, 'a:b:completed')).toBe(true);
+      expect(matchTopic(regex, 'a:b:failed')).toBe(false);
+    });
+
+    it('escapes regex special characters', () => {
+      const regex = compilePattern('user+name.test');
+      expect(matchTopic(regex, 'user+name.test')).toBe(true);
+      expect(matchTopic(regex, 'userXname.test')).toBe(false);
+    });
+
+    it('caches compiled patterns', () => {
+      const r1 = compilePattern('test.pattern');
+      const r2 = compilePattern('test.pattern');
+      expect(r1).toBe(r2); // Same reference from cache
+    });
+  });
+
+  describe('matchTopic', () => {
+    it('matches exact topics', () => {
+      const regex = compilePattern('events:order:created');
+      expect(matchTopic(regex, 'events:order:created')).toBe(true);
+      expect(matchTopic(regex, 'events:order:updated')).toBe(false);
+    });
+
+    it('matches real-world on_event patterns', () => {
+      // Pattern from PWE on_event: "*:*:#vote:instance.completed"
+      const regex = compilePattern('*:*:#vote:instance.completed');
+      expect(matchTopic(regex, 'workflow:def1:#vote:instance.completed')).toBe(true);
+      expect(matchTopic(regex, 'x:y:#vote:instance.completed')).toBe(true);
+      expect(matchTopic(regex, 'x:y:#vote:instance.failed')).toBe(false);
+    });
+  });
+});
+
+describe('EventBus', () => {
+  let bus: EventBus;
+
+  beforeEach(() => {
+    clearPatternCache();
+    bus = new EventBus();
+  });
+
+  describe('subscribe/publish', () => {
+    it('delivers events to matching subscribers', async () => {
+      const handler = vi.fn();
+      bus.subscribe('test:event', handler);
+
+      await bus.publish('test:event', { data: 1 });
+      expect(handler).toHaveBeenCalledWith({ topic: 'test:event', payload: { data: 1 } });
+    });
+
+    it('does not deliver to non-matching subscribers', async () => {
+      const handler = vi.fn();
+      bus.subscribe('other:event', handler);
+
+      await bus.publish('test:event', { data: 1 });
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('delivers to multiple matching subscribers', async () => {
+      const h1 = vi.fn();
+      const h2 = vi.fn();
+      bus.subscribe('test:event', h1);
+      bus.subscribe('test:event', h2);
+
+      await bus.publish('test:event');
+      expect(h1).toHaveBeenCalledOnce();
+      expect(h2).toHaveBeenCalledOnce();
+    });
+
+    it('supports wildcard subscriptions', async () => {
+      const handler = vi.fn();
+      bus.subscribe('test:*', handler);
+
+      await bus.publish('test:event1');
+      await bus.publish('test:event2');
+      expect(handler).toHaveBeenCalledTimes(2);
+    });
+
+    it('supports double-wildcard subscriptions', async () => {
+      const handler = vi.fn();
+      bus.subscribe('**', handler);
+
+      await bus.publish('any:topic:here');
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('defaults payload to empty object', async () => {
+      const handler = vi.fn();
+      bus.subscribe('test', handler);
+
+      await bus.publish('test');
+      expect(handler).toHaveBeenCalledWith({ topic: 'test', payload: {} });
+    });
+  });
+
+  describe('unsubscribe', () => {
+    it('removes subscription when unsubscribe is called', async () => {
+      const handler = vi.fn();
+      const unsub = bus.subscribe('test:event', handler);
+
+      unsub();
+      await bus.publish('test:event');
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('only removes the specific subscription', async () => {
+      const h1 = vi.fn();
+      const h2 = vi.fn();
+      const unsub1 = bus.subscribe('test:event', h1);
+      bus.subscribe('test:event', h2);
+
+      unsub1();
+      await bus.publish('test:event');
+      expect(h1).not.toHaveBeenCalled();
+      expect(h2).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('error handling', () => {
+    it('catches and logs handler errors without propagating', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const good = vi.fn();
+      bus.subscribe('test', () => { throw new Error('boom'); });
+      bus.subscribe('test', good);
+
+      await bus.publish('test');
+      expect(good).toHaveBeenCalledOnce();
+      expect(warn).toHaveBeenCalled();
+      warn.mockRestore();
+    });
+  });
+
+  describe('emit (fire-and-forget)', () => {
+    it('publishes without awaiting', () => {
+      const handler = vi.fn();
+      bus.subscribe('test', handler);
+
+      bus.emit('test', { x: 1 });
+      // Handler may or may not have been called yet (async)
+      // Just verify it doesn't throw
+    });
+  });
+
+  describe('size and clear', () => {
+    it('tracks subscription count', () => {
+      expect(bus.size).toBe(0);
+      bus.subscribe('a', () => {});
+      bus.subscribe('b', () => {});
+      expect(bus.size).toBe(2);
+    });
+
+    it('clears all subscriptions', () => {
+      bus.subscribe('a', () => {});
+      bus.subscribe('b', () => {});
+      bus.clear();
+      expect(bus.size).toBe(0);
+    });
+  });
+});

package/src/__tests__/expression.test.ts

@@ -0,0 +1,296 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  createEvaluator,
+  CORE_FUNCTIONS,
+  buildFunctionMap,
+  WEB_FAILURE_POLICIES,
+  clearExpressionCache,
+} from '../expression';
+import type { Evaluator, ExpressionContext } from '../expression';
+
+describe('Expression Engine', () => {
+  let evaluator: Evaluator;
+  let ctx: ExpressionContext;
+
+  beforeEach(() => {
+    clearExpressionCache();
+    evaluator = createEvaluator({
+      functions: [],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+    ctx = {
+      state_data: { title: 'Test', count: 5, name: 'Alice', items: [1, 2, 3] },
+      memory: { visited: true },
+      current_state: 'active',
+      status: 'ACTIVE',
+      title: 'Test',
+      count: 5,
+      name: 'Alice',
+      items: [1, 2, 3],
+    };
+  });
+
+  describe('Literals', () => {
+    it('evaluates numeric literals', () => {
+      expect(evaluator.evaluate('42', ctx).value).toBe(42);
+      expect(evaluator.evaluate('3.14', ctx).value).toBe(3.14);
+      expect(evaluator.evaluate('0', ctx).value).toBe(0);
+    });
+
+    it('evaluates boolean literals', () => {
+      expect(evaluator.evaluate('true', ctx).value).toBe(true);
+      expect(evaluator.evaluate('false', ctx).value).toBe(false);
+    });
+
+    it('evaluates null/undefined', () => {
+      expect(evaluator.evaluate('null', ctx).value).toBe(null);
+      expect(evaluator.evaluate('undefined', ctx).value).toBe(undefined);
+    });
+
+    it('evaluates string literals', () => {
+      expect(evaluator.evaluate("'hello'", ctx).value).toBe('hello');
+      expect(evaluator.evaluate('"world"', ctx).value).toBe('world');
+    });
+  });
+
+  describe('Path Resolution', () => {
+    it('resolves direct field access', () => {
+      expect(evaluator.evaluate('title', ctx).value).toBe('Test');
+      expect(evaluator.evaluate('count', ctx).value).toBe(5);
+    });
+
+    it('resolves nested paths', () => {
+      expect(evaluator.evaluate('state_data.title', ctx).value).toBe('Test');
+      expect(evaluator.evaluate('memory.visited', ctx).value).toBe(true);
+    });
+
+    it('returns undefined for missing paths', () => {
+      expect(evaluator.evaluate('nonexistent', ctx).value).toBeUndefined();
+    });
+
+    it('resolves current_state and status', () => {
+      expect(evaluator.evaluate('current_state', ctx).value).toBe('active');
+      expect(evaluator.evaluate('status', ctx).value).toBe('ACTIVE');
+    });
+  });
+
+  describe('Math Functions', () => {
+    it('add', () => {
+      expect(evaluator.evaluate('add(2, 3)', ctx).value).toBe(5);
+      expect(evaluator.evaluate('add(count, 10)', ctx).value).toBe(15);
+    });
+
+    it('subtract', () => {
+      expect(evaluator.evaluate('subtract(10, 3)', ctx).value).toBe(7);
+    });
+
+    it('multiply', () => {
+      expect(evaluator.evaluate('multiply(4, 5)', ctx).value).toBe(20);
+    });
+
+    it('divide', () => {
+      expect(evaluator.evaluate('divide(10, 2)', ctx).value).toBe(5);
+      expect(evaluator.evaluate('divide(10, 0)', ctx).value).toBe(0); // safe divide by zero
+    });
+
+    it('abs', () => {
+      expect(evaluator.evaluate('abs(-5)', ctx).value).toBe(5);
+    });
+
+    it('round', () => {
+      expect(evaluator.evaluate('round(3.7)', ctx).value).toBe(4);
+      expect(evaluator.evaluate('round(3.456, 2)', ctx).value).toBe(3.46);
+    });
+
+    it('min/max', () => {
+      expect(evaluator.evaluate('min(1, 2, 3)', ctx).value).toBe(1);
+      expect(evaluator.evaluate('max(1, 2, 3)', ctx).value).toBe(3);
+    });
+  });
+
+  describe('Comparison Functions', () => {
+    it('eq/neq', () => {
+      expect(evaluator.evaluate('eq(count, 5)', ctx).value).toBe(true);
+      expect(evaluator.evaluate('neq(count, 3)', ctx).value).toBe(true);
+    });
+
+    it('gt/gte/lt/lte', () => {
+      expect(evaluator.evaluate('gt(count, 3)', ctx).value).toBe(true);
+      expect(evaluator.evaluate('gte(count, 5)', ctx).value).toBe(true);
+      expect(evaluator.evaluate('lt(count, 10)', ctx).value).toBe(true);
+      expect(evaluator.evaluate('lte(count, 5)', ctx).value).toBe(true);
+    });
+  });
+
+  describe('Logic Functions', () => {
+    it('if', () => {
+      expect(evaluator.evaluate("if(eq(count, 5), 'yes', 'no')", ctx).value).toBe('yes');
+      expect(evaluator.evaluate("if(eq(count, 3), 'yes', 'no')", ctx).value).toBe('no');
+    });
+
+    it('and/or/not', () => {
+      expect(evaluator.evaluate('and(true, true)', ctx).value).toBe(true);
+      expect(evaluator.evaluate('and(true, false)', ctx).value).toBe(false);
+      expect(evaluator.evaluate('or(false, true)', ctx).value).toBe(true);
+      expect(evaluator.evaluate('not(false)', ctx).value).toBe(true);
+    });
+
+    it('coalesce', () => {
+      expect(evaluator.evaluate('coalesce(null, undefined, 42)', ctx).value).toBe(42);
+      expect(evaluator.evaluate("coalesce('first', 'second')", ctx).value).toBe('first');
+    });
+  });
+
+  describe('String Functions', () => {
+    it('concat', () => {
+      expect(evaluator.evaluate("concat('Hello', ' ', 'World')", ctx).value).toBe('Hello World');
+    });
+
+    it('upper/lower', () => {
+      expect(evaluator.evaluate("upper('hello')", ctx).value).toBe('HELLO');
+      expect(evaluator.evaluate("lower('HELLO')", ctx).value).toBe('hello');
+    });
+
+    it('trim', () => {
+      expect(evaluator.evaluate("trim('  hello  ')", ctx).value).toBe('hello');
+    });
+
+    it('length', () => {
+      expect(evaluator.evaluate("length('hello')", ctx).value).toBe(5);
+      expect(evaluator.evaluate('length(items)', ctx).value).toBe(3);
+    });
+  });
+
+  describe('Path Functions', () => {
+    it('get', () => {
+      expect(evaluator.evaluate("get(state_data, 'title')", ctx).value).toBe('Test');
+    });
+
+    it('includes', () => {
+      expect(evaluator.evaluate("includes('hello world', 'world')", ctx).value).toBe(true);
+    });
+
+    it('is_defined', () => {
+      expect(evaluator.evaluate('is_defined(title)', ctx).value).toBe(true);
+      // Nonexistent vars in with() throw ReferenceError → fallback
+      // Use is_defined with a path that resolves to null/undefined instead
+      expect(evaluator.evaluate('is_defined(null)', ctx).value).toBe(false);
+      expect(evaluator.evaluate('is_defined(state_data.missing)', ctx).value).toBe(false);
+    });
+  });
+
+  describe('Type Functions', () => {
+    it('is_empty', () => {
+      expect(evaluator.evaluate("is_empty('')", ctx).value).toBe(true);
+      expect(evaluator.evaluate('is_empty(null)', ctx).value).toBe(true);
+      expect(evaluator.evaluate("is_empty('hello')", ctx).value).toBe(false);
+    });
+
+    it('is_null', () => {
+      expect(evaluator.evaluate('is_null(null)', ctx).value).toBe(true);
+      expect(evaluator.evaluate('is_null(title)', ctx).value).toBe(false);
+    });
+
+    it('to_string', () => {
+      expect(evaluator.evaluate('to_string(42)', ctx).value).toBe('42');
+      expect(evaluator.evaluate('to_string(null)', ctx).value).toBe('');
+    });
+  });
+
+  describe('Template Interpolation', () => {
+    it('interpolates expressions in templates', () => {
+      const result = evaluator.evaluateTemplate('Hello {{name}}, you have {{count}} items', ctx);
+      expect(result.value).toBe('Hello Alice, you have 5 items');
+    });
+
+    it('returns plain strings unchanged', () => {
+      const result = evaluator.evaluateTemplate('no interpolation here', ctx);
+      expect(result.value).toBe('no interpolation here');
+    });
+
+    it('handles missing values as empty string', () => {
+      const result = evaluator.evaluateTemplate('Value: {{nonexistent}}', ctx);
+      expect(result.value).toBe('Value: ');
+    });
+  });
+
+  describe('Complex Expressions', () => {
+    it('evaluates operator expressions', () => {
+      expect(evaluator.evaluate('count > 3', ctx).value).toBe(true);
+      expect(evaluator.evaluate('count == 5', ctx).value).toBe(true);
+      expect(evaluator.evaluate('count != 10', ctx).value).toBe(true);
+    });
+
+    it('evaluates ternary expressions', () => {
+      const result = evaluator.evaluate("count > 3 ? 'many' : 'few'", ctx);
+      expect(result.value).toBe('many');
+    });
+
+    it('evaluates nested function calls', () => {
+      const result = evaluator.evaluate('add(multiply(2, 3), 4)', ctx);
+      expect(result.value).toBe(10);
+    });
+  });
+
+  describe('Validation', () => {
+    it('rejects invalid syntax', () => {
+      const result = evaluator.validate('add(1, ');
+      expect(result.valid).toBe(false);
+    });
+
+    it('accepts valid expressions', () => {
+      const result = evaluator.validate('add(1, 2)');
+      expect(result.valid).toBe(true);
+    });
+
+    it('unknown functions are valid syntax (just return undefined)', () => {
+      const result = evaluator.validate('eval("bad")');
+      expect(result.valid).toBe(true);
+      // eval is not in fnMap, so it safely returns undefined
+      const evalResult = evaluator.evaluate('eval("test")', ctx);
+      expect(evalResult.status).toBe('ok');
+      expect(evalResult.value).toBeUndefined();
+    });
+  });
+
+  describe('Failure Policy', () => {
+    it('VIEW_BINDING returns empty string fallback on syntax error', () => {
+      const viewEvaluator = createEvaluator({
+        functions: [],
+        failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+      });
+      const result = viewEvaluator.evaluate('add(1, ', ctx);
+      expect(result.status).toBe('fallback');
+      expect(result.value).toBe('');
+    });
+
+    it('CONDITIONAL_VISIBILITY returns true fallback on syntax error', () => {
+      const visEvaluator = createEvaluator({
+        functions: [],
+        failurePolicy: WEB_FAILURE_POLICIES.CONDITIONAL_VISIBILITY,
+      });
+      const result = visEvaluator.evaluate('add(1, ', ctx);
+      expect(result.status).toBe('fallback');
+      expect(result.value).toBe(true);
+    });
+  });
+
+  describe('Custom Functions', () => {
+    it('registers and uses custom functions', () => {
+      const custom = createEvaluator({
+        functions: [{ name: 'double', fn: (x: unknown) => Number(x) * 2, arity: 1 }],
+        failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+      });
+      expect(custom.evaluate('double(21)', ctx).value).toBe(42);
+    });
+  });
+
+  describe('buildFunctionMap', () => {
+    it('builds map from function array', () => {
+      const map = buildFunctionMap(CORE_FUNCTIONS);
+      expect(map.size).toBe(31);
+      expect(map.has('add')).toBe(true);
+      expect(map.has('eq')).toBe(true);
+    });
+  });
+});

package/src/__tests__/failure-policies.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createEvaluator, WEB_FAILURE_POLICIES, clearExpressionCache } from '../expression';
+import type { ExpressionContext } from '../expression';
+
+describe('Web Failure Policies', () => {
+  beforeEach(() => {
+    clearExpressionCache();
+  });
+
+  const ctx: ExpressionContext = {
+    state_data: { title: 'Test' },
+    memory: {},
+    current_state: 'active',
+    status: 'ACTIVE',
+    title: 'Test',
+  };
+
+  describe('VIEW_BINDING', () => {
+    it('returns empty string fallback on missing path', () => {
+      const evaluator = createEvaluator({
+        functions: [],
+        failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+      });
+      // This triggers a parse error (incomplete expression)
+      const result = evaluator.evaluate('add(1,', ctx);
+      expect(result.value).toBe('');
+      expect(result.status).toBe('fallback');
+    });
+
+    it('logs at warn level', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const evaluator = createEvaluator({
+        functions: [],
+        failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+      });
+      evaluator.evaluate('add(1,', ctx);
+      expect(warn).toHaveBeenCalled();
+      warn.mockRestore();
+    });
+  });
+
+  describe('EVENT_REACTION', () => {
+    it('logs diagnostic and continues on error', () => {
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const evaluator = createEvaluator({
+        functions: [],
+        failurePolicy: WEB_FAILURE_POLICIES.EVENT_REACTION,
+      });
+      const result = evaluator.evaluate('add(1,', ctx);
+      expect(result.status).toBe('error');
+      expect(result.value).toBeUndefined();
+      expect(result.error).toBeDefined();
+      expect(error).toHaveBeenCalled();
+      error.mockRestore();
+    });
+
+    it('returns undefined fallback value', () => {
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const evaluator = createEvaluator({
+        functions: [],
+        failurePolicy: WEB_FAILURE_POLICIES.EVENT_REACTION,
+      });
+      const result = evaluator.evaluate('add(1,', ctx);
+      expect(result.value).toBeUndefined();
+      error.mockRestore();
+    });
+  });
+
+  describe('DURING_ACTION', () => {
+    it('logs and skips on error', () => {
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const evaluator = createEvaluator({
+        functions: [],
+        failurePolicy: WEB_FAILURE_POLICIES.DURING_ACTION,
+      });
+      const result = evaluator.evaluate('add(1,', ctx);
+      expect(result.status).toBe('error');
+      expect(result.value).toBeUndefined();
+      error.mockRestore();
+    });
+  });
+
+  describe('CONDITIONAL_VISIBILITY', () => {
+    it('returns true on expression error (show, do not hide)', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const evaluator = createEvaluator({
+        functions: [],
+        failurePolicy: WEB_FAILURE_POLICIES.CONDITIONAL_VISIBILITY,
+      });
+      const result = evaluator.evaluate('add(1,', ctx);
+      expect(result.value).toBe(true);
+      expect(result.status).toBe('fallback');
+      warn.mockRestore();
+    });
+
+    it('logs at warn level, not error', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const evaluator = createEvaluator({
+        functions: [],
+        failurePolicy: WEB_FAILURE_POLICIES.CONDITIONAL_VISIBILITY,
+      });
+      evaluator.evaluate('add(1,', ctx);
+      expect(warn).toHaveBeenCalled();
+      expect(error).not.toHaveBeenCalled();
+      warn.mockRestore();
+      error.mockRestore();
+    });
+  });
+});