ertk 0.1.1 → 0.1.3

package/dist/cli.js

@@ -2,18 +2,18 @@
 import * as path from "node:path";
 import { loadConfig, resolveConfig } from "./config.js";
 import { runGenerate, runWatch } from "./generate.js";
-const HELP = `
-ertk — Easy RTK Query codegen
-
-Usage:
-  ertk generate          One-shot generation (skips if nothing changed)
-  ertk generate --watch  Watch mode with incremental regeneration
-  ertk init              Scaffold config file and directories
-  ertk --help            Show this help message
-
-Options:
-  --watch    Watch for endpoint file changes and regenerate
-  --help     Show help
+const HELP = `
+ertk — Easy RTK Query codegen
+
+Usage:
+  ertk generate          One-shot generation (skips if nothing changed)
+  ertk generate --watch  Watch mode with incremental regeneration
+  ertk init              Scaffold config file and directories
+  ertk --help            Show this help message
+
+Options:
+  --watch    Watch for endpoint file changes and regenerate
+  --help     Show help
 `.trim();
 async function main() {
     const args = process.argv.slice(2);
@@ -52,25 +52,25 @@ async function runInit() {
         console.log("ertk.config.ts already exists, skipping.");
     }
     else {
-        fs.writeFileSync(configPath, `import { defineConfig } from "ertk";
-
-export default defineConfig({
-\t// Directory containing endpoint definition files
-\tendpoints: "src/endpoints",
-
-\t// Directory for generated output (api.ts, store.ts, invalidation.ts)
-\tgenerated: "src/generated",
-
-\t// Base URL for RTK Query fetchBaseQuery
-\tbaseUrl: "/api",
-
-\t// Route generation (remove to skip route generation for client-only projects)
-\troutes: {
-\t\tdir: "src/app/api",
-\t\thandlerModule: "ertk/next",
-\t\tignoredRoutes: [],
-\t},
-});
+        fs.writeFileSync(configPath, `import { defineConfig } from "ertk";
+
+export default defineConfig({
+\t// Directory containing endpoint definition files
+\tendpoints: "src/endpoints",
+
+\t// Directory for generated output (api.ts, store.ts, invalidation.ts)
+\tgenerated: "src/generated",
+
+\t// Base URL for RTK Query fetchBaseQuery
+\tbaseUrl: "/api",
+
+\t// Route generation (remove to skip route generation for client-only projects)
+\troutes: {
+\t\tdir: "src/app/api",
+\t\thandlerModule: "ertk/next",
+\t\tignoredRoutes: [],
+\t},
+});
 `);
         console.log("Created ertk.config.ts");
     }

package/dist/generate.js

@@ -126,6 +126,18 @@ function parseEndpointFile(project, filePath, config) {
             .getInitializerOrThrow()
             .getText();
     }
+    // Extract maxRetries
+    const maxRetriesProp = configObj.getProperty("maxRetries");
+    let maxRetries = null;
+    if (maxRetriesProp) {
+        const val = parseInt(maxRetriesProp
+            .asKindOrThrow(SyntaxKind.PropertyAssignment)
+            .getInitializerOrThrow()
+            .getText(), 10);
+        if (!Number.isNaN(val) && val > 0) {
+            maxRetries = val;
+        }
+    }
     // Derive route path from file path
     const routePath = deriveRoutePath(filePath, config);
     const endpointType = method === "get" ? "query" : "mutation";
@@ -170,6 +182,7 @@ function parseEndpointFile(project, filePath, config) {
         providesTagsSource,
         invalidatesTagsSource,
         optimisticSource,
+        maxRetries,
         typeImports,
     };
 }
@@ -244,9 +257,15 @@ function generateApiTs(endpoints, config) {
         extractTagTypes(ep.providesTagsSource, tagTypes);
         extractTagTypes(ep.invalidatesTagsSource, tagTypes);
     }
+    const hasAnyRetries = endpoints.some((ep) => ep.maxRetries != null && ep.maxRetries > 0);
     const lines = [];
     lines.push("// AUTO-GENERATED by ERTK codegen. Do not edit.");
