trickle-backend 0.1.0

package/dist/services/sse-broker.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sseBroker = void 0;
+const events_1 = require("events");
+class SseBroker extends events_1.EventEmitter {
+    clients = [];
+    addClient(res, filter) {
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+            "X-Accel-Buffering": "no",
+        });
+        res.write(":\n\n"); // initial comment to establish connection
+        const client = { res, filter };
+        this.clients.push(client);
+        res.on("close", () => {
+            this.removeClient(res);
+        });
+    }
+    removeClient(res) {
+        this.clients = this.clients.filter((c) => c.res !== res);
+    }
+    broadcast(event, data) {
+        const payload = JSON.stringify(data);
+        const functionName = typeof data === "object" && data !== null && "functionName" in data
+            ? data.functionName
+            : undefined;
+        for (const client of this.clients) {
+            if (client.filter && functionName) {
+                if (!functionName.includes(client.filter)) {
+                    continue;
+                }
+            }
+            client.res.write(`event: ${event}\ndata: ${payload}\n\n`);
+        }
+    }
+}
+exports.sseBroker = new SseBroker();

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

@@ -0,0 +1,2 @@
+import { TypeNode, TypeDiff } from "../types";
+export declare function diffTypes(from: TypeNode, to: TypeNode, basePath?: string): TypeDiff[];

package/dist/services/type-differ.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffTypes = diffTypes;
+function diffTypes(from, to, basePath = "") {
+    const diffs = [];
+    if (from.kind !== to.kind) {
+        diffs.push({ kind: "changed", path: basePath || "(root)", from, to });
+        return diffs;
+    }
+    switch (from.kind) {
+        case "primitive": {
+            const toNode = to;
+            if (from.name !== toNode.name) {
+                diffs.push({ kind: "changed", path: basePath || "(root)", from, to });
+            }
+            break;
+        }
+        case "object": {
+            const toNode = to;
+            const fromKeys = new Set(Object.keys(from.properties));
+            const toKeys = new Set(Object.keys(toNode.properties));
+            for (const key of fromKeys) {
+                const childPath = basePath ? `${basePath}.${key}` : key;
+                if (!toKeys.has(key)) {
+                    diffs.push({ kind: "removed", path: childPath, type: from.properties[key] });
+                }
+                else {
+                    diffs.push(...diffTypes(from.properties[key], toNode.properties[key], childPath));
+                }
+            }
+            for (const key of toKeys) {
+                if (!fromKeys.has(key)) {
+                    const childPath = basePath ? `${basePath}.${key}` : key;
+                    diffs.push({ kind: "added", path: childPath, type: toNode.properties[key] });
+                }
+            }
+            break;
+        }
+        case "array": {
+            const toNode = to;
+            diffs.push(...diffTypes(from.element, toNode.element, `${basePath || "(root)"}[]`));
+            break;
+        }
+        case "union": {
+            const toNode = to;
+            const fromSerialized = from.members.map((m) => JSON.stringify(m));
+            const toSerialized = toNode.members.map((m) => JSON.stringify(m));
+            const fromSet = new Set(fromSerialized);
+            const toSet = new Set(toSerialized);
+            for (let i = 0; i < fromSerialized.length; i++) {
+                if (!toSet.has(fromSerialized[i])) {
+                    diffs.push({
+                        kind: "removed",
+                        path: `${basePath || "(root)"}|[${i}]`,
+                        type: from.members[i],
+                    });
+                }
+            }
+            for (let i = 0; i < toSerialized.length; i++) {
+                if (!fromSet.has(toSerialized[i])) {
+                    diffs.push({
+                        kind: "added",
+                        path: `${basePath || "(root)"}|[${i}]`,
+                        type: toNode.members[i],
+                    });
+                }
+            }
+            break;
+        }
+        case "function": {
+            const toNode = to;
+            const maxParams = Math.max(from.params.length, toNode.params.length);
+            for (let i = 0; i < maxParams; i++) {
+                const paramPath = `${basePath || "(root)"}.params[${i}]`;
+                if (i >= from.params.length) {
+                    diffs.push({ kind: "added", path: paramPath, type: toNode.params[i] });
+                }
+                else if (i >= toNode.params.length) {
+                    diffs.push({ kind: "removed", path: paramPath, type: from.params[i] });
+                }
+                else {
+                    diffs.push(...diffTypes(from.params[i], toNode.params[i], paramPath));
+                }
+            }
+            diffs.push(...diffTypes(from.returnType, toNode.returnType, `${basePath || "(root)"}.return`));
+            break;
+        }
+        case "promise": {
+            const toNode = to;
+            diffs.push(...diffTypes(from.resolved, toNode.resolved, `${basePath || "(root)"}<resolved>`));
+            break;
+        }
+        case "map": {
+            const toNode = to;
+            diffs.push(...diffTypes(from.key, toNode.key, `${basePath || "(root)"}<key>`));
+            diffs.push(...diffTypes(from.value, toNode.value, `${basePath || "(root)"}<value>`));
+            break;
+        }
+        case "set": {
+            const toNode = to;
+            diffs.push(...diffTypes(from.element, toNode.element, `${basePath || "(root)"}<element>`));
+            break;
+        }
+        case "tuple": {
+            const toNode = to;
+            const maxLen = Math.max(from.elements.length, toNode.elements.length);
+            for (let i = 0; i < maxLen; i++) {
+                const elPath = `${basePath || "(root)"}[${i}]`;
+                if (i >= from.elements.length) {
+                    diffs.push({ kind: "added", path: elPath, type: toNode.elements[i] });
+                }
+                else if (i >= toNode.elements.length) {
+                    diffs.push({ kind: "removed", path: elPath, type: from.elements[i] });
+                }
+                else {
+                    diffs.push(...diffTypes(from.elements[i], toNode.elements[i], elPath));
+                }
+            }
+            break;
+        }
+        case "unknown":
+            // Both unknown — no diff
+            break;
+    }
+    return diffs;
+}

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

