trickle-observe 0.1.0

package/dist/auto-register.d.ts

@@ -0,0 +1,16 @@
+/**
+ * trickle/auto — Zero-config type generation.
+ *
+ * Add ONE LINE to your app and types appear automatically:
+ *
+ *   require('trickle/auto');
+ *
+ * This module:
+ * 1. Forces local mode (no backend needed)
+ * 2. Activates the observe-register hooks (instruments all user functions)
+ * 3. Runs a background timer that generates .d.ts files from observations
+ * 4. On process exit, does a final type generation
+ *
+ * No CLI. No backend. No configuration. Just types.
+ */
+import './observe-register';

package/dist/auto-register.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * trickle/auto — Zero-config type generation.
+ *
+ * Add ONE LINE to your app and types appear automatically:
+ *
+ *   require('trickle/auto');
+ *
+ * This module:
+ * 1. Forces local mode (no backend needed)
+ * 2. Activates the observe-register hooks (instruments all user functions)
+ * 3. Runs a background timer that generates .d.ts files from observations
+ * 4. On process exit, does a final type generation
+ *
+ * No CLI. No backend. No configuration. Just types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// Force local mode BEFORE importing observe-register (which calls configure)
+process.env.TRICKLE_LOCAL = '1';
+// Import the observe-register hooks (instruments all functions)
+require("./observe-register");
+// Import the auto codegen
+const auto_codegen_1 = require("./auto-codegen");
+const debug = process.env.TRICKLE_DEBUG === '1' || process.env.TRICKLE_DEBUG === 'true';
+let lastFunctionCount = 0;
+let generationCount = 0;
+/**
+ * Run type generation and optionally log results.
+ */
+function runGeneration(isFinal) {
+    try {
+        const count = (0, auto_codegen_1.generateTypes)();
+        if (count === -1)
+            return; // no change
+        if (count > 0) {
+            generationCount++;
+            if (debug || (count > lastFunctionCount)) {
+                const newTypes = count - lastFunctionCount;
+                if (newTypes > 0 && generationCount > 1) {
+                    // Only log after first generation (avoid noise on startup)
+                    console.log(`[trickle/auto] +${newTypes} type(s) generated (${count} total)`);
+                }
+            }
+            lastFunctionCount = count;
+        }
+        if (isFinal && lastFunctionCount > 0) {
+            console.log(`[trickle/auto] ${lastFunctionCount} function type(s) written to .d.ts`);
+            // Inject JSDoc into source files if TRICKLE_INJECT=1
+            try {
+                const injected = (0, auto_codegen_1.injectTypes)();
+                if (injected > 0) {
+                    console.log(`[trickle/auto] ${injected} function(s) annotated with JSDoc in source`);
+                }
+            }
+            catch { /* don't crash */ }
+            // Print coverage report if TRICKLE_COVERAGE=1
+            try {
+                const report = (0, auto_codegen_1.generateCoverageReport)();
+                if (report)
+                    console.log(report);
+            }
+            catch { /* don't crash */ }
+            // Print type summary if TRICKLE_SUMMARY=1
+            try {
+                const summary = (0, auto_codegen_1.generateTypeSummary)();
+                if (summary)
+                    console.log(summary);
+            }
+            catch { /* don't crash */ }
+        }
+    }
+    catch {
+        // Never crash user's app
+    }
+}
+// Background timer — regenerate types every 3 seconds
+const timer = setInterval(() => runGeneration(false), 3000);
+// Don't keep the process alive just for type generation
+if (timer && typeof timer === 'object' && 'unref' in timer) {
+    timer.unref();
+}
+// Also do a first check after 1 second
+const initialTimer = setTimeout(() => runGeneration(false), 1000);
+if (initialTimer && typeof initialTimer === 'object' && 'unref' in initialTimer) {
+    initialTimer.unref();
+}
+// Final generation on exit
+if (typeof process !== 'undefined' && process.on) {
+    process.on('beforeExit', () => {
+        runGeneration(true);
+    });
+    // On SIGTERM/SIGINT, do final generation
+    const exitHandler = () => {
+        clearInterval(timer);
+        runGeneration(true);
+    };
+    process.on('SIGTERM', exitHandler);
+    process.on('SIGINT', exitHandler);
+}

