trickle-observe 0.2.1 → 0.2.3

package/dist/auto-codegen.d.ts

@@ -11,7 +11,7 @@
  */
 export declare function injectTypes(): number;
 /**
- * Read observations and generate .d.ts files next to source files.
+ * Read observations and generate .d.ts type files in .trickle/types/.
  * Returns the number of functions typed.
  */
 export declare function generateTypes(): number;

package/dist/auto-codegen.js

@@ -248,6 +248,17 @@ function typeToTS(node, ext, parent, prop, indent) {
             const keys = Object.keys(node.properties || {});
             if (keys.length === 0)
                 return 'Record<string, never>';
+            // Recognize special marker objects from type-inference
+            if (keys.length === 1 && keys[0] === '__date')
+                return 'Date';
+            if (keys.length === 1 && keys[0] === '__buffer')
+                return 'Buffer';
+            if (keys.length === 1 && keys[0] === '__typedArray')
+                return 'TypedArray';
+            if (keys.includes('__regexp'))
+                return 'RegExp';
+            if (keys.includes('__error'))
+                return 'Error';
             if (keys.length > 2 && prop) {
                 const iName = toPascalCase(parent) + toPascalCase(prop);
                 if (!ext.some(e => e.name === iName))
@@ -543,6 +554,15 @@ function typeToJSDoc(node) {
             const keys = Object.keys(props);
             if (keys.length === 0)
                 return 'Object';
+            // Recognize special marker objects from type-inference
+            if (keys.length === 1 && keys[0] === '__date')
+                return 'Date';
+            if (keys.length === 1 && keys[0] === '__buffer')
+                return 'Buffer';
+            if (keys.includes('__regexp'))
+                return 'RegExp';
+            if (keys.includes('__error'))
+                return 'Error';
             const entries = keys.map(k => {
                 const { isOptional, innerType } = extractOptional(props[k]);
                 return isOptional ? `${k}?: ${typeToJSDoc(innerType)}` : `${k}: ${typeToJSDoc(innerType)}`;
@@ -673,9 +693,143 @@ function injectTypes() {
 }
 // ── Public API ──
 let lastSize = 0;
-let lastContent = '';
+const lastContentByModule = new Map();
+let tsconfigPatched = false;
 /**
- * Read observations and generate .d.ts files next to source files.
+ * Generate a typed Express route definitions file from route observations.
+ * Each route (e.g., "GET /users") becomes a typed interface.
+ */
+function generateRoutesDts(routeFunctions) {
+    const sections = [
+        '// Auto-generated by trickle — Express route types from runtime observations',
+        `// Generated at ${new Date().toISOString()}`,
+        '// Do not edit — types update automatically as your code runs',
+        '',
+    ];
+    const ext = [];
+    for (const fn of routeFunctions) {
+        // Route name like "GET /users" → GetUsers
+        const routeName = fn.name;
+        const baseName = toPascalCase(routeName);
+        // Input type (body, params, query)
+        const inputProps = fn.argsType.kind === 'object' ? fn.argsType.properties || {} : {};
+        const hasInput = Object.keys(inputProps).length > 0;
+        if (hasInput) {
+            sections.push(renderInterface(`${baseName}Input`, fn.argsType, ext));
+            sections.push('');
+        }
+        // Output type
+        if (fn.returnType.kind === 'object' && Object.keys(fn.returnType.properties || {}).length > 0) {
+            sections.push(renderInterface(`${baseName}Output`, fn.returnType, ext));
+        }
+        else {
+            sections.push(`export type ${baseName}Output = ${typeToTS(fn.returnType, ext, baseName, undefined, 0)};`);
+        }
+        sections.push('');
+    }
+    // Emit extracted interfaces
+    const emitted = new Set();
+    const extLines = [];
+    for (const iface of ext) {
+        if (emitted.has(iface.name))
+            continue;
+        emitted.add(iface.name);
+        extLines.push(renderInterface(iface.name, iface.node, ext));
+        extLines.push('');
+    }
+    if (extLines.length > 0) {
+        // Insert extracted interfaces after the header, before route types
+        sections.splice(4, 0, ...extLines);
+    }
+    // Route map type for typed middleware/client usage
+    sections.push('/** All observed routes with their input/output types */');
+    sections.push('export interface TrickleRoutes {');
+    for (const fn of routeFunctions) {
+        const baseName = toPascalCase(fn.name);
+        const inputProps = fn.argsType.kind === 'object' ? fn.argsType.properties || {} : {};
+        const hasInput = Object.keys(inputProps).length > 0;
+        const inputType = hasInput ? `${baseName}Input` : 'Record<string, never>';
+        sections.push(`  '${fn.name}': { input: ${inputType}; output: ${baseName}Output };`);
+    }
+    sections.push('}');
+    sections.push('');
+    return sections.join('\n');
+}
+/**
+ * Ensure .trickle/types/ directory exists.
+ */
+function ensureTypesDir(trickleDir) {
+    const typesDir = path.join(trickleDir, 'types');
+    try {
+        fs.mkdirSync(typesDir, { recursive: true });
+    }
+    catch { /* already exists */ }
+    return typesDir;
+}
+/**
+ * Auto-patch tsconfig.json to include .trickle/types so generated
+ * types are visible in VSCode and tsc. Only runs once per process.
+ */
+function patchTsConfig() {
+    if (tsconfigPatched)
+        return;
+    tsconfigPatched = true;
+    const tsconfigPath = path.join(process.cwd(), 'tsconfig.json');
+    try {
+        if (!fs.existsSync(tsconfigPath))
+            return;
+        const raw = fs.readFileSync(tsconfigPath, 'utf-8');
+        // Strip JSON comments safely (skip strings to avoid breaking paths like "@/*")
+        let stripped = '';
+        let i = 0;
+        while (i < raw.length) {
+            if (raw[i] === '"') {
+                // Skip string content
+                let j = i + 1;
+                while (j < raw.length && raw[j] !== '"') {
+                    if (raw[j] === '\\')
+                        j++; // skip escaped char
+                    j++;
+                }
+                stripped += raw.slice(i, j + 1);
+                i = j + 1;
+            }
+            else if (raw[i] === '/' && i + 1 < raw.length && raw[i + 1] === '/') {
+                // Line comment — skip to end of line
+                while (i < raw.length && raw[i] !== '\n')
+                    i++;
+            }
+            else if (raw[i] === '/' && i + 1 < raw.length && raw[i + 1] === '*') {
+                // Block comment — skip to */
+                i += 2;
+                while (i < raw.length - 1 && !(raw[i] === '*' && raw[i + 1] === '/'))
+                    i++;
+                i += 2;
+            }
+            else {
+                stripped += raw[i];
+                i++;
+            }
+        }
+        // Also strip trailing commas (common in tsconfig)
+        const cleaned = stripped.replace(/,(\s*[}\]])/g, '$1');
+        const config = JSON.parse(cleaned);
+        const include = config.include;
+        if (include && include.some((p) => p === '.trickle' || p.startsWith('.trickle/'))) {
+            return; // Already configured
+        }
+        if (include) {
+            include.push('.trickle/types');
+        }
+        else {
+            config.include = ['.trickle/types'];
+        }
+        fs.writeFileSync(tsconfigPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    }
+    catch { /* don't crash — tsconfig patching is best-effort */ }
+}
+/**
+ * Read observations and generate .d.ts type files in .trickle/types/.
  * Returns the number of functions typed.
  */
 function generateTypes() {
@@ -696,35 +850,53 @@ function generateTypes() {
     const functions = readAndMerge(jsonlPath);
     if (functions.length === 0)
         return 0;
-    // Group by module and generate .d.ts next to source files
-    const byModule = new Map();
+    // Separate Express route observations from regular functions
+    const routeFunctions = [];
+    const regularFunctions = [];
     for (const fn of functions) {
+        if (fn.module === 'express' && /^(GET|POST|PUT|DELETE|PATCH|ALL)\s/.test(fn.name)) {
+            routeFunctions.push(fn);
+        }
+        else {
+            regularFunctions.push(fn);
+        }
+    }
+    // Group regular functions by module
+    const byModule = new Map();
+    for (const fn of regularFunctions) {
         const mod = fn.module || '_default';
         if (!byModule.has(mod))
             byModule.set(mod, []);
         byModule.get(mod).push(fn);
     }
+    // Write all types to .trickle/types/ so TypeScript picks them up via tsconfig include
+    const typesDir = ensureTypesDir(trickleDir);
+    patchTsConfig();
     let totalFunctions = 0;
+    // Generate Express route types
+    if (routeFunctions.length > 0) {
+        const routesDts = generateRoutesDts(routeFunctions);
+        if (routesDts !== lastContentByModule.get('__routes')) {
+            const routesDtsPath = path.join(typesDir, 'routes.d.ts');
+            try {
+                fs.writeFileSync(routesDtsPath, routesDts, 'utf-8');
+                lastContentByModule.set('__routes', routesDts);
+                totalFunctions += routeFunctions.length;
+            }
+            catch { /* don't crash */ }
+        }
+    }
     for (const [mod, fns] of byModule) {
         // Skip HTTP route observations (module is hostname like "localhost")
         if (mod.includes('.') && !mod.includes('/') && !mod.includes('\\'))
             continue;
         const dts = generateDts(fns);
-        if (dts === lastContent)
+        if (dts === lastContentByModule.get(mod))
             continue;
-        // Find source file for this module
-        const sourceFile = findSourceFile(mod);
-        if (!sourceFile)
-            continue;
-        const ext = path.extname(sourceFile);
-        const dir = path.dirname(sourceFile);
-        const baseName = path.basename(sourceFile, ext);
-        // For .ts/.tsx files, use .trickle.d.ts to avoid conflicts (TS ignores .d.ts next to .ts)
-        const isTs = ext === '.ts' || ext === '.tsx';
-        const dtsPath = path.join(dir, `${baseName}${isTs ? '.trickle' : ''}.d.ts`);
+        const dtsPath = path.join(typesDir, `${mod}.d.ts`);
         try {
             fs.writeFileSync(dtsPath, dts, 'utf-8');
-            lastContent = dts;
+            lastContentByModule.set(mod, dts);
             totalFunctions += fns.length;
         }
         catch { /* don't crash user's app */ }
@@ -858,6 +1030,14 @@ function typeToCompact(node, depth = 0) {
             const keys = Object.keys(props);
             if (keys.length === 0)
                 return '{}';
+            if (keys.length === 1 && keys[0] === '__date')
+                return 'Date';
+            if (keys.length === 1 && keys[0] === '__buffer')
+                return 'Buffer';
+            if (keys.includes('__regexp'))
+                return 'RegExp';
+            if (keys.includes('__error'))
+                return 'Error';
             if (keys.length > 4) {
                 const shown = keys.slice(0, 3).map(k => `${k}: ${typeToCompact(props[k], depth + 1)}`);
                 return `{ ${shown.join(', ')}, ... }`;
@@ -970,6 +1150,39 @@ function generateTypeSummary() {
     }
     return lines.join('\n');
 }
+/**
+ * Cached recursive file index: maps basename (without ext) → full path.
+ * Built once on first call, then reused.
+ */
+let fileIndex = null;
+function buildFileIndex() {
+    const cwd = process.cwd();
+    const exts = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs']);
+    const index = new Map();
+    // Common source directories to scan
+    const dirs = ['src', 'dist', 'lib', 'app', '.'];
+    for (const dir of dirs) {
+        const absDir = path.join(cwd, dir);
+        try {
+            const entries = fs.readdirSync(absDir, { recursive: true, withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                const ext = path.extname(entry.name);
+                if (!exts.has(ext))
+                    continue;
+                const baseName = entry.name.replace(/\.[^.]+$/, '');
+                const fullPath = path.join(absDir, entry.parentPath ? path.relative(absDir, entry.parentPath) : '', entry.name);
+                // Prefer src/ over dist/ for the same basename
+                if (!index.has(baseName) || fullPath.includes('/src/')) {
+                    index.set(baseName, fullPath);
+                }
+            }
+        }
+        catch { /* dir doesn't exist */ }
+    }
+    return index;
+}
 /**
  * Try to find the source file for a given module name.
  */
@@ -995,5 +1208,9 @@ function findSourceFile(moduleName) {
         if (fs.existsSync(candidate))
             return candidate;
     }
-    return null;
+    // Recursive search using cached file index
+    if (!fileIndex) {
+        fileIndex = buildFileIndex();
+    }
+    return fileIndex.get(moduleName) || null;
 }

package/dist/auto-register.js

@@ -44,7 +44,7 @@ function runGeneration(isFinal) {
             lastFunctionCount = count;
         }
         if (isFinal && lastFunctionCount > 0) {
-            console.log(`[trickle/auto] ${lastFunctionCount} function type(s) written to .d.ts`);
+            console.log(`[trickle/auto] ${lastFunctionCount} function type(s) written to .trickle/types/`);
             // Inject JSDoc into source files if TRICKLE_INJECT=1
             try {
                 const injected = (0, auto_codegen_1.injectTypes)();

package/dist/express.js

@@ -282,6 +282,7 @@ function trickleMiddleware(userOpts) {
         sampleRate: userOpts?.sampleRate ?? 1,
         maxDepth: userOpts?.maxDepth ?? 5,
     };
+    const debug = process.env.TRICKLE_DEBUG === '1' || process.env.TRICKLE_DEBUG === 'true';
     return function trickleMiddlewareHandler(req, res, next) {
         if (!opts.enabled) {
             next();
@@ -292,6 +293,9 @@ function trickleMiddleware(userOpts) {
             next();
             return;
         }
+        if (debug) {
+            console.log(`[trickle/middleware] Intercepting ${req.method} ${req.originalUrl || req.url}`);
+        }
         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.
@@ -314,6 +318,9 @@ function trickleMiddleware(userOpts) {
                 if (!captured) {
                     captured = true;
                     const routeName = getRouteName();
+                    if (debug) {
+                        console.log(`[trickle/middleware] Captured res.json for ${routeName}`);
+                    }
                     // 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);
@@ -322,6 +329,9 @@ function trickleMiddleware(userOpts) {
                 return originalJson.call(res, data);
             };
         }
+        else if (debug) {
+            console.log(`[trickle/middleware] res.json is not a function: ${typeof originalJson}`);
+        }
         // Intercept res.send()
         const originalSend = res.send;
         if (typeof originalSend === 'function') {
@@ -329,6 +339,9 @@ function trickleMiddleware(userOpts) {
                 if (!captured) {
                     captured = true;
                     const routeName = getRouteName();
+                    if (debug) {
+                        console.log(`[trickle/middleware] Captured res.send for ${routeName}`);
+                    }
                     const latestInput = extractRequestInput(req);
                     const output = typeof data === 'string' ? { __html: true } : data;
                     emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, output);