trickle-observe 0.1.0

package/src/type-inference.ts

@@ -0,0 +1,285 @@
+import { TypeNode } from './types';
+
+const MAX_ARRAY_SAMPLE = 20;
+const DEFAULT_MAX_DEPTH = 5;
+
+/**
+ * Infer the TypeNode representation of a runtime JavaScript value.
+ * Uses a WeakSet to detect circular references.
+ * Samples at most the first 20 elements of arrays for performance.
+ */
+export function inferType(value: unknown, maxDepth: number = DEFAULT_MAX_DEPTH): TypeNode {
+  const seen = new WeakSet();
+  return infer(value, maxDepth, seen);
+}
+
+function infer(value: unknown, depth: number, seen: WeakSet<object>): TypeNode {
+  // Null
+  if (value === null) {
+    return { kind: 'primitive', name: 'null' };
+  }
+
+  // Undefined
+  if (value === undefined) {
+    return { kind: 'primitive', name: 'undefined' };
+  }
+
+  const t = typeof value;
+
+  // Primitives
+  if (t === 'string') return { kind: 'primitive', name: 'string' };
+  if (t === 'number') return { kind: 'primitive', name: 'number' };
+  if (t === 'boolean') return { kind: 'primitive', name: 'boolean' };
+  if (t === 'bigint') return { kind: 'primitive', name: 'bigint' };
+  if (t === 'symbol') return { kind: 'primitive', name: 'symbol' };
+
+  // Functions
+  if (t === 'function') {
+    return {
+      kind: 'function',
+      params: new Array((value as Function).length).fill({ kind: 'unknown' } as TypeNode),
+      returnType: { kind: 'unknown' },
+    };
+  }
+
+  // Object types — check depth and circular refs
+  if (t === 'object') {
+    const obj = value as object;
+
+    // Circular reference detection
+    if (seen.has(obj)) {
+      return { kind: 'unknown' };
+    }
+
+    if (depth <= 0) {
+      return { kind: 'unknown' };
+    }
+
+    seen.add(obj);
+
+    try {
+      return inferObject(obj, depth, seen);
+    } finally {
+      // Don't remove from seen — keeps circular detection intact for the full traversal
+    }
+  }
+
+  return { kind: 'unknown' };
+}
+
+function inferObject(obj: object, depth: number, seen: WeakSet<object>): TypeNode {
+  // Promise
+  if (obj instanceof Promise) {
+    return { kind: 'promise', resolved: { kind: 'unknown' } };
+  }
+
+  // Map
+  if (obj instanceof Map) {
+    let keyType: TypeNode = { kind: 'unknown' };
+    let valType: TypeNode = { kind: 'unknown' };
+    let count = 0;
+    const keyTypes: TypeNode[] = [];
+    const valTypes: TypeNode[] = [];
+
+    for (const [k, v] of obj) {
+      if (count >= MAX_ARRAY_SAMPLE) break;
+      keyTypes.push(infer(k, depth - 1, seen));
+      valTypes.push(infer(v, depth - 1, seen));
+      count++;
+    }
+
+    keyType = unifyTypes(keyTypes);
+    valType = unifyTypes(valTypes);
+
+    return { kind: 'map', key: keyType, value: valType };
+  }
+
+  // Set
+  if (obj instanceof Set) {
+    const elementTypes: TypeNode[] = [];
+    let count = 0;
+    for (const item of obj) {
+      if (count >= MAX_ARRAY_SAMPLE) break;
+      elementTypes.push(infer(item, depth - 1, seen));
+      count++;
+    }
+    return { kind: 'set', element: unifyTypes(elementTypes) };
+  }
+
+  // Array (including TypedArrays)
+  if (Array.isArray(obj)) {
+    return inferArray(obj, depth, seen);
+  }
+
+  // TypedArrays (not real arrays)
+  if (ArrayBuffer.isView(obj) && !(obj instanceof DataView)) {
+    return {
+      kind: 'object',
+      properties: {
+        __typedArray: { kind: 'primitive', name: 'string' },
+        length: { kind: 'primitive', name: 'number' },
+      },
+    };
+  }
+
+  // Buffer (Node.js)
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(obj)) {
+    return {
+      kind: 'object',
+      properties: {
+        __buffer: { kind: 'primitive', name: 'string' },
+        length: { kind: 'primitive', name: 'number' },
+      },
+    };
+  }
+
+  // Date
+  if (obj instanceof Date) {
+    return {
+      kind: 'object',
+      properties: {
+        __date: { kind: 'primitive', name: 'string' },
+      },
+    };
+  }
+
+  // RegExp
+  if (obj instanceof RegExp) {
+    return {
+      kind: 'object',
+      properties: {
+        __regexp: { kind: 'primitive', name: 'string' },
+        source: { kind: 'primitive', name: 'string' },
+        flags: { kind: 'primitive', name: 'string' },
+      },
+    };
+  }
+
+  // Error
+  if (obj instanceof Error) {
+    return {
+      kind: 'object',
+      properties: {
+        __error: { kind: 'primitive', name: 'string' },
+        name: { kind: 'primitive', name: 'string' },
+        message: { kind: 'primitive', name: 'string' },
+        stack: { kind: 'primitive', name: 'string' },
+      },
+    };
+  }
+
+  // Plain objects
+  return inferPlainObject(obj, depth, seen);
+}
+
+function inferArray(arr: unknown[], depth: number, seen: WeakSet<object>): TypeNode {
+  if (arr.length === 0) {
+    return { kind: 'array', element: { kind: 'unknown' } };
+  }
+
+  const sampleSize = Math.min(arr.length, MAX_ARRAY_SAMPLE);
+  const elementTypes: TypeNode[] = [];
+
+  for (let i = 0; i < sampleSize; i++) {
+    elementTypes.push(infer(arr[i], depth - 1, seen));
+  }
+
+  return { kind: 'array', element: unifyTypes(elementTypes) };
+}
+
+function inferPlainObject(obj: object, depth: number, seen: WeakSet<object>): TypeNode {
+  const properties: Record<string, TypeNode> = {};
+  const keys = Object.keys(obj);
+
+  for (const key of keys) {
+    try {
+      properties[key] = infer((obj as Record<string, unknown>)[key], depth - 1, seen);
+    } catch {
+      properties[key] = { kind: 'unknown' };
+    }
+  }
+
+  return { kind: 'object', properties };
+}
+
+/**
+ * Unify an array of TypeNodes into a single TypeNode.
+ * If all types are structurally identical, returns that type.
+ * Otherwise, returns a union of the distinct types.
+ */
+function unifyTypes(types: TypeNode[]): TypeNode {
+  if (types.length === 0) return { kind: 'unknown' };
+  if (types.length === 1) return types[0];
+
+  // Deduplicate by serialization
+  const uniqueMap = new Map<string, TypeNode>();
+  for (const t of types) {
+    const key = canonicalStringify(t);
+    if (!uniqueMap.has(key)) {
+      uniqueMap.set(key, t);
+    }
+  }
+
+  const unique = Array.from(uniqueMap.values());
+  if (unique.length === 1) return unique[0];
+
+  // Flatten nested unions
+  const members: TypeNode[] = [];
+  for (const u of unique) {
+    if (u.kind === 'union') {
+      members.push(...u.members);
+    } else {
+      members.push(u);
+    }
+  }
+
+  // Deduplicate again after flattening
+  const finalMap = new Map<string, TypeNode>();
+  for (const m of members) {
+    const key = canonicalStringify(m);
+    if (!finalMap.has(key)) {
+      finalMap.set(key, m);
+    }
+  }
+
+  const finalMembers = Array.from(finalMap.values());
+  if (finalMembers.length === 1) return finalMembers[0];
+
+  return { kind: 'union', members: finalMembers };
+}
+
+function canonicalStringify(node: TypeNode): string {
+  if (node.kind === 'object') {
+    const sorted = Object.keys(node.properties).sort();
+    const entries = sorted.map(k => `${JSON.stringify(k)}:${canonicalStringify(node.properties[k])}`);
+    return `{object:{${entries.join(',')}}}`;
+  }
+  if (node.kind === 'union') {
+    const sorted = node.members.map(canonicalStringify).sort();
+    return `{union:[${sorted.join(',')}]}`;
+  }
+  if (node.kind === 'array') {
+    return `{array:${canonicalStringify(node.element)}}`;
+  }
+  if (node.kind === 'primitive') {
+    return `{prim:${node.name}}`;
+  }
+  if (node.kind === 'function') {
+    return `{fn:[${node.params.map(canonicalStringify).join(',')}]->${canonicalStringify(node.returnType)}}`;
+  }
+  if (node.kind === 'promise') {
+    return `{promise:${canonicalStringify(node.resolved)}}`;
+  }
+  if (node.kind === 'map') {
+    return `{map:${canonicalStringify(node.key)},${canonicalStringify(node.value)}}`;
+  }
+  if (node.kind === 'set') {
+    return `{set:${canonicalStringify(node.element)}}`;
+  }
+  if (node.kind === 'tuple') {
+    return `{tuple:[${node.elements.map(canonicalStringify).join(',')}]}`;
+  }
+  return '{unknown}';
+}
+
+export { unifyTypes };

