@veloxts/client 0.1.0

package/dist/client.js

@@ -0,0 +1,376 @@
+/**
+ * Type-safe API client implementation
+ *
+ * Provides a fetch-based client that calls REST endpoints with full type safety
+ * inferred from backend procedure definitions.
+ *
+ * @module client
+ */
+import { NetworkError, parseErrorResponse } from './errors.js';
+// ============================================================================
+// Naming Convention Mapping
+// ============================================================================
+/**
+ * Maps procedure naming convention to HTTP method
+ *
+ * Matches the same logic used in @veloxts/router REST adapter
+ */
+const PROCEDURE_METHOD_MAP = {
+    get: 'GET',
+    list: 'GET',
+    find: 'GET',
+    create: 'POST',
+    add: 'POST',
+    update: 'PUT',
+    edit: 'PUT',
+    patch: 'PATCH',
+    delete: 'DELETE',
+    remove: 'DELETE',
+};
+/**
+ * Pre-compiled regex pattern for path parameters
+ *
+ * PERFORMANCE: Compiled once at module load instead of per-request.
+ * The pattern matches :paramName format (e.g., :id, :userId, :post_id)
+ *
+ * @internal
+ */
+const PATH_PARAM_PATTERN = /:([a-zA-Z_][a-zA-Z0-9_]*)/g;
+/**
+ * Infers HTTP method from procedure name
+ *
+ * @internal
+ */
+function inferMethodFromName(procedureName) {
+    // Check each prefix
+    for (const [prefix, method] of Object.entries(PROCEDURE_METHOD_MAP)) {
+        if (procedureName.startsWith(prefix)) {
+            return method;
+        }
+    }
+    // Default to POST for mutations (conservative default)
+    return 'POST';
+}
+// Note: extractResourceFromName is reserved for future use in path building enhancements
+// Keeping it commented for now to avoid unused code warnings
+// function extractResourceFromName(procedureName: string): string | undefined {
+//   for (const prefix of Object.keys(PROCEDURE_METHOD_MAP)) {
+//     if (procedureName.startsWith(prefix)) {
+//       const remainder = procedureName.slice(prefix.length);
+//       if (remainder.length > 0) {
+//         return remainder.charAt(0).toLowerCase() + remainder.slice(1);
+//       }
+//     }
+//   }
+//   return undefined;
+// }
+/**
+ * Builds REST path from namespace and procedure name
+ *
+ * @example
+ * - namespace='users', name='getUser' -> '/users/:id'
+ * - namespace='users', name='listUsers' -> '/users'
+ * - namespace='posts', name='createPost' -> '/posts'
+ *
+ * @internal
+ */
+function buildRestPath(namespace, procedureName) {
+    const method = inferMethodFromName(procedureName);
+    // List operations: /namespace
+    if (procedureName.startsWith('list')) {
+        return `/${namespace}`;
+    }
+    // Single resource operations (get, update, delete): /namespace/:id
+    if (procedureName.startsWith('get') ||
+        procedureName.startsWith('update') ||
+        procedureName.startsWith('delete')) {
+        return `/${namespace}/:id`;
+    }
+    // Create operations: /namespace
+    if (method === 'POST') {
+        return `/${namespace}`;
+    }
+    // Default: /namespace
+    return `/${namespace}`;
+}
+/**
+ * Replaces path parameters with actual values from input
+ *
+ * PERFORMANCE: Uses pre-compiled PATH_PARAM_PATTERN instead of creating
+ * a new RegExp on each call. Resets lastIndex for safe reuse.
+ *
+ * @example
+ * - path='/users/:id', input={ id: '123' } -> '/users/123'
+ * - path='/posts/:postId/comments/:id', input={ postId: 'abc', id: '456' } -> '/posts/abc/comments/456'
+ *
+ * @internal
+ */
+function resolvePathParams(path, input) {
+    // Reset lastIndex for safe reuse of global regex
+    PATH_PARAM_PATTERN.lastIndex = 0;
+    return path.replace(PATH_PARAM_PATTERN, (_match, paramName) => {
+        const value = input[paramName];
+        if (value === undefined || value === null) {
+            throw new Error(`Missing path parameter: ${paramName}`);
+        }
+        return String(value);
+    });
+}
+/**
+ * Builds query string from input object, excluding path params
+ *
+ * @internal
+ */
+function buildQueryString(input, pathParams) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(input)) {
+        // Skip path parameters
+        if (pathParams.has(key)) {
+            continue;
+        }
+        // Skip undefined values
+        if (value === undefined) {
+            continue;
+        }
+        // Handle arrays
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                params.append(key, String(item));
+            }
+        }
+        else {
+            params.append(key, String(value));
+        }
+    }
+    const queryString = params.toString();
+    return queryString ? `?${queryString}` : '';
+}
+/**
+ * Extracts path parameter names from a path pattern
+ *
+ * PERFORMANCE: Uses pre-compiled PATH_PARAM_PATTERN instead of creating
+ * a new RegExp on each call. Uses matchAll which handles lastIndex internally.
+ *
+ * @example
+ * - '/users/:id' -> Set(['id'])
+ * - '/posts/:postId/comments/:commentId' -> Set(['postId', 'commentId'])
+ *
+ * @internal
+ */
+function extractPathParams(path) {
+    const params = new Set();
+    // matchAll creates an iterator that handles lastIndex internally
+    for (const match of path.matchAll(PATH_PARAM_PATTERN)) {
+        params.add(match[1]);
+    }
+    return params;
+}
+// ============================================================================
+// Request Building
+// ============================================================================
+/**
+ * Builds the full URL and request options for a procedure call
+ *
+ * @internal
+ */
+function buildRequest(call, baseUrl, config) {
+    const method = inferMethodFromName(call.procedureName);
+    const path = buildRestPath(call.namespace, call.procedureName);
+    // Prepare headers
+    const headers = {
+        'Content-Type': 'application/json',
+        ...config.headers,
+    };
+    let finalPath = path;
+    let body;
+    // Handle input based on method
+    if (method === 'GET') {
+        // GET: params in URL
+        const pathParams = extractPathParams(path);
+        const input = (call.input || {});
+        // Resolve path parameters
+        finalPath = resolvePathParams(path, input);
+        // Add query string for remaining parameters
+        const queryString = buildQueryString(input, pathParams);
+        finalPath = `${finalPath}${queryString}`;
+    }
+    else {
+        // POST/PUT/PATCH/DELETE: body as JSON
+        // But first resolve path params if any
+        const pathParams = extractPathParams(path);
+        if (pathParams.size > 0 && call.input && typeof call.input === 'object') {
+            const input = call.input;
+            finalPath = resolvePathParams(path, input);
+            // For POST with path params, body is the input minus path params
+            const bodyInput = {};
+            for (const [key, value] of Object.entries(input)) {
+                if (!pathParams.has(key)) {
+                    bodyInput[key] = value;
+                }
+            }
+            body = JSON.stringify(bodyInput);
+        }
+        else {
+            body = JSON.stringify(call.input);
+        }
+    }
+    // Build full URL
+    const url = `${baseUrl}${finalPath}`;
+    return {
+        url,
+        options: {
+            method,
+            headers,
+            body,
+        },
+    };
+}
+/**
+ * Executes a procedure call against the API
+ *
+ * @internal
+ */
+async function executeProcedure(call, state) {
+    const { url, options } = buildRequest(call, state.config.baseUrl, state.config);
+    // Call onRequest interceptor
+    if (state.config.onRequest) {
+        await state.config.onRequest(url, options);
+    }
+    let response;
+    try {
+        response = await state.fetch(url, options);
+    }
+    catch (error) {
+        // Network error - couldn't reach server
+        const networkError = new NetworkError('Network request failed', {
+            url,
+            method: options.method || 'GET',
+            cause: error instanceof Error ? error : undefined,
+        });
+        // Call onError interceptor
+        if (state.config.onError) {
+            await state.config.onError(networkError);
+        }
+        throw networkError;
+    }
+    // Parse response body
+    let body;
+    const contentType = response.headers.get('content-type');
+    if (contentType?.includes('application/json')) {
+        try {
+            body = await response.json();
+        }
+        catch {
+            // Couldn't parse JSON - use text
+            body = await response.text();
+        }
+    }
+    else {
+        body = await response.text();
+    }
+    // Handle error responses
+    if (!response.ok) {
+        const error = parseErrorResponse(response, body, url, options.method || 'GET');
+        // Call onError interceptor
+        if (state.config.onError) {
+            await state.config.onError(error);
+        }
+        throw error;
+    }
+    // Call onResponse interceptor
+    if (state.config.onResponse) {
+        await state.config.onResponse(response);
+    }
+    return body;
+}
+/**
+ * Creates a proxy for a namespace that intercepts procedure calls
+ *
+ * @internal
+ */
+function createNamespaceProxy(namespace, state) {
+    return new Proxy({}, {
+        get(_target, procedureName) {
+            // Return a function that executes the procedure
+            return (input) => {
+                return executeProcedure({
+                    namespace,
+                    procedureName,
+                    input,
+                }, state);
+            };
+        },
+    });
+}
+/**
+ * Creates the root client proxy
+ *
+ * @internal
+ */
+function createClientProxy(state) {
+    return new Proxy({}, {
+        get(_target, namespace) {
+            return createNamespaceProxy(namespace, state);
+        },
+    });
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Creates a type-safe API client for a VeloxTS backend
+ *
+ * The client uses TypeScript's type system to infer the full API shape from
+ * backend procedure definitions, providing autocomplete and compile-time type checking.
+ *
+ * @template TRouter - The router type (typeof imported procedures)
+ * @param config - Client configuration
+ * @returns Fully typed API client with namespaced procedures
+ *
+ * @example
+ * ```typescript
+ * // Import procedure types from backend
+ * import type { userProcedures, postProcedures } from '../server/procedures';
+ *
+ * // Create client with inferred types
+ * const api = createClient<{
+ *   users: typeof userProcedures;
+ *   posts: typeof postProcedures;
+ * }>({
+ *   baseUrl: 'https://api.example.com/api',
+ * });
+ *
+ * // Fully typed calls
+ * const user = await api.users.getUser({ id: '123' });
+ * const newPost = await api.posts.createPost({ title: 'Hello', content: '...' });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom configuration
+ * const api = createClient<Router>({
+ *   baseUrl: '/api',
+ *   headers: {
+ *     'Authorization': 'Bearer token123',
+ *   },
+ *   onRequest: async (url, options) => {
+ *     console.log(`${options.method} ${url}`);
+ *   },
+ *   onError: async (error) => {
+ *     console.error('API Error:', error.message);
+ *   },
+ * });
+ * ```
+ */
+export function createClient(config) {
+    // Use provided fetch or global fetch
+    const fetchImpl = config.fetch || fetch;
+    // Create client state
+    const state = {
+        config,
+        fetch: fetchImpl,
+    };
+    // Return the proxy-based client
+    return createClientProxy(state);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Client-side error handling
+ *
+ * Provides error classes that mirror the server-side VeloxError structure,
+ * with additional context about the failed request.
+ *
+ * @module errors
+ */
+import type { ClientError } from './types.js';
+/**
+ * Base error response fields from server
+ */
+interface BaseErrorResponse {
+    error: string;
+    message: string;
+    statusCode: number;
+    code?: string;
+}
+/**
+ * Validation error response from server
+ */
+interface ValidationErrorResponse extends BaseErrorResponse {
+    error: 'ValidationError';
+    statusCode: 400;
+    code: 'VALIDATION_ERROR';
+    fields?: Record<string, string>;
+}
+/**
+ * Not found error response from server
+ */
+interface NotFoundErrorResponse extends BaseErrorResponse {
+    error: 'NotFoundError';
+    statusCode: 404;
+    code: 'NOT_FOUND';
+    resource: string;
+    resourceId?: string;
+}
+/**
+ * Generic error response from server
+ */
+interface GenericErrorResponse extends BaseErrorResponse {
+    error: string;
+    statusCode: number;
+    code?: string;
+}
+/**
+ * Union of all error response types from server
+ */
+export type ErrorResponse = ValidationErrorResponse | NotFoundErrorResponse | GenericErrorResponse;
+/**
+ * Base error class for all client errors
+ *
+ * Represents an error that occurred during an API request, including
+ * both network errors and server-returned error responses.
+ */
+export declare class VeloxClientError extends Error implements ClientError {
+    readonly statusCode?: number;
+    readonly code?: string;
+    readonly body?: unknown;
+    readonly url: string;
+    readonly method: string;
+    constructor(message: string, options: {
+        statusCode?: number;
+        code?: string;
+        body?: unknown;
+        url: string;
+        method: string;
+    });
+}
+/**
+ * Network error when request fails to reach server
+ *
+ * Thrown when the request cannot be completed due to network issues,
+ * CORS problems, or other transport-level failures.
+ */
+export declare class NetworkError extends VeloxClientError {
+    readonly cause?: Error;
+    constructor(message: string, options: {
+        url: string;
+        method: string;
+        cause?: Error;
+    });
+}
+/**
+ * Validation error from server (400 status)
+ *
+ * Thrown when request data fails server-side validation.
+ * Includes field-level error details if provided by server.
+ */
+export declare class ClientValidationError extends VeloxClientError {
+    readonly fields?: Record<string, string>;
+    constructor(message: string, options: {
+        url: string;
+        method: string;
+        fields?: Record<string, string>;
+        body?: unknown;
+    });
+}
+/**
+ * Not found error from server (404 status)
+ *
+ * Thrown when a requested resource doesn't exist.
+ */
+export declare class ClientNotFoundError extends VeloxClientError {
+    readonly resource?: string;
+    readonly resourceId?: string;
+    constructor(message: string, options: {
+        url: string;
+        method: string;
+        resource?: string;
+        resourceId?: string;
+        body?: unknown;
+    });
+}
+/**
+ * Server error (5xx status)
+ *
+ * Thrown when server returns an internal error.
+ */
+export declare class ServerError extends VeloxClientError {
+    constructor(message: string, options: {
+        statusCode: number;
+        code?: string;
+        url: string;
+        method: string;
+        body?: unknown;
+    });
+}
+/**
+ * Type guard for VeloxClientError
+ */
+export declare function isVeloxClientError(error: unknown): error is VeloxClientError;
+/**
+ * Type guard for NetworkError
+ */
+export declare function isNetworkError(error: unknown): error is NetworkError;
+/**
+ * Type guard for ClientValidationError
+ */
+export declare function isClientValidationError(error: unknown): error is ClientValidationError;
+/**
+ * Type guard for ClientNotFoundError
+ */
+export declare function isClientNotFoundError(error: unknown): error is ClientNotFoundError;
+/**
+ * Type guard for ServerError
+ */
+export declare function isServerError(error: unknown): error is ServerError;
+/**
+ * Type guard for validation error response
+ */
+export declare function isValidationErrorResponse(response: ErrorResponse): response is ValidationErrorResponse;
+/**
+ * Type guard for not found error response
+ */
+export declare function isNotFoundErrorResponse(response: ErrorResponse): response is NotFoundErrorResponse;
+/**
+ * Parses an error response from the server and creates appropriate error instance
+ *
+ * @internal
+ */
+export declare function parseErrorResponse(response: Response, body: unknown, url: string, method: string): VeloxClientError;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}