ts-typed-api 0.1.3 → 0.1.5

package/BROWSER_USAGE.md

@@ -0,0 +1,133 @@
+# Browser Usage Guide
+
+This guide explains how to use `ts-typed-api` in browser environments without including server-side dependencies.
+
+## Problem
+
+When using the main package import in browsers, you might encounter issues with Node.js-specific dependencies like `busboy` and `multer` that are used for server-side file uploads. These dependencies reference Node.js APIs like `Buffer` that don't exist in browsers.
+
+## Solution
+
+The package now provides separate entry points for client-side and server-side code:
+
+### Client-Only Import (Browser-Safe)
+
+```typescript
+// ✅ Browser-safe import - no server dependencies
+import { ApiClient, CreateApiDefinition, CreateResponses } from 'ts-typed-api/client';
+```
+
+This import includes:
+- `ApiClient` - HTTP client for making API calls
+- `CreateApiDefinition` - Function to define API structure
+- `CreateResponses` - Function to define response schemas
+- All necessary types for client-side usage
+- Zod for validation
+
+This import **does NOT include**:
+- `RegisterHandlers` (server-side)
+- `UploadedFile` type (server-side)
+- Express/Multer dependencies
+- Any Node.js-specific code
+
+### Server-Only Import
+
+```typescript
+// Server-side import - includes server dependencies
+import { RegisterHandlers, UploadedFile } from 'ts-typed-api/server';
+```
+
+### Full Import (Node.js Only)
+
+```typescript
+// Traditional import - includes everything (Node.js only)
+import { ApiClient, RegisterHandlers } from 'ts-typed-api';
+```
+
+## Example Usage
+
+### Browser Client
+
+```typescript
+import { ApiClient, CreateApiDefinition, CreateResponses } from 'ts-typed-api/client';
+import { z } from 'zod';
+
+const ApiDefinition = CreateApiDefinition({
+    prefix: '/api',
+    endpoints: {
+        users: {
+            getUser: {
+                path: '/users/:id',
+                method: 'GET',
+                params: z.object({ id: z.string() }),
+                responses: CreateResponses({
+                    200: z.object({
+                        id: z.string(),
+                        name: z.string(),
+                        email: z.string()
+                    })
+                })
+            }
+        }
+    }
+});
+
+const client = new ApiClient('http://localhost:3000', ApiDefinition);
+
+// Use in browser
+const result = await client.callApi('users', 'getUser', 
+    { params: { id: '123' } },
+    {
+        200: ({ data }) => data,
+        422: ({ error }) => { throw new Error('Validation failed'); }
+    }
+);
+```
+
+### Server Implementation
+
+```typescript
+import express from 'express';
+import { RegisterHandlers } from 'ts-typed-api/server';
+// Import the same ApiDefinition used by the client
+
+const app = express();
+
+RegisterHandlers(app, ApiDefinition, {
+    users: {
+        getUser: async (req, res) => {
+            const { id } = req.params;
+            // ... server logic
+            res.respond(200, { id, name: 'John', email: 'john@example.com' });
+        }
+    }
+});
+```
+
+## Bundle Size Benefits
+
+Using the client-only import significantly reduces bundle size for browser applications by excluding:
+- Express framework
+- Multer file upload middleware
+- Busboy multipart parser
+- Other Node.js-specific dependencies
+
+## Migration Guide
+
+If you're currently using the main import in browser code:
+
+**Before:**
+```typescript
+import { ApiClient } from 'ts-typed-api';
+```
+
+**After:**
+```typescript
+import { ApiClient } from 'ts-typed-api/client';
+```
+
+The API remains exactly the same - only the import path changes.
+
+## TypeScript Support
+
+All imports provide full TypeScript support with proper type inference and autocompletion.

package/dist/client-only.d.ts

@@ -0,0 +1,5 @@
+export { ApiClient, FetchHttpClientAdapter } from './client';
+export { CreateApiDefinition, CreateResponses } from './definition';
+export { z as ZodSchema } from 'zod';
+export type { ApiDefinitionSchema, RouteSchema, UnifiedError, InferDataFromUnifiedResponse, ApiClientParams, ApiClientQuery, ApiClientBody, ApiResponse, ApiBody, ApiParams, ApiQuery, FileType, HttpSuccessStatusCode, HttpClientErrorStatusCode, HttpServerErrorStatusCode, AllowedInputStatusCode, AllowedResponseStatusCode } from './definition';
+export type { HttpRequestOptions, HttpResponse, HttpClientAdapter, ApiCallResult, CallApiOptions } from './client';

package/dist/client-only.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZodSchema = exports.CreateResponses = exports.CreateApiDefinition = exports.FetchHttpClientAdapter = exports.ApiClient = void 0;
+// Client-only exports - no server dependencies
+var client_1 = require("./client");
+Object.defineProperty(exports, "ApiClient", { enumerable: true, get: function () { return client_1.ApiClient; } });
+Object.defineProperty(exports, "FetchHttpClientAdapter", { enumerable: true, get: function () { return client_1.FetchHttpClientAdapter; } });
+var definition_1 = require("./definition");
+Object.defineProperty(exports, "CreateApiDefinition", { enumerable: true, get: function () { return definition_1.CreateApiDefinition; } });
+Object.defineProperty(exports, "CreateResponses", { enumerable: true, get: function () { return definition_1.CreateResponses; } });
+var zod_1 = require("zod");
+Object.defineProperty(exports, "ZodSchema", { enumerable: true, get: function () { return zod_1.z; } });

