trickle-observe 0.1.0

package/dist/type-inference.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferType = inferType;
+exports.unifyTypes = unifyTypes;
+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.
+ */
+function inferType(value, maxDepth = DEFAULT_MAX_DEPTH) {
+    const seen = new WeakSet();
+    return infer(value, maxDepth, seen);
+}
+function infer(value, depth, seen) {
+    // 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.length).fill({ kind: 'unknown' }),
+            returnType: { kind: 'unknown' },
+        };
+    }
+    // Object types — check depth and circular refs
+    if (t === 'object') {
+        const obj = value;
+        // 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, depth, seen) {
+    // Promise
+    if (obj instanceof Promise) {
+        return { kind: 'promise', resolved: { kind: 'unknown' } };
+    }
+    // Map
+    if (obj instanceof Map) {
+        let keyType = { kind: 'unknown' };
+        let valType = { kind: 'unknown' };
+        let count = 0;
+        const keyTypes = [];
+        const valTypes = [];
+        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 = [];
+        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, depth, seen) {
+    if (arr.length === 0) {
+        return { kind: 'array', element: { kind: 'unknown' } };
+    }
+    const sampleSize = Math.min(arr.length, MAX_ARRAY_SAMPLE);
+    const elementTypes = [];
+    for (let i = 0; i < sampleSize; i++) {
+        elementTypes.push(infer(arr[i], depth - 1, seen));
+    }
+    return { kind: 'array', element: unifyTypes(elementTypes) };
+}
+function inferPlainObject(obj, depth, seen) {
+    const properties = {};
+    const keys = Object.keys(obj);
+    for (const key of keys) {
+        try {
+            properties[key] = infer(obj[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) {
+    if (types.length === 0)
+        return { kind: 'unknown' };
+    if (types.length === 1)
+        return types[0];
+    // Deduplicate by serialization
+    const uniqueMap = new Map();
+    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 = [];
+    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();
+    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) {
+    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}';
+}

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+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/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/wrap.d.ts

@@ -0,0 +1,10 @@
+import { WrapOptions } from './types';
+import { TypeCache } from './cache';
+declare const typeCache: TypeCache;
+/**
+ * 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 declare function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: WrapOptions): T;
+export { typeCache };

package/dist/wrap.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typeCache = void 0;
+exports.wrapFunction = wrapFunction;
+const type_inference_1 = require("./type-inference");
+const type_hash_1 = require("./type-hash");
+const proxy_tracker_1 = require("./proxy-tracker");
+const cache_1 = require("./cache");
+const transport_1 = require("./transport");
+const typeCache = new cache_1.TypeCache();
+exports.typeCache = 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.
+ */
+function wrapFunction(fn, opts) {
+    if (!opts.enabled)
+        return fn;
+    // Prevent double-wrapping (compile hook + load hook may both see the same function)
+    if (fn[TRICKLE_WRAPPED])
+        return fn;
+    const functionKey = `${opts.module}::${opts.functionName}`;
+    // Create wrapper with same length using a dynamic approach
+    const wrapper = function (...args) {
+        // Sample rate check
+        if (opts.sampleRate < 1 && Math.random() > opts.sampleRate) {
+            return fn.apply(this, args);
+        }
+        // Set up arg tracking
+        const trackers = [];
+        const proxiedArgs = args.map((arg, i) => {
+            if (arg !== null && arg !== undefined && typeof arg === 'object') {
+                const tracker = (0, proxy_tracker_1.createTracker)(arg);
+                trackers.push(tracker);
+                return tracker.proxy;
+            }
+            return arg;
+        });
+        let result;
+        let threwError = false;
+        let caughtError;
+        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) => {
+                try {
+                    capturePayload(functionKey, opts, args, trackers, resolved, true);
+                }
+                catch {
+                    // Never let our instrumentation interfere
+                }
+                return resolved;
+            }, (err) => {
+                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[TRICKLE_WRAPPED] = true;
+    return wrapper;
+}
+/**
+ * Capture and enqueue a successful invocation's type data.
+ */
+function capturePayload(functionKey, opts, originalArgs, trackers, returnValue, isAsync = false) {
+    // Build args type as a tuple
+    const argsType = buildArgsType(originalArgs, trackers, opts.maxDepth);
+    const returnType = (0, type_inference_1.inferType)(returnValue, opts.maxDepth);
+    const hash = (0, type_hash_1.hashType)(argsType, returnType);
+    // Check cache
+    if (!typeCache.shouldSend(functionKey, hash)) {
+        return;
+    }
+    typeCache.markSent(functionKey, hash);
+    const payload = {
+        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;
+    }
+    (0, transport_1.enqueue)(payload);
+}
+/**
+ * Capture type context for a failed invocation.
+ */
+function captureErrorPayload(functionKey, opts, originalArgs, trackers, error) {
+    const argsType = buildArgsType(originalArgs, trackers, opts.maxDepth);
+    const returnType = { kind: 'unknown' };
+    const hash = (0, type_hash_1.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 = {};
+    for (const tracker of trackers) {
+        const paths = tracker.getAccessedPaths();
+        for (const [path, type] of paths) {
+            accessedPaths[path] = type;
+        }
+    }
+    const payload = {
+        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),
+        },
+    };
+    (0, transport_1.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, trackers, maxDepth) {
+    const elements = originalArgs.map(arg => (0, type_inference_1.inferType)(arg, maxDepth));
+    if (elements.length === 0) {
+        return { kind: 'tuple', elements: [] };
+    }
+    return { kind: 'tuple', elements };
+}
+/**
+ * Extract error information safely.
+ */
+function extractErrorInfo(err) {
+    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, depth = 3) {
+    if (depth <= 0)
+        return '[truncated]';
+    if (value === null || value === undefined)
+        return value;
+    const t = typeof value;
+    if (t === 'string') {
+        const s = value;
+        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.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;
+        const result = {};
+        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);
+}