package/dist/cache.d.ts

@@ -0,0 +1,27 @@
+/**
+ * In-memory cache to avoid sending redundant type data to the backend.
+ * Keyed by function identity (name + module), stores the last type hash sent.
+ * Re-sends if the hash changes or if the entry becomes stale.
+ */
+export declare class TypeCache {
+    private cache;
+    private maxStalenessMs;
+    constructor(maxStalenessMs?: number);
+    /**
+     * Returns true if this type observation should be sent to the backend.
+     * Returns false if we recently sent the same hash for this function.
+     */
+    shouldSend(functionKey: string, hash: string): boolean;
+    /**
+     * Mark that we just sent data for this function with this hash.
+     */
+    markSent(functionKey: string, hash: string): void;
+    /**
+     * Clear the cache (useful for testing or reconfiguration).
+     */
+    clear(): void;
+    /**
+     * Get the number of cached entries.
+     */
+    get size(): number;
+}

package/dist/cache.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeCache = void 0;
+/**
+ * In-memory cache to avoid sending redundant type data to the backend.
+ * Keyed by function identity (name + module), stores the last type hash sent.
+ * Re-sends if the hash changes or if the entry becomes stale.
+ */
+class TypeCache {
+    cache;
+    maxStalenessMs;
+    constructor(maxStalenessMs = 5 * 60 * 1000) {
+        this.cache = new Map();
+        this.maxStalenessMs = maxStalenessMs;
+    }
+    /**
+     * Returns true if this type observation should be sent to the backend.
+     * Returns false if we recently sent the same hash for this function.
+     */
+    shouldSend(functionKey, hash) {
+        const entry = this.cache.get(functionKey);
+        if (!entry)
+            return true;
+        // Different type shape — always send
+        if (entry.hash !== hash)
+            return true;
+        // Same shape but stale — re-send to confirm it's still alive
+        const age = Date.now() - entry.lastSentAt;
+        if (age > this.maxStalenessMs)
+            return true;
+        return false;
+    }
+    /**
+     * Mark that we just sent data for this function with this hash.
+     */
+    markSent(functionKey, hash) {
+        this.cache.set(functionKey, { hash, lastSentAt: Date.now() });
+    }
+    /**
+     * Clear the cache (useful for testing or reconfiguration).
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the number of cached entries.
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+exports.TypeCache = TypeCache;

package/dist/env-detect.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Detect the runtime environment from environment variables.
+ * Returns a human-readable string identifying where this code is running.
+ */
+export declare function detectEnvironment(): string;

package/dist/env-detect.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectEnvironment = detectEnvironment;
+/**
+ * Detect the runtime environment from environment variables.
+ * Returns a human-readable string identifying where this code is running.
+ */
+function detectEnvironment() {
+    const env = typeof process !== 'undefined' && process.env ? process.env : {};
+    if (env.AWS_LAMBDA_FUNCTION_NAME)
+        return 'lambda';
+    if (env.VERCEL)
+        return 'vercel';
+    if (env.RAILWAY_ENVIRONMENT)
+        return 'railway';
+    if (env.K_SERVICE)
+        return 'cloud-run';
+    if (env.AZURE_FUNCTIONS_ENVIRONMENT)
+        return 'azure-functions';
+    if (env.GOOGLE_CLOUD_PROJECT)
+        return 'gcp';
+    if (env.ECS_CONTAINER_METADATA_URI)
+        return 'ecs';
+    if (env.FLY_APP_NAME)
+        return 'fly';
+    if (env.RENDER_SERVICE_ID)
+        return 'render';
+    if (env.HEROKU_APP_NAME || env.DYNO)
+        return 'heroku';
+    if (env.CODESPACE_NAME)
+        return 'codespace';
+    if (env.GITPOD_WORKSPACE_ID)
+        return 'gitpod';
+    return 'node';
+}

package/dist/express.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Instrument an Express application by monkey-patching route registration methods.
+ *
+ * Must be called BEFORE routes are defined:
+ *
+ *   import express from 'express';
+ *   import { instrumentExpress } from 'trickle';
+ *
+ *   const app = express();
+ *   instrumentExpress(app);
+ *
+ *   app.get('/api/users', (req, res) => { ... });
+ *
+ * Each registered handler is wrapped to capture:
+ * - Input: `{ body, params, query }` from the request
+ * - Output: the data passed to `res.json()` or `res.send()`
+ * - Errors: exceptions or `next(err)` calls
+ */
+export declare function instrumentExpress(app: any, userOpts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): void;
+/**
+ * Express middleware that intercepts responses to capture type information.
+ *
+ * Use this when you prefer middleware over monkey-patching:
+ *
+ *   import express from 'express';
+ *   import { trickleMiddleware } from 'trickle';
+ *
+ *   const app = express();
+ *   app.use(trickleMiddleware());
+ *
+ * The middleware captures the route `METHOD /path` once the response is sent,
+ * by intercepting `res.json()` and `res.send()`.
+ */
+export declare function trickleMiddleware(userOpts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): (req: any, res: any, next: (...args: any[]) => void) => void;

package/dist/express.js

@@ -0,0 +1,342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instrumentExpress = instrumentExpress;
+exports.trickleMiddleware = trickleMiddleware;
+const type_inference_1 = require("./type-inference");
+const type_hash_1 = require("./type-hash");
+const cache_1 = require("./cache");
+const transport_1 = require("./transport");
+const env_detect_1 = require("./env-detect");
+const expressCache = new cache_1.TypeCache();
+/**
+ * Extract the interesting parts of an Express request as a plain object
+ * suitable for type inference. We deliberately avoid the full req object
+ * because it is enormous and contains circular references.
+ */
+function extractRequestInput(req) {
+    const input = {};
+    try {
+        if (req.body !== undefined && req.body !== null && Object.keys(req.body).length > 0) {
+            input.body = req.body;
+        }
+    }
+    catch {
+        // body might not be readable
+    }
+    try {
+        if (req.params && Object.keys(req.params).length > 0) {
+            input.params = req.params;
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        if (req.query && Object.keys(req.query).length > 0) {
+            input.query = req.query;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return input;
+}
+/**
+ * Sanitize a sample value for safe serialization (local copy to avoid circular import).
+ */
+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)) {
+        return value.slice(0, 5).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);
+}
+/**
+ * Emit a type payload for a single Express route invocation.
+ */
+function emitExpressPayload(functionName, environment, maxDepth, input, output, error) {
+    try {
+        const functionKey = `express::${functionName}`;
+        const argsType = (0, type_inference_1.inferType)(input, maxDepth);
+        const returnType = error ? { kind: 'unknown' } : (0, type_inference_1.inferType)(output, maxDepth);
+        const hash = (0, type_hash_1.hashType)(argsType, returnType);
+        // For errors, always send. For success, use cache.
+        if (!error && !expressCache.shouldSend(functionKey, hash)) {
+            return;
+        }
+        if (!error) {
+            expressCache.markSent(functionKey, hash);
+        }
+        const payload = {
+            functionName,
+            module: 'express',
+            language: 'js',
+            environment,
+            typeHash: hash,
+            argsType,
+            returnType,
+            sampleInput: sanitizeSample(input),
+            sampleOutput: error ? undefined : sanitizeSample(output),
+        };
+        if (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            payload.error = {
+                type: err.constructor?.name || 'Error',
+                message: err.message,
+                stackTrace: err.stack,
+                argsSnapshot: sanitizeSample(input),
+            };
+        }
+        (0, transport_1.enqueue)(payload);
+    }
+    catch {
+        // Never crash the user's app
+    }
+}
+/**
+ * Wrap a single Express route handler so that it captures request input
+ * (body, params, query) and response output (json/send payloads) as type data.
+ */
+function wrapExpressHandler(handler, routeName, opts) {
+    const wrapped = function (req, res, next) {
+        // Sample rate check
+        if (opts.sampleRate < 1 && Math.random() > opts.sampleRate) {
+            return handler.call(this, req, res, next);
+        }
+        const input = extractRequestInput(req);
+        let captured = false;
+        // Intercept res.json()
+        const originalJson = res.json;
+        if (typeof originalJson === 'function') {
+            res.json = function (data) {
+                if (!captured) {
+                    captured = true;
+                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, data);
+                }
+                res.json = originalJson; // restore
+                return originalJson.call(res, data);
+            };
+        }
+        // Intercept res.send()
+        const originalSend = res.send;
+        if (typeof originalSend === 'function') {
+            res.send = function (data) {
+                if (!captured) {
+                    captured = true;
+                    // Only capture non-string data as typed output; strings are usually HTML
+                    const output = typeof data === 'string' ? { __html: true } : data;
+                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, output);
+                }
+                res.send = originalSend; // restore
+                return originalSend.call(res, data);
+            };
+        }
+        // Wrap next to capture errors passed via next(err)
+        const wrappedNext = function (err) {
+            if (err && !captured) {
+                captured = true;
+                emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err);
+            }
+            if (typeof next === 'function') {
+                return next(err);
+            }
+        };
+        try {
+            const result = handler.call(this, req, res, wrappedNext);
+            // Handle async handlers that return a promise
+            if (result && typeof result === 'object' && typeof result.then === 'function') {
+                return result.catch((err) => {
+                    if (!captured) {
+                        captured = true;
+                        emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err);
+                    }
+                    // Re-throw so Express error handling picks it up
+                    throw err;
+                });
+            }
+            return result;
+        }
+        catch (err) {
+            if (!captured) {
+                captured = true;
+                emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err);
+            }
+            throw err;
+        }
+    };
+    // Preserve function metadata
+    Object.defineProperty(wrapped, 'name', { value: handler.name || routeName, configurable: true });
+    Object.defineProperty(wrapped, 'length', { value: handler.length, configurable: true });
+    return wrapped;
+}
+/**
+ * Instrument an Express application by monkey-patching route registration methods.
+ *
+ * Must be called BEFORE routes are defined:
+ *
+ *   import express from 'express';
+ *   import { instrumentExpress } from 'trickle';
+ *
+ *   const app = express();
+ *   instrumentExpress(app);
+ *
+ *   app.get('/api/users', (req, res) => { ... });
+ *
+ * Each registered handler is wrapped to capture:
+ * - Input: `{ body, params, query }` from the request
+ * - Output: the data passed to `res.json()` or `res.send()`
+ * - Errors: exceptions or `next(err)` calls
+ */
+function instrumentExpress(app, userOpts) {
+    const opts = {
+        enabled: userOpts?.enabled !== false,
+        environment: userOpts?.environment || (0, env_detect_1.detectEnvironment)(),
+        sampleRate: userOpts?.sampleRate ?? 1,
+        maxDepth: userOpts?.maxDepth ?? 5,
+    };
+    if (!opts.enabled)
+        return;
+    const methods = ['get', 'post', 'put', 'delete', 'patch', 'all'];
+    for (const method of methods) {
+        const original = app[method];
+        if (typeof original !== 'function')
+            continue;
+        app[method] = function (path, ...handlers) {
+            // Express allows non-string first args (RegExp, array of paths, etc.)
+            // We only label with a string path; otherwise fall back to the method name.
+            const pathStr = typeof path === 'string' ? path : String(path);
+            const routeName = `${method.toUpperCase()} ${pathStr}`;
+            const wrapped = handlers.map((handler) => {
+                if (typeof handler !== 'function')
+                    return handler;
+                try {
+                    return wrapExpressHandler(handler, routeName, opts);
+                }
+                catch {
+                    // If wrapping fails for any reason, return the original handler
+                    return handler;
+                }
+            });
+            return original.call(this, path, ...wrapped);
+        };
+    }
+}
+/**
+ * Express middleware that intercepts responses to capture type information.
+ *
+ * Use this when you prefer middleware over monkey-patching:
+ *
+ *   import express from 'express';
+ *   import { trickleMiddleware } from 'trickle';
+ *
+ *   const app = express();
+ *   app.use(trickleMiddleware());
+ *
+ * The middleware captures the route `METHOD /path` once the response is sent,
+ * by intercepting `res.json()` and `res.send()`.
+ */
+function trickleMiddleware(userOpts) {
+    const opts = {
+        enabled: userOpts?.enabled !== false,
+        environment: userOpts?.environment || (0, env_detect_1.detectEnvironment)(),
+        sampleRate: userOpts?.sampleRate ?? 1,
+        maxDepth: userOpts?.maxDepth ?? 5,
+    };
+    return function trickleMiddlewareHandler(req, res, next) {
+        if (!opts.enabled) {
+            next();
+            return;
+        }
+        // Sample rate check
+        if (opts.sampleRate < 1 && Math.random() > opts.sampleRate) {
+            next();
+            return;
+        }
+        let captured = false;
+        // We derive the route name lazily once the response is being sent,
+        // because req.route is only populated after the handler matches.
+        function getRouteName() {
+            try {
+                if (req.route && req.route.path) {
+                    return `${req.method} ${req.baseUrl || ''}${req.route.path}`;
+                }
+            }
+            catch {
+                // ignore
+            }
+            return `${req.method || 'UNKNOWN'} ${req.originalUrl || req.url || '/'}`;
+        }
+        const input = extractRequestInput(req);
+        // Intercept res.json()
+        const originalJson = res.json;
+        if (typeof originalJson === 'function') {
+            res.json = function (data) {
+                if (!captured) {
+                    captured = true;
+                    const routeName = getRouteName();
+                    // Re-extract input here because body parsers may have run since middleware was entered
+                    const latestInput = extractRequestInput(req);
+                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, data);
+                }
+                res.json = originalJson;
+                return originalJson.call(res, data);
+            };
+        }
+        // Intercept res.send()
+        const originalSend = res.send;
+        if (typeof originalSend === 'function') {
+            res.send = function (data) {
+                if (!captured) {
+                    captured = true;
+                    const routeName = getRouteName();
+                    const latestInput = extractRequestInput(req);
+                    const output = typeof data === 'string' ? { __html: true } : data;
+                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, output);
+                }
+                res.send = originalSend;
+                return originalSend.call(res, data);
+            };
+        }
+        next();
+    };
+}

package/dist/fetch-observer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Fetch observer — patches global.fetch to automatically capture
+ * request/response types from HTTP calls made by user code.
+ *
+ * When your app does:
+ *   const data = await fetch('https://api.example.com/users').then(r => r.json());
+ *
+ * Trickle captures:
+ *   - Function name: "GET /users" (method + path)
+ *   - Module: "api.example.com" (hostname)
+ *   - Input type: request body (for POST/PUT/PATCH)
+ *   - Return type: inferred from JSON response
+ *   - Sample data: actual response payload
+ *
+ * The observer only intercepts when .json() is called, so:
+ *   - Non-JSON responses (HTML, binary) are ignored
+ *   - The original response is never modified
+ *   - No extra network requests are made
+ */
+/**
+ * Patch global.fetch to observe JSON responses.
+ * Safe to call multiple times (idempotent).
+ */
+export declare function patchFetch(environment: string, debugMode: boolean): void;