package/src/types.ts

@@ -0,0 +1,61 @@
+export type TypeNode =
+  | { kind: "primitive"; name: "string" | "number" | "boolean" | "null" | "undefined" | "bigint" | "symbol" }
+  | { kind: "array"; element: TypeNode }
+  | { kind: "object"; properties: Record<string, TypeNode> }
+  | { kind: "union"; members: TypeNode[] }
+  | { kind: "function"; params: TypeNode[]; returnType: TypeNode }
+  | { kind: "promise"; resolved: TypeNode }
+  | { kind: "map"; key: TypeNode; value: TypeNode }
+  | { kind: "set"; element: TypeNode }
+  | { kind: "tuple"; elements: TypeNode[] }
+  | { kind: "unknown" };
+
+export interface IngestPayload {
+  functionName: string;
+  module: string;
+  language: "js" | "python";
+  environment: string;
+  typeHash: string;
+  argsType: TypeNode;
+  returnType: TypeNode;
+  isAsync?: boolean;
+  paramNames?: string[];
+  sampleInput?: unknown;
+  sampleOutput?: unknown;
+  error?: {
+    type: string;
+    message: string;
+    stackTrace?: string;
+    argsSnapshot?: unknown;
+  };
+}
+
+export interface GlobalOpts {
+  backendUrl: string;
+  batchIntervalMs: number;
+  enabled: boolean;
+  environment: string | undefined;
+  maxBatchSize?: number;
+  debug?: boolean;
+}
+
+export interface TrickleOpts {
+  name?: string;
+  module?: string;
+  trackArgs?: boolean;
+  trackReturn?: boolean;
+  sampleRate?: number;
+  maxDepth?: number;
+}
+
+export interface WrapOptions {
+  functionName: string;
+  module: string;
+  trackArgs: boolean;
+  trackReturn: boolean;
+  sampleRate: number;
+  maxDepth: number;
+  environment: string;
+  enabled: boolean;
+  paramNames?: string[];
+}