@@ -0,0 +1,319 @@
+import { TypeNode } from "../types";
+/**
+ * Accumulates extracted named interfaces so complex nested objects
+ * get their own `export interface Foo { ... }` block.
+ */
+interface ExtractedInterface {
+    name: string;
+    node: Extract<TypeNode, {
+        kind: "object";
+    }>;
+}
+/**
+ * Convert a TypeNode to a TypeScript type string.
+ *
+ * Large nested objects (>2 properties) are extracted into named interfaces
+ * so the output stays readable.
+ */
+declare function typeNodeToTS(node: TypeNode, extracted: ExtractedInterface[], parentName: string, propName: string | undefined, indent: number): string;
+/**
+ * Generate TypeScript definitions for a single function.
+ *
+ * For a function `processOrder(order)` that takes an object and returns an object:
+ * ```ts
+ * export interface ProcessOrderInput { id: string; customer: Customer; ... }
+ * export interface ProcessOrderOutput { orderId: string; total: number; ... }
+ * export declare function processOrder(order: ProcessOrderInput): ProcessOrderOutput;
+ * ```
+ */
+export declare function generateFunctionTypes(functionName: string, argsType: TypeNode, returnType: TypeNode, meta?: {
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}): string;
+/**
+ * Generate a complete TypeScript declarations file for all functions.
+ */
+export declare function generateAllTypes(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+export declare function generatePythonTypes(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate a fully-typed fetch-based API client from runtime-observed routes.
+ *
+ * Output is a single TypeScript file with:
+ * - All request/response interfaces
+ * - A `createTrickleClient(baseUrl)` factory that returns typed fetch wrappers
+ * - Proper path parameter substitution
+ * - Request body typing for POST/PUT/PATCH
+ */
+export declare function generateApiClient(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate an OpenAPI 3.0 specification from runtime-observed route types.
+ */
+export declare function generateOpenApiSpec(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>, options?: {
+    title?: string;
+    version?: string;
+    serverUrl?: string;
+}): object;
+/**
+ * Generate typed Express handler type aliases from runtime-observed routes.
+ *
+ * For each route like `GET /api/users/:id`, produces:
+ * - `GetApiUsersIdHandler` — a fully typed `RequestHandler` with
+ *   `Request<Params, ResBody, ReqBody, Query>` and `Response<ResBody>`
+ *
+ * Developers can use these to type their route handlers:
+ *   app.get('/api/users/:id', ((req, res) => { ... }) as GetApiUsersIdHandler);
+ */
+export declare function generateHandlerTypes(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate Zod validation schemas from runtime-observed types.
+ *
+ * For each function/route, generates a named Zod schema that can be used for:
+ * - Runtime validation of API inputs/outputs
+ * - TypeScript type inference via `z.infer<typeof schema>`
+ * - Form validation, config parsing, etc.
+ */
+export declare function generateZodSchemas(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate fully-typed TanStack Query (React Query) hooks from runtime-observed routes.
+ *
+ * For each route:
+ * - GET → useQuery hook with typed response and query keys
+ * - POST/PUT/PATCH/DELETE → useMutation hook with typed input/output
+ * - Query key factory for cache invalidation
+ * - All request/response interfaces included
+ */
+export declare function generateReactQueryHooks(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate TypeScript type guard functions from runtime-observed types.
+ *
+ * For each route:
+ * - `isGetApiUsersResponse(value): value is GetApiUsersResponse`
+ * - `isPostApiUsersRequest(value): value is PostApiUsersRequest`
+ *
+ * Type guards perform structural checks: verify typeof, key existence,
+ * array shapes, and nested object structure.
+ */
+export declare function generateTypeGuards(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate Express validation middleware from runtime-observed types.
+ *
+ * For each POST/PUT/PATCH route, generates middleware that:
+ * - Validates request body structure and types
+ * - Returns 400 with structured errors on failure
+ * - Passes through to next() on success
+ *
+ * Self-contained — no external validation library required.
+ */
+export declare function generateMiddleware(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate Mock Service Worker (MSW) request handlers from observed API routes.
+ *
+ * Output:
+ * - Import from 'msw'
+ * - Response type interfaces for each route
+ * - Individual handler exports (e.g. getApiUsersHandler)
+ * - A combined `handlers` array for setupServer/setupWorker
+ */
+export declare function generateMswHandlers(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate JSON Schema definitions from observed runtime types.
+ *
+ * Output is a single JSON object with $defs for each route/function's
+ * request and response types, suitable for use with ajv, joi, or any
+ * JSON Schema-compatible validator.
+ */
+export declare function generateJsonSchemas(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate typed SWR hooks from observed API routes.
+ *
+ * Output:
+ * - Import from 'swr' and 'swr/mutation'
+ * - Response/input type interfaces
+ * - A configurable fetcher
+ * - useSWR hooks for GET routes
+ * - useSWRMutation hooks for POST/PUT/PATCH/DELETE routes
+ */
+export declare function generateSwrHooks(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate Pydantic BaseModel classes from observed runtime types.
+ *
+ * Unlike --python (TypedDict), Pydantic models provide:
+ * - Runtime validation (model_validate)
+ * - JSON serialization (model_dump_json)
+ * - JSON Schema generation (model_json_schema)
+ * - Direct use as FastAPI request/response models
+ */
+export declare function generatePydanticModels(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate class-validator DTO classes from observed runtime types.
+ *
+ * Output: NestJS-ready DTOs with class-validator decorators for
+ * request validation and class-transformer for nested object support.
+ */
+export declare function generateClassValidatorDtos(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate a GraphQL SDL schema from runtime-observed API routes.
+ *
+ * Converts REST routes into Query (GET) and Mutation (POST/PUT/PATCH/DELETE)
+ * fields with properly typed inputs and outputs.
+ */
+export declare function generateGraphqlSchema(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate a fully-typed tRPC router from runtime-observed API routes.
+ *
+ * - GET routes → t.procedure.query()
+ * - POST/PUT/PATCH/DELETE routes → t.procedure.input(zodSchema).mutation()
+ * - Includes Zod input schemas for request body validation
+ * - Includes TypeScript return type annotations from observed responses
+ * - Exports AppRouter type for client-side type inference
+ */
+export declare function generateTrpcRouter(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate a typed Axios client from runtime-observed API routes.
+ *
+ * For each route:
+ * - Request/response interfaces
+ * - Typed function using axios.get/post/put/patch/delete
+ * - Path parameter interpolation
+ * - Query parameter support
+ * - Configurable base URL and axios instance
+ */
+export declare function generateAxiosClient(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+    env?: string;
+    observedAt?: string;
+}>): string;
+/**
+ * Generate compact inline type annotations for annotating source code.
+ * Unlike generateFunctionTypes which emits full interfaces, this produces
+ * minimal inline annotations suitable for inserting into source files.
+ */
+export declare function generateInlineAnnotations(functions: Array<{
+    name: string;
+    argsType: TypeNode;
+    returnType: TypeNode;
+    module?: string;
+}>, language?: "typescript" | "python"): Record<string, {
+    params: Array<{
+        name: string;
+        type: string;
+    }>;
+    returnType: string;
+}>;
+export { typeNodeToTS as typeNodeToTSPublic };