-    lines.push('import { createApi, fetchBaseQuery } from "@reduxjs/toolkit/query/react";');
+    if (hasAnyRetries) {
+        lines.push('import { createApi, fetchBaseQuery, retry } from "@reduxjs/toolkit/query/react";');
+    }
+    else {
+        lines.push('import { createApi, fetchBaseQuery } from "@reduxjs/toolkit/query/react";');
+    }
     // Add type imports
     for (const [importPath, types] of [...allTypeImports.entries()].sort()) {
         const typeList = [...types].sort().join(", ");
@@ -256,7 +275,17 @@ function generateApiTs(endpoints, config) {
     lines.push("export const api = createApi({");
     lines.push('\treducerPath: "api",');
     // baseQuery — use custom source if provided, otherwise default
-    if (config.baseQuery) {
+    // When retries are used, wrap with retry() and set maxRetries: 0 as default
+    // so only endpoints with explicit extraOptions.maxRetries will retry.
+    if (hasAnyRetries) {
+        if (config.baseQuery) {
+            lines.push(`\tbaseQuery: retry(${config.baseQuery}, { maxRetries: 0 }),`);
+        }
+        else {
+            lines.push(`\tbaseQuery: retry(fetchBaseQuery({ baseUrl: "${config.baseUrl}" }), { maxRetries: 0 }),`);
+        }
+    }
+    else if (config.baseQuery) {
         lines.push(`\tbaseQuery: ${config.baseQuery},`);
     }
     else {
@@ -309,6 +338,9 @@ function generateEndpointDef(ep) {
             lines.push(...onQueryStarted);
         }
     }
+    if (ep.maxRetries != null && ep.maxRetries > 0) {
+        lines.push(`\t\t\textraOptions: { maxRetries: ${ep.maxRetries} },`);
+    }
     lines.push("\t\t}),");
     return lines;
 }
@@ -420,33 +452,33 @@ function capitalize(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
 }
 function generateStoreTs() {
-    return `// AUTO-GENERATED by ERTK codegen. Do not edit.
-import { configureStore } from "@reduxjs/toolkit";
-import { api } from "./api";
-
-export const store = configureStore({
-\treducer: {
-\t\t[api.reducerPath]: api.reducer,
-\t},
-\tmiddleware: (getDefaultMiddleware) =>
-\t\tgetDefaultMiddleware().concat(api.middleware),
-});
-
-export type RootState = ReturnType<typeof store.getState>;
-export type AppDispatch = typeof store.dispatch;
+    return `// AUTO-GENERATED by ERTK codegen. Do not edit.
+import { configureStore } from "@reduxjs/toolkit";
+import { api } from "./api";
+
+export const store = configureStore({
+\treducer: {
+\t\t[api.reducerPath]: api.reducer,
+\t},
+\tmiddleware: (getDefaultMiddleware) =>
+\t\tgetDefaultMiddleware().concat(api.middleware),
+});
+
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
 `;
 }
 function generateInvalidationTs() {
-    return `// AUTO-GENERATED by ERTK codegen. Do not edit.
-import { api } from "./api";
-
-export function invalidateTags(
-\t...args: Parameters<typeof api.util.invalidateTags>
-) {
-\treturn api.util.invalidateTags(...args);
-}
-
-export const updateQueryData = api.util.updateQueryData;
+    return `// AUTO-GENERATED by ERTK codegen. Do not edit.
+import { api } from "./api";
+
+export function invalidateTags(
+\t...args: Parameters<typeof api.util.invalidateTags>
+) {
+\treturn api.util.invalidateTags(...args);
+}
+
+export const updateQueryData = api.util.updateQueryData;
 `;
 }
 function generateRouteFile(group, config) {

package/dist/next/index.d.ts

@@ -1,2 +1,3 @@
 export { configureHandler, createRouteHandler, type ErtkAuthAdapter, type ErtkErrorHandler, type ConfigureHandlerOptions, } from "./route-handler.js";
+export { InMemoryRateLimitAdapter, defaultKeyFn, type RateLimitAdapter, type RateLimitConfig, type RateLimitResult, } from "./rate-limit.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/next/index.js

@@ -1,2 +1,3 @@
 export { configureHandler, createRouteHandler, } from "./route-handler.js";
+export { InMemoryRateLimitAdapter, defaultKeyFn, } from "./rate-limit.js";
 //# sourceMappingURL=index.js.map

package/dist/next/rate-limit.d.ts

@@ -0,0 +1,78 @@
+/**
+ * ERTK Rate Limiting
+ *
+ * Pluggable rate limiting for server-side route handlers.
+ * Ships with an in-memory sliding window adapter suitable for
+ * single-process deployments. For multi-instance / serverless
+ * deployments (e.g., Vercel), provide a distributed adapter
+ * (Redis, Upstash, DynamoDB, etc.).
+ */
+/** Result of a rate limit check. */
+export interface RateLimitResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Total limit for the window */
+    limit: number;
+    /** Remaining requests in the current window */
+    remaining: number;
+    /** Unix timestamp (seconds) when the window resets */
+    resetAt: number;
+}
+/**
+ * Pluggable rate limiting adapter interface.
+ * Implement this for custom storage backends (Redis, Upstash, DynamoDB, etc.).
+ */
+export interface RateLimitAdapter {
+    /**
+     * Check and consume a rate limit token for the given key.
+     * @param key   Identifier for the rate limit bucket (typically IP or user ID)
+     * @param windowMs  Sliding window duration in milliseconds
+     * @param max   Maximum requests allowed in the window
+     */
+    check(key: string, windowMs: number, max: number): Promise<RateLimitResult>;
+}
+/** Rate limit configuration for `configureHandler()`. */
+export interface RateLimitConfig {
+    /** Sliding window duration in milliseconds (e.g., 60_000 for 1 minute) */
+    windowMs: number;
+    /** Maximum requests allowed within the window */
+    max: number;
+    /**
+     * Function to derive the rate limit key from a request.
+     * Receives the authenticated user when available.
+     * Default: extract client IP from standard proxy headers.
+     */
+    keyFn?: (req: Request, user?: {
+        id: string;
+    }) => string;
+    /**
+     * Rate limit storage adapter.
+     * Default: InMemoryRateLimitAdapter (suitable for single-process deployments).
+     */
+    adapter?: RateLimitAdapter;
+}
+/**
+ * Default key function: extracts client IP from standard proxy headers,
+ * falling back to a static key if no IP is available.
+ */
+export declare function defaultKeyFn(req: Request): string;
+/**
+ * In-memory sliding window rate limiter.
+ *
+ * Suitable for single-process deployments (e.g., a long-running Node.js server).
+ * State resets on process restart and is not shared across instances.
+ * For multi-instance or serverless deployments, use a distributed adapter.
+ *
+ * Periodically prunes expired entries to prevent memory leaks.
+ */
+export declare class InMemoryRateLimitAdapter implements RateLimitAdapter {
+    private windows;
+    private pruneIntervalMs;
+    private lastPrune;
+    constructor(options?: {
+        pruneIntervalMs?: number;
+    });
+    check(key: string, windowMs: number, max: number): Promise<RateLimitResult>;
+    private maybePrune;
+}
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/next/rate-limit.js

@@ -0,0 +1,73 @@
+/**
+ * ERTK Rate Limiting
+ *
+ * Pluggable rate limiting for server-side route handlers.
+ * Ships with an in-memory sliding window adapter suitable for
+ * single-process deployments. For multi-instance / serverless
+ * deployments (e.g., Vercel), provide a distributed adapter
+ * (Redis, Upstash, DynamoDB, etc.).
+ */
+// ─── Default Key Function ─────────────────────────────────────
+/**
+ * Default key function: extracts client IP from standard proxy headers,
+ * falling back to a static key if no IP is available.
+ */
+export function defaultKeyFn(req) {
+    const forwarded = req.headers.get("x-forwarded-for");
+    if (forwarded) {
+        return forwarded.split(",")[0].trim();
+    }
+    const realIp = req.headers.get("x-real-ip");
+    if (realIp)
+        return realIp.trim();
+    return "unknown";
+}
+/**
+ * In-memory sliding window rate limiter.
+ *
+ * Suitable for single-process deployments (e.g., a long-running Node.js server).
+ * State resets on process restart and is not shared across instances.
+ * For multi-instance or serverless deployments, use a distributed adapter.
+ *
+ * Periodically prunes expired entries to prevent memory leaks.
+ */
+export class InMemoryRateLimitAdapter {
+    windows = new Map();
+    pruneIntervalMs;
+    lastPrune = Date.now();
+    constructor(options) {
+        this.pruneIntervalMs = options?.pruneIntervalMs ?? 60_000;
+    }
+    async check(key, windowMs, max) {
+        const now = Date.now();
+        this.maybePrune(now, windowMs);
+        let entry = this.windows.get(key);
+        if (!entry) {
+            entry = { timestamps: [] };
+            this.windows.set(key, entry);
+        }
+        // Remove timestamps outside the current window
+        const windowStart = now - windowMs;
+        entry.timestamps = entry.timestamps.filter((t) => t > windowStart);
+        const resetAt = Math.ceil((now + windowMs) / 1000);
+        if (entry.timestamps.length >= max) {
+            return { allowed: false, limit: max, remaining: 0, resetAt };
+        }
+        entry.timestamps.push(now);
+        const remaining = max - entry.timestamps.length;
+        return { allowed: true, limit: max, remaining, resetAt };
+    }
+    maybePrune(now, windowMs) {
+        if (now - this.lastPrune < this.pruneIntervalMs)
+            return;
+        this.lastPrune = now;
+        const cutoff = now - windowMs;
+        for (const [key, entry] of this.windows) {
+            entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+            if (entry.timestamps.length === 0) {
+                this.windows.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/next/route-handler.d.ts

@@ -6,6 +6,7 @@
  * auth or database implementation.
  */
 import type { EndpointDefinition } from "../types.js";
+import { type RateLimitConfig } from "./rate-limit.js";
 /**
  * Auth adapter interface. Consumers implement this to provide
  * user resolution for protected endpoints.
@@ -37,6 +38,12 @@ export interface ConfigureHandlerOptions {
     auth?: ErtkAuthAdapter;
     /** Custom error handlers, processed in order. First non-null response wins. */
     errorHandlers?: ErtkErrorHandler[];
+    /**
+     * Global rate limiting configuration.
+     * Applied to all endpoints unless overridden per-endpoint.
+     * Omit to disable rate limiting entirely.
+     */
+    rateLimit?: RateLimitConfig;
 }
 /**
  * Create a configured route handler factory. Call this once with your

package/dist/next/route-handler.js

@@ -5,6 +5,7 @@
  * Next.js App Router route handlers. Decoupled from any specific
  * auth or database implementation.
  */
+import { defaultKeyFn, InMemoryRateLimitAdapter, } from "./rate-limit.js";
 // ─── Validation Error ─────────────────────────────────────────
 class ValidationError extends Error {
     issues;
@@ -25,8 +26,7 @@ async function parseAndValidateRequest(req, schema) {
         const url = new URL(req.url);
         const params = {};
         url.searchParams.forEach((value, key) => {
-            const numValue = Number(value);
-            params[key] = Number.isNaN(numValue) ? value : numValue;
+            params[key] = value;
         });
         try {
             const data = schema.parse(params);
@@ -82,6 +82,38 @@ function jsonResponse(data, status = 200) {
 function errorResponse(message, status) {
     return jsonResponse({ error: message }, status);
 }
+// ─── Rate Limiting ────────────────────────────────────────────
+let defaultAdapter = null;
+function getDefaultAdapter() {
+    if (!defaultAdapter) {
+        defaultAdapter = new InMemoryRateLimitAdapter();
+    }
+    return defaultAdapter;
+}
+async function applyRateLimit(req, user, globalConfig, endpointOverride) {
+    if (!globalConfig && !endpointOverride)
+        return null;
+    const windowMs = endpointOverride?.windowMs ?? globalConfig.windowMs;
+    const max = endpointOverride?.max ?? globalConfig.max;
+    const keyFn = globalConfig?.keyFn ?? defaultKeyFn;
+    const adapter = globalConfig?.adapter ?? getDefaultAdapter();
+    const key = keyFn(req, user);
+    const result = await adapter.check(key, windowMs, max);
+    if (!result.allowed) {
+        const retryAfter = Math.ceil((result.resetAt * 1000 - Date.now()) / 1000);
+        return new Response(JSON.stringify({ error: "Too many requests" }), {
+            status: 429,
+            headers: {
+                "Content-Type": "application/json",
+                "Retry-After": String(Math.max(1, retryAfter)),
+                "X-RateLimit-Limit": String(result.limit),
+                "X-RateLimit-Remaining": "0",
+                "X-RateLimit-Reset": String(result.resetAt),
+            },
+        });
+    }
+    return null;
+}
 // ─── Route Handler Factory ───────────────────────────────────
 /**
  * Create a configured route handler factory. Call this once with your
@@ -120,7 +152,7 @@ export function configureHandler(options = {}) {
                 // Parse and validate request
                 const { body, query } = await parseAndValidateRequest(req, def.request);
                 // Resolve user for protected endpoints
-                let user = undefined;
+                let user = null;
                 if (def.protected) {
                     if (!options.auth) {
                         return errorResponse("No auth adapter configured for protected endpoint", 500);
@@ -130,12 +162,18 @@ export function configureHandler(options = {}) {
                         return errorResponse("Unauthorized", 401);
                     }
                 }
+                // Rate limiting
+                if (options.rateLimit || def.rateLimit) {
+                    const rateLimitResponse = await applyRateLimit(req, user, options.rateLimit, def.rateLimit);
+                    if (rateLimitResponse)
+                        return rateLimitResponse;
+                }
                 // Call the endpoint handler
                 if (!def.handler) {
                     return errorResponse("No handler defined for this endpoint", 501);
                 }
                 const result = await def.handler({
-                    user: (user ?? { id: "" }),
+                    user: user ?? null,
                     body,
                     query,
                     params,
@@ -163,7 +201,10 @@ export function configureHandler(options = {}) {
                 if (error instanceof Error &&
                     "status" in error &&
                     typeof error.status === "number") {
-                    return errorResponse(error.message || "An error occurred", error.status);
+                    const status = error.status;
+                    const isClientSafe = "expose" in error &&
+                        error.expose === true;
+                    return errorResponse(isClientSafe ? error.message : "An error occurred", status);
                 }
                 // Generic error
                 if (error instanceof Error) {

package/dist/types.d.ts

@@ -34,7 +34,7 @@ export interface DefaultUser {
  * Context passed to endpoint handlers on the server side.
  */
 export interface HandlerContext<TBody = unknown, TQuery = unknown, TUser = DefaultUser> {
-    user: TUser;
+    user: TUser | null;
     body: TBody;
     query: TQuery;
     params: Record<string, string>;
@@ -69,6 +69,22 @@ export interface EndpointDefinition<TResponse = unknown, TArgs = void> {
     };
     /** Optimistic update configuration */
     optimistic?: SingleOptimistic<TArgs> | MultiOptimistic<TArgs>;
+    /**
+     * Maximum number of retry attempts for transient failures (5xx, network errors, 408, 429).
+     * Uses RTK Query's built-in `retry` utility with exponential backoff.
+     * 0 or undefined means no retries. A value of 2 means up to 3 total attempts.
+     * Client-side only — does not affect server-side route handlers.
+     */
+    maxRetries?: number;
+    /**
+     * Per-endpoint rate limit override for the server-side route handler.
+     * Overrides the global `rateLimit` config from `configureHandler()`.
+     * Only `windowMs` and `max` can be overridden; `keyFn` and `adapter` come from the global config.
+     */
+    rateLimit?: {
+        windowMs: number;
+        max: number;
+    };
     /**
      * Server-side handler. Optional — omit for client-only endpoints
      * that consume an external API.