@smoothbricks/lmao 0.1.0

package/src/lib/schema/__tests__/featureFlags.test.ts

@@ -0,0 +1,443 @@
+import { describe, expect, test } from 'bun:test';
+// Must import test-helpers first to initialize timestamp implementation
+import '../../__tests__/test-helpers.js';
+import { createTestTracerOptions } from '../../__tests__/test-helpers.js';
+import { defineOpContext } from '../../defineOpContext.js';
+import { TestTracer } from '../../tracers/TestTracer.js';
+import type { AnySpanBuffer } from '../../types.js';
+import { S } from '../builder.js';
+import { defineFeatureFlags } from '../defineFeatureFlags.js';
+import { defineLogSchema } from '../defineLogSchema.js';
+import { InMemoryFlagEvaluator } from '../evaluator.js';
+import { ENTRY_TYPE_FF_ACCESS, ENTRY_TYPE_FF_USAGE } from '../systemSchema.js';
+
+/**
+ * Helper to count entries of a specific type in the buffer
+ */
+function countEntryType(buffer: AnySpanBuffer, entryType: number): number {
+  let count = 0;
+  let current: AnySpanBuffer | undefined = buffer;
+  while (current) {
+    const writeIndex = current._writeIndex;
+    for (let i = 0; i < writeIndex; i++) {
+      if (current.entry_type[i] === entryType) {
+        count++;
+      }
+    }
+    current = current._overflow;
+  }
+  return count;
+}
+
+describe('Feature Flags', () => {
+  // Define a minimal log schema for tests
+  const testLogSchema = defineLogSchema({});
+
+  test('defines feature flags with sync/async markers', () => {
+    const flags = defineFeatureFlags({
+      debugMode: S.boolean().default(false).sync(),
+      maxRetries: S.number().default(3).sync(),
+      userSpecificLimit: S.number().default(100).async(),
+    });
+
+    expect(flags.schema).toBeDefined();
+    expect(flags.syncFlags).toContain('debugMode');
+    expect(flags.syncFlags).toContain('maxRetries');
+    expect(flags.asyncFlags).toContain('userSpecificLimit');
+  });
+
+  test('evaluator returns FlagContext for truthy flags', async () => {
+    const flags = defineFeatureFlags({
+      debugMode: S.boolean().default(false).sync(),
+      maxRetries: S.number().default(3).sync(),
+    });
+
+    const ctx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const flagEvaluator = new InMemoryFlagEvaluator(flags.schema, {
+      debugMode: true,
+      maxRetries: 5,
+    });
+
+    const { trace } = new TestTracer(ctx, { ...createTestTracerOptions(), flagEvaluator });
+    const result = await trace('test-span', async (ctx) => {
+      const ff = ctx.ff;
+
+      expect(ff.debugMode).toBeDefined();
+      expect(ff.debugMode?.value).toBe(true);
+      expect(typeof ff.debugMode?.track).toBe('function');
+
+      expect(ff.maxRetries).toBeDefined();
+      expect(ff.maxRetries?.value).toBe(5);
+      expect(typeof ff.maxRetries?.track).toBe('function');
+
+      return ctx.ok(null);
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test('feature-flag runtime stays worker-safe', async () => {
+    const flags = defineFeatureFlags({
+      debugMode: S.boolean().default(false).sync(),
+    });
+
+    const ctx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const flagEvaluator = new InMemoryFlagEvaluator(flags.schema, { debugMode: true });
+    const tracer = new TestTracer(ctx, { ...createTestTracerOptions(), flagEvaluator });
+
+    await tracer.trace('worker-safe-evaluator', async (spanCtx) => {
+      expect(spanCtx.ff.debugMode?.value).toBe(true);
+      expect(spanCtx.ff.constructor.toString()).not.toContain('new Function');
+      return spanCtx.ok(null);
+    });
+  });
+
+  test('evaluator returns undefined for falsy flags', async () => {
+    const flags = defineFeatureFlags({
+      debugMode: S.boolean().default(false).sync(),
+      userLimit: S.number().default(100).async(),
+    });
+
+    const ctx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const flagEvaluator = new InMemoryFlagEvaluator(flags.schema, {}); // No flags set → null values
+
+    const { trace } = new TestTracer(ctx, { ...createTestTracerOptions(), flagEvaluator });
+    await trace('test-span', async (ctx) => {
+      const ff = ctx.ff;
+      expect(ff.debugMode).toBeUndefined();
+      return ctx.ok(null);
+    });
+  });
+
+  test('async flags return FlagContext via get method', async () => {
+    const flags = defineFeatureFlags({
+      userSpecificLimit: S.number().default(100).async(),
+      dynamicProvider: S.enum(['stripe', 'paypal']).default('stripe').async(),
+    });
+
+    const ctx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const flagEvaluator = new InMemoryFlagEvaluator(flags.schema, {
+      userSpecificLimit: 200,
+      dynamicProvider: 'paypal',
+    });
+
+    const { trace } = new TestTracer(ctx, { ...createTestTracerOptions(), flagEvaluator });
+    await trace('test-span', async (ctx) => {
+      // Async flags accessed via get() return FlagContext
+      const limit = await ctx.ff.get('userSpecificLimit');
+      expect(limit).toBeDefined();
+      expect(limit?.value).toBe(200);
+
+      const provider = await ctx.ff.get('dynamicProvider');
+      expect(provider).toBeDefined();
+      expect(provider?.value).toBe('paypal');
+
+      return ctx.ok(null);
+    });
+  });
+
+  test('track() on FlagContext logs usage events', async () => {
+    const flags = defineFeatureFlags({
+      advancedValidation: S.boolean().default(false).sync(),
+    });
+
+    const ctx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const flagEvaluator = new InMemoryFlagEvaluator(flags.schema, {
+      advancedValidation: true,
+    });
+
+    const { trace } = new TestTracer(ctx, { ...createTestTracerOptions(), flagEvaluator });
+    await trace('test-span', async (ctx) => {
+      const flag = ctx.ff.advancedValidation;
+
+      // track() returns fluent log entry so additional fields can be tagged
+      flag?.track({ action: 'validation_performed', outcome: 'success' }).ff_value('used').line(123);
+
+      // Check buffer for ff-usage entry
+      const usageCount = countEntryType(ctx.buffer, ENTRY_TYPE_FF_USAGE);
+      expect(usageCount).toBe(1);
+
+      return ctx.ok(null);
+    });
+  });
+
+  test('sync flag access is logged only once per span', async () => {
+    const flags = defineFeatureFlags({
+      debugMode: S.boolean().default(false).sync(),
+    });
+
+    const ctx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const flagEvaluator = new InMemoryFlagEvaluator(flags.schema, { debugMode: true });
+
+    const { trace } = new TestTracer(ctx, { ...createTestTracerOptions(), flagEvaluator });
+    await trace('test-span', async (ctx) => {
+      // Access the flag multiple times
+      const value1 = ctx.ff.debugMode;
+      const value2 = ctx.ff.debugMode;
+      const value3 = ctx.ff.debugMode;
+
+      // All accesses should return same value (flag is truthy)
+      expect(value1?.value).toBe(true);
+      expect(value2?.value).toBe(true);
+      expect(value3?.value).toBe(true);
+
+      // Only ONE ff-access log should be written (deduplication via buffer scan)
+      const accessCount = countEntryType(ctx.buffer, ENTRY_TYPE_FF_ACCESS);
+      expect(accessCount).toBe(1);
+
+      return ctx.ok(null);
+    });
+  });
+
+  test('async flag access is logged', async () => {
+    const flags = defineFeatureFlags({
+      userLimit: S.number().default(100).async(),
+    });
+
+    const ctx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const flagEvaluator = new InMemoryFlagEvaluator(flags.schema, { userLimit: 200 });
+
+    const { trace } = new TestTracer(ctx, { ...createTestTracerOptions(), flagEvaluator });
+    await trace('test-span', async (ctx) => {
+      const value = await ctx.ff.get('userLimit');
+      expect(value?.value).toBe(200);
+
+      // Check buffer for ff-access entry
+      const accessCount = countEntryType(ctx.buffer, ENTRY_TYPE_FF_ACCESS);
+      expect(accessCount).toBe(1);
+
+      return ctx.ok(null);
+    });
+  });
+
+  test('S.enum validates enum values', () => {
+    const schema = defineFeatureFlags({
+      environment: S.enum(['dev', 'staging', 'prod'] as const)
+        .default('dev')
+        .sync(),
+    });
+
+    expect(schema.schema.environment).toBeDefined();
+    expect(schema.schema.environment.defaultValue).toBe('dev');
+    expect(schema.schema.environment.evaluationType).toBe('sync');
+  });
+
+  test('S.enum throws on empty values', () => {
+    expect(() => {
+      S.enum([]);
+    }).toThrow('Enum must have at least one value');
+  });
+
+  test('multiple sync and async flags work together', async () => {
+    const flags = defineFeatureFlags({
+      // Sync flags
+      enableFeatureX: S.boolean().default(false).sync(),
+      maxConnectionPool: S.number().default(10).sync(),
+      logLevel: S.enum(['debug', 'info', 'warn', 'error'] as const)
+        .default('info')
+        .sync(),
+
+      // Async flags
+      userTier: S.category().default('free').async(),
+      customLimit: S.number().default(100).async(),
+    });
+
+    const ctx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const flagEvaluator = new InMemoryFlagEvaluator(flags.schema, {
+      enableFeatureX: true,
+      maxConnectionPool: 20,
+      logLevel: 'debug',
+      userTier: 'premium',
+      customLimit: 500,
+    });
+
+    const { trace } = new TestTracer(ctx, { ...createTestTracerOptions(), flagEvaluator });
+    await trace('test-span', async (ctx) => {
+      // Test sync flags
+      expect(ctx.ff.enableFeatureX?.value).toBe(true);
+      expect(ctx.ff.maxConnectionPool?.value).toBe(20);
+      expect(ctx.ff.logLevel?.value).toBe('debug');
+
+      // Test async flags
+      const userTier = await ctx.ff.get('userTier');
+      expect(userTier?.value).toBe('premium');
+
+      const customLimit = await ctx.ff.get('customLimit');
+      expect(customLimit?.value).toBe(500);
+
+      return ctx.ok(null);
+    });
+  });
+
+  test('InMemoryFlagEvaluator setFlag updates values', async () => {
+    const schema = defineFeatureFlags({
+      testFlag: S.category().default('initial').sync(),
+    });
+    const evaluator = new InMemoryFlagEvaluator(schema.schema, {
+      testFlag: 'initial',
+    });
+
+    // getSync receives ctx as first param (can be empty object for simple evaluator)
+    const { trace } = new TestTracer(
+      defineOpContext({
+        logSchema: testLogSchema,
+        flags: schema.schema,
+      }),
+      { ...createTestTracerOptions(), flagEvaluator: evaluator },
+    );
+    await trace('sync-read-initial', async (ctx) => {
+      expect(evaluator.getSync(ctx, 'testFlag')).toBe('initial');
+      return ctx.ok(null);
+    });
+
+    evaluator.setFlag('testFlag', 'updated');
+
+    await trace('sync-read-updated', async (ctx) => {
+      expect(evaluator.getSync(ctx, 'testFlag')).toBe('updated');
+      return ctx.ok(null);
+    });
+  });
+
+  test('InMemoryFlagEvaluator works with async', async () => {
+    const schema = defineFeatureFlags({
+      asyncFlag: S.number().default(0).async(),
+    });
+    const evaluator = new InMemoryFlagEvaluator(schema.schema, {
+      asyncFlag: 42,
+    });
+
+    const { trace } = new TestTracer(
+      defineOpContext({
+        logSchema: testLogSchema,
+        flags: schema.schema,
+      }),
+      { ...createTestTracerOptions(), flagEvaluator: evaluator },
+    );
+    await trace('async-read', async (ctx) => {
+      expect(await evaluator.getAsync(ctx, 'asyncFlag')).toBe(42);
+      return ctx.ok(null);
+    });
+  });
+
+  test('forContext creates child evaluator bound to child SpanContext', async () => {
+    const flags = defineFeatureFlags({
+      debugMode: S.boolean().default(false).sync(),
+    });
+
+    const ctx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const flagEvaluator = new InMemoryFlagEvaluator(flags.schema, { debugMode: true });
+
+    const { trace } = new TestTracer(ctx, { ...createTestTracerOptions(), flagEvaluator });
+    await trace('parent-span', async (parentCtx) => {
+      // Access flag in parent
+      expect(parentCtx.ff.debugMode?.value).toBe(true);
+
+      const parentAccessCount = countEntryType(parentCtx.buffer, ENTRY_TYPE_FF_ACCESS);
+      expect(parentAccessCount).toBe(1);
+
+      // Create child span - child gets its own ff evaluator via forContext
+      await parentCtx.span('child-span', async (childCtx) => {
+        expect(childCtx.ff.debugMode?.value).toBe(true);
+
+        // Access in child should log to child buffer
+        const childAccessCount = countEntryType(childCtx.buffer, ENTRY_TYPE_FF_ACCESS);
+        expect(childAccessCount).toBe(1);
+
+        return childCtx.ok(null);
+      });
+
+      return parentCtx.ok(null);
+    });
+  });
+
+  test('usage example from spec: undefined/truthy pattern', async () => {
+    const flags = defineFeatureFlags({
+      darkMode: S.boolean().default(false).sync(),
+      advancedSearch: S.boolean().default(false).sync(),
+    });
+
+    // Scenario 1: darkMode is enabled
+    const enabledCtx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const enabledFlagEvaluator = new InMemoryFlagEvaluator(flags.schema, { darkMode: true });
+    const { trace: enabledTrace } = new TestTracer(enabledCtx, {
+      ...createTestTracerOptions(),
+      flagEvaluator: enabledFlagEvaluator,
+    });
+
+    await enabledTrace('test-enabled', async (ctx) => {
+      const darkMode = ctx.ff.darkMode;
+
+      // Truthy check works naturally with undefined/truthy semantics
+      if (darkMode) {
+        expect(darkMode.value).toBe(true);
+        darkMode.track({ action: 'applied' });
+      }
+
+      return ctx.ok(null);
+    });
+
+    // Scenario 2: darkMode is disabled
+    const disabledCtx = defineOpContext({
+      logSchema: testLogSchema,
+      flags: flags.schema,
+    });
+
+    const disabledFlagEvaluator = new InMemoryFlagEvaluator(flags.schema, { darkMode: false });
+    const { trace: disabledTrace } = new TestTracer(disabledCtx, {
+      ...createTestTracerOptions(),
+      flagEvaluator: disabledFlagEvaluator,
+    });
+
+    await disabledTrace('test-disabled', async (ctx) => {
+      const darkModeDisabled = ctx.ff.darkMode;
+
+      // Falsy check works - undefined is falsy
+      expect(darkModeDisabled).toBeUndefined();
+      if (!darkModeDisabled) {
+        expect(true).toBe(true);
+      }
+
+      return ctx.ok(null);
+    });
+  });
+});

package/src/lib/schema/builder.ts

@@ -0,0 +1,201 @@
+/**
+ * Schema builder for lmao - extends arrow-builder's schema builder with feature flags, masking, and binary sugar
+ *
+ * This module re-exports the S object from arrow-builder and adds:
+ * - Feature flag support via .default().sync()/.async() pattern
+ * - Masking transformations for sensitive data
+ * - S.unknown() and S.object<T>() sugar for msgpack-encoded binary columns
+ * - S.binary() passthrough to arrow-builder's S.binary()
+ */
+
+import { encode } from '@msgpack/msgpack';
+import {
+  S as ArrowS,
+  type BinaryEncoder,
+  type LazyBinarySchema,
+  type LazyCategorySchema,
+  type LazyEnumSchema,
+  type LazyTextSchema,
+  type Schema,
+} from '@smoothbricks/arrow-builder';
+import type { FeatureFlagDefinition, FlagBuilderWithDefault, SchemaBuilder, SchemaOrFlagBuilder } from './types.js';
+
+/**
+ * Msgpack encoder singleton -- per-value, synchronous.
+ * Encodes at flush time (cold path), not on the hot write path.
+ * @msgpack/msgpack already handles most types; functions/symbols become undefined (dropped silently).
+ *
+ * Both wrap @msgpack/msgpack's encode(). This encoder is private to the schema builder;
+ */
+const msgpackEncoder: BinaryEncoder = {
+  encode(value: unknown): Uint8Array {
+    return encode(value) as Uint8Array;
+  },
+};
+
+/**
+ * Create a flag builder that wraps a schema object
+ * This allows schemas to be used for both tag attributes and feature flags
+ */
+type SchemaWithFlagBuilder<TSchema extends Schema<Value>, Value> = TSchema & SchemaOrFlagBuilder<Value>;
+
+function createSchemaWithFlagBuilder<Value, TSchema extends Schema<Value>>(
+  schema: TSchema,
+): SchemaWithFlagBuilder<TSchema, Value> {
+  const schemaWithBuilder: SchemaWithFlagBuilder<TSchema, Value> = Object.assign(schema, {
+    default(defaultValue: Value): FlagBuilderWithDefault<Value> {
+      return {
+        sync(): FeatureFlagDefinition<Value, 'sync'> {
+          return {
+            schema,
+            defaultValue,
+            evaluationType: 'sync' as const,
+          };
+        },
+        async(): FeatureFlagDefinition<Value, 'async'> {
+          return {
+            schema,
+            defaultValue,
+            evaluationType: 'async' as const,
+          };
+        },
+      };
+    },
+  });
+
+  return schemaWithBuilder;
+}
+
+/**
+ * Schema builder that wraps arrow-builder's S with feature flag support
+ *
+ * STRING TYPE SYSTEM (See specs/lmao/01a_trace_schema_system.md):
+ * Three distinct string types, each with different storage strategies:
+ * - S.enum(['A', 'B', 'C']) - Known values at compile time (Uint8Array, 1 byte)
+ * - S.category() - Repeated values (raw string storage, dictionary built at Arrow conversion)
+ * - S.text() - Unique values (no dictionary overhead)
+ */
+const schemaBuilderImpl: SchemaBuilder = {
+  /**
+   * Create number schema
+   *
+   * Usage:
+   * - S.number() - any number for tag attributes
+   * - S.number().default(0).sync() - feature flag
+   */
+  number: () => {
+    const schema = ArrowS.number();
+    return createSchemaWithFlagBuilder(schema);
+  },
+
+  /**
+   * Create boolean schema
+   *
+   * Usage:
+   * - S.boolean() - for tag attributes
+   * - S.boolean().default(false).sync() - feature flag
+   */
+  boolean: () => {
+    const schema = ArrowS.boolean();
+    return createSchemaWithFlagBuilder(schema);
+  },
+
+  /**
+   * Wrap schema to make it optional
+   *
+   * Usage:
+   * - SchemaBuilder.optional(SchemaBuilder.string()) - string | undefined
+   */
+  optional: <T>(schema: Schema<T>): Schema<T | undefined, T | undefined> => {
+    return ArrowS.optional(schema);
+  },
+
+  /**
+   * Create union of multiple schemas
+   *
+   * Usage:
+   * - SchemaBuilder.union([SchemaBuilder.string(), SchemaBuilder.number()]) - string | number
+   */
+  union: <T extends readonly [Schema, ...Schema[]]>(schemas: T) => {
+    return ArrowS.union(schemas);
+  },
+
+  /**
+   * Enum - Known values at compile time
+   *
+   * Storage: Uint8Array (1 byte) with compile-time mapping
+   * Arrow: Dictionary with pre-defined values (UTF-8 pre-computed at definition time)
+   * Use for: Operations, HTTP methods, entry types, status enums
+   *
+   * Usage:
+   * - S.enum(['CREATE', 'READ', 'UPDATE', 'DELETE']) - for tag attributes
+   * - S.enum(['dev', 'staging', 'prod']).default('dev').sync() - feature flag
+   */
+  enum: <T extends readonly string[]>(values: T): SchemaOrFlagBuilder<T[number]> & LazyEnumSchema<T[number]> => {
+    const schema = ArrowS.enum(values);
+    return createSchemaWithFlagBuilder(schema);
+  },
+
+  /**
+   * Category - Values that often repeat (limited cardinality)
+   *
+   * Storage: Raw strings (no hot-path interning)
+   * Arrow: Dictionary built dynamically from values at Arrow conversion
+   * Use for: userIds, sessionIds, moduleNames, spanNames, table names
+   */
+  category: (): SchemaOrFlagBuilder<string> & LazyCategorySchema => {
+    const schema = ArrowS.category();
+    return createSchemaWithFlagBuilder(schema);
+  },
+
+  /**
+   * Text - Unique values that rarely repeat
+   *
+   * Storage: Raw strings without interning
+   * Arrow: Plain string column (no dictionary overhead)
+   * Use for: Unique error messages, URLs, request bodies, masked queries
+   */
+  text: (): SchemaOrFlagBuilder<string> & LazyTextSchema => {
+    const schema = ArrowS.text();
+    return createSchemaWithFlagBuilder(schema);
+  },
+
+  /**
+   * Binary - Raw bytes or encoder-wrapped values
+   *
+   * Passthrough to arrow-builder's S.binary().
+   * Without encoder: accepts Uint8Array (raw binary).
+   * With encoder: accepts any value T (encoded to bytes at flush time).
+   */
+  binary: ((options?: { encoder: BinaryEncoder }): LazyBinarySchema => {
+    if (options?.encoder) {
+      return ArrowS.binary(options);
+    }
+    return ArrowS.binary();
+  }) as SchemaBuilder['binary'],
+
+  /**
+   * Unknown - accepts any value, msgpack-encoded at flush time
+   *
+   * Sugar for S.binary({ encoder: msgpackEncoder }).
+   * Use for: arbitrary objects, request bodies, error context, unknown-shape data.
+   * Hot path stores frozen object reference; flush path encodes via @msgpack/msgpack.
+   */
+  unknown: (): LazyBinarySchema<unknown> => {
+    return ArrowS.binary({ encoder: msgpackEncoder });
+  },
+
+  /**
+   * Object<T> - typed variant of unknown, same underlying binary storage with msgpack encoding
+   *
+   * TypeScript enforces shape at compile time; no runtime validation on hot path.
+   * Sugar for S.binary<T>({ encoder: msgpackEncoder }).
+   */
+  object: <T extends object>(): LazyBinarySchema<T> => {
+    return ArrowS.binary<T>({ encoder: msgpackEncoder });
+  },
+};
+
+// Export as S for convenience
+// Note: The SchemaBuilder type is exported from types.ts
+export const S = schemaBuilderImpl;