trickle-backend 0.1.0 → 0.1.1

package/dist/routes/codegen.js

@@ -48,6 +48,8 @@ function collectFunctionTypes(opts) {
             module: moduleName,
             env: snapshot.env || environment,
             observedAt: snapshot.observed_at,
+            sampleInput: snapshot.sample_input ? tryParseJson(snapshot.sample_input) : undefined,
+            sampleOutput: snapshot.sample_output ? tryParseJson(snapshot.sample_output) : undefined,
         });
     }
     return results;

package/dist/services/type-generator.d.ts

@@ -30,6 +30,8 @@ export declare function generateFunctionTypes(functionName: string, argsType: Ty
     module?: string;
     env?: string;
     observedAt?: string;
+    sampleInput?: unknown;
+    sampleOutput?: unknown;
 }): string;
 /**
  * Generate a complete TypeScript declarations file for all functions.
@@ -41,6 +43,8 @@ export declare function generateAllTypes(functions: Array<{
     module?: string;
     env?: string;
     observedAt?: string;
+    sampleInput?: unknown;
+    sampleOutput?: unknown;
 }>): string;
 export declare function generatePythonTypes(functions: Array<{
     name: string;

package/dist/services/type-generator.js

@@ -264,13 +264,39 @@ function generateFunctionTypes(functionName, argsType, returnType, meta) {
         });
         funcDecl = `export declare function ${funcIdent}(${params.join(", ")}): ${outputName};`;
     }
+    // ── Build @example JSDoc from sample data ──
+    const exampleLines = [];
+    if (meta?.sampleInput !== undefined || meta?.sampleOutput !== undefined) {
+        exampleLines.push(`/**`);
+        if (meta?.sampleInput !== undefined) {
+            exampleLines.push(` * @example`);
+            exampleLines.push(` * // Sample input:`);
+            const inputStr = JSON.stringify(meta.sampleInput, null, 2);
+            for (const line of inputStr.split('\n')) {
+                exampleLines.push(` * ${line}`);
+            }
+        }
+        if (meta?.sampleOutput !== undefined) {
+            if (!meta?.sampleInput)
+                exampleLines.push(` * @example`);
+            exampleLines.push(` * // Sample output:`);
+            const outputStr = JSON.stringify(meta.sampleOutput, null, 2);
+            for (const line of outputStr.split('\n')) {
+                exampleLines.push(` * ${line}`);
+            }
+        }
+        exampleLines.push(` */`);
+    }
     // ── Assemble output ──
-    // Order: extracted interfaces → input → output → function declaration
+    // Order: extracted interfaces → input → output → JSDoc with examples → function declaration
     const result = [];
     if (extractedLines.length > 0) {
         result.push(...extractedLines);
     }
     result.push(...lines);
+    if (exampleLines.length > 0) {
+        result.push(...exampleLines);
+    }
     result.push(funcDecl);
     return result.join("\n");
 }
@@ -288,6 +314,8 @@ function generateAllTypes(functions) {
             module: fn.module,
             env: fn.env,
             observedAt: fn.observedAt,
+            sampleInput: fn.sampleInput,
+            sampleOutput: fn.sampleOutput,
         }));
         sections.push("");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-backend",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "dist/index.js",
   "scripts": {
     "build": "tsc",

package/src/routes/codegen.ts

@@ -13,6 +13,8 @@ interface FunctionTypeData {
   module?: string;
   env?: string;
   observedAt?: string;
+  sampleInput?: unknown;
+  sampleOutput?: unknown;
 }
 
 function tryParseJson(value: string): unknown {
@@ -65,6 +67,8 @@ function collectFunctionTypes(opts: {
       module: moduleName,
       env: (snapshot.env as string) || environment,
       observedAt: snapshot.observed_at as string,
+      sampleInput: snapshot.sample_input ? tryParseJson(snapshot.sample_input as string) : undefined,
+      sampleOutput: snapshot.sample_output ? tryParseJson(snapshot.sample_output as string) : undefined,
     });
   }
 

package/src/services/type-generator.ts

@@ -178,7 +178,7 @@ export function generateFunctionTypes(
   functionName: string,
   argsType: TypeNode,
   returnType: TypeNode,
-  meta?: { module?: string; env?: string; observedAt?: string },
+  meta?: { module?: string; env?: string; observedAt?: string; sampleInput?: unknown; sampleOutput?: unknown },
 ): string {
   const baseName = toPascalCase(functionName);
   const extracted: ExtractedInterface[] = [];
@@ -298,14 +298,41 @@ export function generateFunctionTypes(
     funcDecl = `export declare function ${funcIdent}(${params.join(", ")}): ${outputName};`;
   }
 
+  // ── Build @example JSDoc from sample data ──
+
+  const exampleLines: string[] = [];
+  if (meta?.sampleInput !== undefined || meta?.sampleOutput !== undefined) {
+    exampleLines.push(`/**`);
+    if (meta?.sampleInput !== undefined) {
+      exampleLines.push(` * @example`);
+      exampleLines.push(` * // Sample input:`);
+      const inputStr = JSON.stringify(meta.sampleInput, null, 2);
+      for (const line of inputStr.split('\n')) {
+        exampleLines.push(` * ${line}`);
+      }
+    }
+    if (meta?.sampleOutput !== undefined) {
+      if (!meta?.sampleInput) exampleLines.push(` * @example`);
+      exampleLines.push(` * // Sample output:`);
+      const outputStr = JSON.stringify(meta.sampleOutput, null, 2);
+      for (const line of outputStr.split('\n')) {
+        exampleLines.push(` * ${line}`);
+      }
+    }
+    exampleLines.push(` */`);
+  }
+
   // ── Assemble output ──
-  // Order: extracted interfaces → input → output → function declaration
+  // Order: extracted interfaces → input → output → JSDoc with examples → function declaration
 
   const result: string[] = [];
   if (extractedLines.length > 0) {
     result.push(...extractedLines);
   }
   result.push(...lines);
+  if (exampleLines.length > 0) {
+    result.push(...exampleLines);
+  }
   result.push(funcDecl);
 
   return result.join("\n");
@@ -322,6 +349,8 @@ export function generateAllTypes(
     module?: string;
     env?: string;
     observedAt?: string;
+    sampleInput?: unknown;
+    sampleOutput?: unknown;
   }>,
 ): string {
   const sections: string[] = [];
@@ -337,6 +366,8 @@ export function generateAllTypes(
         module: fn.module,
         env: fn.env,
         observedAt: fn.observedAt,
+        sampleInput: fn.sampleInput,
+        sampleOutput: fn.sampleOutput,
       }),
     );
     sections.push("");