package/dist/server-only.d.ts

@@ -0,0 +1,5 @@
+export { RegisterHandlers, EndpointMiddleware } from './object-handlers';
+export { File as UploadedFile } from './router';
+export { createRouteHandler, makeRouteHandlerCreator } from './router';
+export type { TypedRequest, TypedResponse } from './router';
+export type { ObjectHandlers } from './object-handlers';

package/dist/server-only.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeRouteHandlerCreator = exports.createRouteHandler = exports.RegisterHandlers = void 0;
+// Server-only exports - includes server dependencies
+var object_handlers_1 = require("./object-handlers");
+Object.defineProperty(exports, "RegisterHandlers", { enumerable: true, get: function () { return object_handlers_1.RegisterHandlers; } });
+var router_1 = require("./router");
+Object.defineProperty(exports, "createRouteHandler", { enumerable: true, get: function () { return router_1.createRouteHandler; } });
+Object.defineProperty(exports, "makeRouteHandlerCreator", { enumerable: true, get: function () { return router_1.makeRouteHandlerCreator; } });

package/examples/browser-client-example.ts

@@ -0,0 +1,94 @@
+// Example of using the client-only import for browser environments
+// This import will NOT include server dependencies like multer/busboy
+
+import { ApiClient, CreateApiDefinition, CreateResponses } from 'ts-typed-api/client';
+import { z } from 'zod';
+
+// Define a simple API (this would typically be shared between client and server)
+const ApiDefinition = CreateApiDefinition({
+    prefix: '/api',
+    endpoints: {
+        users: {
+            getUser: {
+                path: '/users/:id',
+                method: 'GET',
+                params: z.object({
+                    id: z.string()
+                }),
+                responses: CreateResponses({
+                    200: z.object({
+                        id: z.string(),
+                        name: z.string(),
+                        email: z.string()
+                    })
+                })
+            },
+            createUser: {
+                path: '/users',
+                method: 'POST',
+                body: z.object({
+                    name: z.string(),
+                    email: z.string()
+                }),
+                responses: CreateResponses({
+                    201: z.object({
+                        id: z.string(),
+                        name: z.string(),
+                        email: z.string()
+                    })
+                })
+            }
+        }
+    }
+});
+
+// Create client instance
+const client = new ApiClient('http://localhost:3000', ApiDefinition);
+
+// Example usage in browser
+async function exampleUsage() {
+    try {
+        // Get a user
+        const getUserResult = await client.callApi('users', 'getUser',
+            { params: { id: '123' } },
+            {
+                200: ({ data }) => {
+                    console.log('User found:', data);
+                    return data;
+                },
+                422: ({ error }) => {
+                    console.error('Validation error:', error);
+                    throw new Error('Validation failed');
+                }
+            }
+        );
+
+        // Create a user
+        const createUserResult = await client.callApi('users', 'createUser',
+            {
+                body: {
+                    name: 'John Doe',
+                    email: 'john@example.com'
+                }
+            },
+            {
+                201: ({ data }) => {
+                    console.log('User created:', data);
+                    return data;
+                },
+                422: ({ error }) => {
+                    console.error('Validation error:', error);
+                    throw new Error('Validation failed');
+                }
+            }
+        );
+
+        return { getUserResult, createUserResult };
+    } catch (error) {
+        console.error('API call failed:', error);
+        throw error;
+    }
+}
+
+// Export for use in browser
+export { client, exampleUsage };

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "ts-typed-api",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A lightweight, type-safe RPC library for TypeScript with Zod validation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client-only.d.ts",
+      "default": "./dist/client-only.js"
+    },
+    "./server": {
+      "types": "./dist/server-only.d.ts",
+      "default": "./dist/server-only.js"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "lint": "eslint . --ext .ts",

package/src/client-only.ts

@@ -0,0 +1,33 @@
+// Client-only exports - no server dependencies
+export { ApiClient, FetchHttpClientAdapter } from './client';
+export { CreateApiDefinition, CreateResponses } from './definition';
+export { z as ZodSchema } from 'zod';
+
+// Re-export types that are safe for client use
+export type {
+    ApiDefinitionSchema,
+    RouteSchema,
+    UnifiedError,
+    InferDataFromUnifiedResponse,
+    ApiClientParams,
+    ApiClientQuery,
+    ApiClientBody,
+    ApiResponse,
+    ApiBody,
+    ApiParams,
+    ApiQuery,
+    FileType,
+    HttpSuccessStatusCode,
+    HttpClientErrorStatusCode,
+    HttpServerErrorStatusCode,
+    AllowedInputStatusCode,
+    AllowedResponseStatusCode
+} from './definition';
+
+export type {
+    HttpRequestOptions,
+    HttpResponse,
+    HttpClientAdapter,
+    ApiCallResult,
+    CallApiOptions
+} from './client';

package/src/server-only.ts

@@ -0,0 +1,17 @@
+// Server-only exports - includes server dependencies
+export { RegisterHandlers, EndpointMiddleware } from './object-handlers';
+export { File as UploadedFile } from './router';
+export {
+    createRouteHandler,
+    makeRouteHandlerCreator
+} from './router';
+
+// Re-export types that are needed for server-side development
+export type {
+    TypedRequest,
+    TypedResponse
+} from './router';
+
+export type {
+    ObjectHandlers
+} from './object-handlers';