package/src/wrap.ts

@@ -0,0 +1,289 @@
+import { TypeNode, IngestPayload, WrapOptions } from './types';
+import { inferType } from './type-inference';
+import { hashType } from './type-hash';
+import { createTracker } from './proxy-tracker';
+import { TypeCache } from './cache';
+import { enqueue } from './transport';
+
+const typeCache = new TypeCache();
+
+/** Symbol to mark already-wrapped functions, preventing double-wrap. */
+const TRICKLE_WRAPPED = Symbol.for('__trickle_wrapped');
+
+/**
+ * Wrap a function to capture runtime type information on each call.
+ * The wrapper is completely transparent: same name, same length, same behavior.
+ * Errors are always re-thrown after capturing type context.
+ */
+export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: WrapOptions): T {
+  if (!opts.enabled) return fn;
+
+  // Prevent double-wrapping (compile hook + load hook may both see the same function)
+  if ((fn as any)[TRICKLE_WRAPPED]) return fn;
+
+  const functionKey = `${opts.module}::${opts.functionName}`;
+
+  // Create wrapper with same length using a dynamic approach
+  const wrapper = function (this: any, ...args: any[]): any {
+    // Sample rate check
+    if (opts.sampleRate < 1 && Math.random() > opts.sampleRate) {
+      return fn.apply(this, args);
+    }
+
+    // Set up arg tracking
+    const trackers: Array<{ proxy: unknown; getAccessedPaths: () => Map<string, TypeNode> }> = [];
+    const proxiedArgs = args.map((arg, i) => {
+      if (arg !== null && arg !== undefined && typeof arg === 'object') {
+        const tracker = createTracker(arg);
+        trackers.push(tracker);
+        return tracker.proxy;
+      }
+      return arg;
+    });
+
+    let result: any;
+    let threwError = false;
+    let caughtError: unknown;
+
+    try {
+      result = fn.apply(this, proxiedArgs);
+    } catch (err) {
+      threwError = true;
+      caughtError = err;
+
+      // Capture error context
+      try {
+        captureErrorPayload(functionKey, opts, args, trackers, err);
+      } catch {
+        // Never let our instrumentation interfere
+      }
+
+      // CRITICAL: always re-throw
+      throw err;
+    }
+
+    // Handle async functions (Promise return)
+    if (result !== null && result !== undefined && typeof result === 'object' && typeof result.then === 'function') {
+      return result.then(
+        (resolved: unknown) => {
+          try {
+            capturePayload(functionKey, opts, args, trackers, resolved, true);
+          } catch {
+            // Never let our instrumentation interfere
+          }
+          return resolved;
+        },
+        (err: unknown) => {
+          try {
+            captureErrorPayload(functionKey, opts, args, trackers, err);
+          } catch {
+            // Never let our instrumentation interfere
+          }
+          // Re-throw the original rejection
+          throw err;
+        },
+      );
+    }
+
+    // Synchronous return
+    try {
+      capturePayload(functionKey, opts, args, trackers, result);
+    } catch {
+      // Never let our instrumentation interfere
+    }
+
+    return result;
+  };
+
+  // Preserve function name and length
+  Object.defineProperty(wrapper, 'name', { value: fn.name || opts.functionName, configurable: true });
+  Object.defineProperty(wrapper, 'length', { value: fn.length, configurable: true });
+
+  // Mark as wrapped to prevent double-wrapping
+  (wrapper as any)[TRICKLE_WRAPPED] = true;
+
+  return wrapper as unknown as T;
+}
+
+/**
+ * Capture and enqueue a successful invocation's type data.
+ */
+function capturePayload(
+  functionKey: string,
+  opts: WrapOptions,
+  originalArgs: unknown[],
+  trackers: Array<{ proxy: unknown; getAccessedPaths: () => Map<string, TypeNode> }>,
+  returnValue: unknown,
+  isAsync: boolean = false,
+): void {
+  // Build args type as a tuple
+  const argsType = buildArgsType(originalArgs, trackers, opts.maxDepth);
+  const returnType = inferType(returnValue, opts.maxDepth);
+
+  const hash = hashType(argsType, returnType);
+
+  // Check cache
+  if (!typeCache.shouldSend(functionKey, hash)) {
+    return;
+  }
+
+  typeCache.markSent(functionKey, hash);
+
+  const payload: IngestPayload = {
+    functionName: opts.functionName,
+    module: opts.module,
+    language: 'js',
+    environment: opts.environment,
+    typeHash: hash,
+    argsType,
+    returnType,
+    sampleInput: sanitizeSample(originalArgs),
+    sampleOutput: sanitizeSample(returnValue),
+  };
+
+  if (isAsync) {
+    payload.isAsync = true;
+  }
+
+  if (opts.paramNames && opts.paramNames.length > 0) {
+    payload.paramNames = opts.paramNames;
+  }
+
+  enqueue(payload);
+}
+
+/**
+ * Capture type context for a failed invocation.
+ */
+function captureErrorPayload(
+  functionKey: string,
+  opts: WrapOptions,
+  originalArgs: unknown[],
+  trackers: Array<{ proxy: unknown; getAccessedPaths: () => Map<string, TypeNode> }>,
+  error: unknown,
+): void {
+  const argsType = buildArgsType(originalArgs, trackers, opts.maxDepth);
+  const returnType: TypeNode = { kind: 'unknown' };
+  const hash = hashType(argsType, returnType);
+
+  // Always send error payloads (don't cache-skip them)
+
+  const errorInfo = extractErrorInfo(error);
+
+  // Collect accessed paths from trackers as "variable" context
+  const accessedPaths: Record<string, TypeNode> = {};
+  for (const tracker of trackers) {
+    const paths = tracker.getAccessedPaths();
+    for (const [path, type] of paths) {
+      accessedPaths[path] = type;
+    }
+  }
+
+  const payload: IngestPayload = {
+    functionName: opts.functionName,
+    module: opts.module,
+    language: 'js',
+    environment: opts.environment,
+    typeHash: hash,
+    argsType,
+    returnType,
+    sampleInput: sanitizeSample(originalArgs),
+    error: {
+      type: errorInfo.type,
+      message: errorInfo.message,
+      stackTrace: errorInfo.stack,
+      argsSnapshot: sanitizeSample(originalArgs),
+    },
+  };
+
+  enqueue(payload);
+}
+
+/**
+ * Build a tuple TypeNode for the args array.
+ * Uses tracker data for objects/arrays that were proxied (captures the "shape" actually used),
+ * and falls back to full inference for primitives and untracked args.
+ */
+function buildArgsType(
+  originalArgs: unknown[],
+  trackers: Array<{ proxy: unknown; getAccessedPaths: () => Map<string, TypeNode> }>,
+  maxDepth: number,
+): TypeNode {
+  const elements: TypeNode[] = originalArgs.map(arg => inferType(arg, maxDepth));
+
+  if (elements.length === 0) {
+    return { kind: 'tuple', elements: [] };
+  }
+
+  return { kind: 'tuple', elements };
+}
+
+/**
+ * Extract error information safely.
+ */
+function extractErrorInfo(err: unknown): { type: string; message: string; stack?: string } {
+  if (err instanceof Error) {
+    return {
+      type: err.constructor.name || 'Error',
+      message: err.message,
+      stack: err.stack,
+    };
+  }
+
+  if (typeof err === 'string') {
+    return { type: 'String', message: err };
+  }
+
+  return {
+    type: typeof err,
+    message: String(err),
+  };
+}
+
+/**
+ * Sanitize a sample value for safe serialization.
+ * Truncates large strings, limits array lengths, strips functions.
+ */
+function sanitizeSample(value: unknown, depth: number = 3): unknown {
+  if (depth <= 0) return '[truncated]';
+  if (value === null || value === undefined) return value;
+
+  const t = typeof value;
+  if (t === 'string') {
+    const s = value as string;
+    return s.length > 200 ? s.substring(0, 200) + '...' : s;
+  }
+  if (t === 'number' || t === 'boolean') return value;
+  if (t === 'bigint') return String(value);
+  if (t === 'symbol') return String(value);
+  if (t === 'function') return `[Function: ${(value as Function).name || 'anonymous'}]`;
+
+  if (Array.isArray(value)) {
+    const sample = value.slice(0, 5);
+    return sample.map(item => sanitizeSample(item, depth - 1));
+  }
+
+  if (t === 'object') {
+    if (value instanceof Date) return value.toISOString();
+    if (value instanceof RegExp) return String(value);
+    if (value instanceof Error) return { error: value.message };
+    if (value instanceof Map) return `[Map: ${value.size} entries]`;
+    if (value instanceof Set) return `[Set: ${value.size} items]`;
+
+    const obj = value as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    const keys = Object.keys(obj).slice(0, 20);
+    for (const key of keys) {
+      try {
+        result[key] = sanitizeSample(obj[key], depth - 1);
+      } catch {
+        result[key] = '[unreadable]';
+      }
+    }
+    return result;
+  }
+
+  return String(value);
+}
+
+export { typeCache };

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}