@spoosh/core 0.3.0 → 0.4.1

package/README.md

@@ -36,7 +36,10 @@ type ApiSchema = {
     $post: Endpoint<{ data: { url: string }; formData: { file: File } }>;
   };
   payments: {
-    $post: Endpoint<{ data: { id: string }; urlEncoded: { amount: number; currency: string } }>;
+    $post: Endpoint<{
+      data: { id: string };
+      urlEncoded: { amount: number; currency: string };
+    }>;
   };
 };
 ```
@@ -173,16 +176,16 @@ const updatedContext = await applyMiddlewares(context, middlewares, "before");
 
 ## Schema Types
 
-| Type                                    | Description                   | Example                                                               |
-| --------------------------------------- | ----------------------------- | --------------------------------------------------------------------- |
-| `Endpoint<{ data }>`                    | Endpoint with data only       | `$get: Endpoint<{ data: User[] }>`                                    |
-| `Endpoint<{ data; body }>`              | Endpoint with JSON body       | `$post: Endpoint<{ data: User; body: CreateUserBody }>`               |
-| `Endpoint<{ data; query }>`             | Endpoint with query params    | `$get: Endpoint<{ data: User[]; query: { page: number } }>`           |
-| `Endpoint<{ data; formData }>`          | Endpoint with multipart form  | `$post: Endpoint<{ data: Result; formData: { file: File } }>`         |
-| `Endpoint<{ data; urlEncoded }>`        | Endpoint with URL-encoded     | `$post: Endpoint<{ data: Result; urlEncoded: { amount: number } }>`   |
-| `Endpoint<{ data; error }>`             | Endpoint with typed error     | `$get: Endpoint<{ data: User; error: ApiError }>`                     |
-| `void`                                  | No response body              | `$delete: void`                                                       |
-| `_`                                     | Dynamic path segment          | `users: { _: { $get: Endpoint<{ data: User }> } }`                    |
+| Type                             | Description                  | Example                                                             |
+| -------------------------------- | ---------------------------- | ------------------------------------------------------------------- |
+| `Endpoint<{ data }>`             | Endpoint with data only      | `$get: Endpoint<{ data: User[] }>`                                  |
+| `Endpoint<{ data; body }>`       | Endpoint with JSON body      | `$post: Endpoint<{ data: User; body: CreateUserBody }>`             |
+| `Endpoint<{ data; query }>`      | Endpoint with query params   | `$get: Endpoint<{ data: User[]; query: { page: number } }>`         |
+| `Endpoint<{ data; formData }>`   | Endpoint with multipart form | `$post: Endpoint<{ data: Result; formData: { file: File } }>`       |
+| `Endpoint<{ data; urlEncoded }>` | Endpoint with URL-encoded    | `$post: Endpoint<{ data: Result; urlEncoded: { amount: number } }>` |
+| `Endpoint<{ data; error }>`      | Endpoint with typed error    | `$get: Endpoint<{ data: User; error: ApiError }>`                   |
+| `void`                           | No response body             | `$delete: void`                                                     |
+| `_`                              | Dynamic path segment         | `users: { _: { $get: Endpoint<{ data: User }> } }`                  |
 
 ## API Reference
 
@@ -206,11 +209,8 @@ import { cachePlugin } from "@spoosh/plugin-cache";
 import { retryPlugin } from "@spoosh/plugin-retry";
 
 const client = new Spoosh<ApiSchema, Error>("/api", {
-  headers: { Authorization: "Bearer token" }
-}).use([
-  cachePlugin({ staleTime: 5000 }),
-  retryPlugin({ retries: 3 })
-]);
+  headers: { Authorization: "Bearer token" },
+}).use([cachePlugin({ staleTime: 5000 }), retryPlugin({ retries: 3 })]);
 
 const { api } = client;
 const { data } = await api.users.$get();
@@ -218,26 +218,25 @@ const { data } = await api.users.$get();
 
 **Constructor Parameters:**
 
-| Parameter        | Type            | Description                             |
-| ---------------- | --------------- | --------------------------------------- |
-| `baseUrl`        | `string`        | Base URL for all API requests           |
-| `defaultOptions` | `RequestInit`   | (Optional) Default fetch options        |
+| Parameter        | Type          | Description                      |
+| ---------------- | ------------- | -------------------------------- |
+| `baseUrl`        | `string`      | Base URL for all API requests    |
+| `defaultOptions` | `RequestInit` | (Optional) Default fetch options |
 
 **Methods:**
 
-| Method | Description |
-| ------ | ----------- |
+| Method          | Description                                                           |
+| --------------- | --------------------------------------------------------------------- |
 | `.use(plugins)` | Add plugins to the client. Returns a new instance with updated types. |
 
 **Properties:**
 
-| Property | Description |
-| -------- | ----------- |
-| `.api` | Type-safe API client for making requests |
-| `.stateManager` | Cache and state management |
-| `.eventEmitter` | Event system for refetch/invalidation |
-| `.pluginExecutor` | Plugin lifecycle management |
-
+| Property          | Description                              |
+| ----------------- | ---------------------------------------- |
+| `.api`            | Type-safe API client for making requests |
+| `.stateManager`   | Cache and state management               |
+| `.eventEmitter`   | Event system for refetch/invalidation    |
+| `.pluginExecutor` | Plugin lifecycle management              |
 
 ## Creating Plugins
 

package/dist/index.d.mts

@@ -96,6 +96,8 @@ type AnyRequestOptions = BaseRequestOptions & {
     urlEncoded?: Record<string, unknown>;
     params?: Record<string, string | number>;
     signal?: AbortSignal;
+    /** @internal Path transformer function. Set by plugins like path-case. */
+    _pathTransformer?: (path: string[]) => string[];
 } & Partial<RetryConfig>;
 type DynamicParamsOption = {
     params?: Record<string, string | number>;
@@ -801,7 +803,6 @@ type HttpMethods<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamN
     [K in SchemaMethod as K extends keyof TSchema ? K : never]: MethodFn<TSchema, K, TDefaultError, TOptionsMap, TParamNames>;
 };
 type DynamicAccess<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = ExtractDynamicSchema<TSchema> extends never ? object : {
-    [key: number]: SpooshClient<ExtractDynamicSchema<TSchema>, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
     /**
      * Dynamic path segment with typed param name.
      * Use `:paramName` format to get typed params in the response.
@@ -844,7 +845,6 @@ type ExtractParamName<S> = S extends `:${infer P}` ? P : never;
 type QueryDynamicAccess<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = TSchema extends {
     _: infer D;
 } ? HasQueryMethods<D> extends true ? {
-    [key: number]: QueryOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
     <TKey extends string | number>(key: TKey): QueryOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | ExtractParamName<TKey>, TRootSchema>;
 } : object : object;
 type QueryOnlyClient<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = QueryHttpMethods<TSchema, TDefaultError, TOptionsMap, TParamNames> & QueryDynamicAccess<TSchema, TDefaultError, TOptionsMap, TParamNames, TRootSchema> & {
@@ -856,7 +856,6 @@ type MutationHttpMethods<TSchema, TDefaultError = unknown, TOptionsMap = object,
 type MutationDynamicAccess<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = TSchema extends {
     _: infer D;
 } ? HasMutationMethods<D> extends true ? {
-    [key: number]: MutationOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string>;
     <TKey extends string | number>(key: TKey): MutationOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | ExtractParamName<TKey>>;
 } : object : object;
 type MutationOnlyClient<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = MutationHttpMethods<TSchema, TDefaultError, TOptionsMap, TParamNames> & MutationDynamicAccess<TSchema, TDefaultError, TOptionsMap, TParamNames> & {
@@ -906,7 +905,7 @@ type EndpointToMethod<T> = (options?: ExtractEndpointRequestOptions<T>) => Promi
  * trigger({
  *   myCallback: (api) => [
  *     api.posts.$get,           // ✓ Valid
- *     api.users[1].$get,        // ✓ Dynamic segment
+ *     api.users(1).$get,        // ✓ Dynamic segment
  *     api.nonexistent.$get,     // ✗ Type error
  *   ],
  * });
@@ -919,7 +918,7 @@ type QuerySchemaHelper<TSchema> = {
 } & (TSchema extends {
     _: infer D;
 } ? HasQueryMethods<D> extends true ? {
-    [key: number]: QuerySchemaHelper<D>;
+    <TKey extends string | number>(key: TKey): QuerySchemaHelper<D>;
 } : object : object);
 
 type PluginArray = readonly SpooshPlugin<PluginTypeConfig>[];
@@ -1066,7 +1065,7 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
      * const { data } = await api.posts.$post({ body: { title: 'Hello' } });
      *
      * // Dynamic path parameters
-     * const { data } = await api.posts[postId].$get();
+     * const { data } = await api.posts(postId).$get();
      * ```
      */
     get api(): SpooshClient<TSchema, TError, CoreRequestOptionsBase>;
@@ -1187,7 +1186,7 @@ type SpooshClientConfig = {
  *
  * // Type-safe API calls
  * const { data } = await api.posts.$get();
- * const { data: post } = await api.posts[123].$get();
+ * const { data: post } = await api.posts(123).$get();
  * ```
  */
 declare function createClient<TSchema, TDefaultError = unknown>(config: SpooshClientConfig): SpooshClient<TSchema, TDefaultError>;
@@ -1260,9 +1259,9 @@ type ProxyHandlerConfig<TOptions = SpooshOptions> = {
  * await api.posts.$get();
  *
  * // Dynamic segments via function call:
- * // api.posts[123].$get() or api.posts('123').$get()
+ * // api.posts(123).$get() or api.posts('123').$get()
  * // Executes: GET /api/posts/123
- * await api.posts[123].$get();
+ * await api.posts(123).$get();
  * ```
  */
 declare function createProxyHandler<TSchema extends object, TOptions = SpooshOptions>(config: ProxyHandlerConfig<TOptions>): TSchema;

package/dist/index.d.ts

@@ -96,6 +96,8 @@ type AnyRequestOptions = BaseRequestOptions & {
     urlEncoded?: Record<string, unknown>;
     params?: Record<string, string | number>;
     signal?: AbortSignal;
+    /** @internal Path transformer function. Set by plugins like path-case. */
+    _pathTransformer?: (path: string[]) => string[];
 } & Partial<RetryConfig>;
 type DynamicParamsOption = {
     params?: Record<string, string | number>;
@@ -801,7 +803,6 @@ type HttpMethods<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamN
     [K in SchemaMethod as K extends keyof TSchema ? K : never]: MethodFn<TSchema, K, TDefaultError, TOptionsMap, TParamNames>;
 };
 type DynamicAccess<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = ExtractDynamicSchema<TSchema> extends never ? object : {
-    [key: number]: SpooshClient<ExtractDynamicSchema<TSchema>, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
     /**
      * Dynamic path segment with typed param name.
      * Use `:paramName` format to get typed params in the response.
@@ -844,7 +845,6 @@ type ExtractParamName<S> = S extends `:${infer P}` ? P : never;
 type QueryDynamicAccess<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = TSchema extends {
     _: infer D;
 } ? HasQueryMethods<D> extends true ? {
-    [key: number]: QueryOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
     <TKey extends string | number>(key: TKey): QueryOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | ExtractParamName<TKey>, TRootSchema>;
 } : object : object;
 type QueryOnlyClient<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = QueryHttpMethods<TSchema, TDefaultError, TOptionsMap, TParamNames> & QueryDynamicAccess<TSchema, TDefaultError, TOptionsMap, TParamNames, TRootSchema> & {
@@ -856,7 +856,6 @@ type MutationHttpMethods<TSchema, TDefaultError = unknown, TOptionsMap = object,
 type MutationDynamicAccess<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = TSchema extends {
     _: infer D;
 } ? HasMutationMethods<D> extends true ? {
-    [key: number]: MutationOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string>;
     <TKey extends string | number>(key: TKey): MutationOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | ExtractParamName<TKey>>;
 } : object : object;
 type MutationOnlyClient<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = MutationHttpMethods<TSchema, TDefaultError, TOptionsMap, TParamNames> & MutationDynamicAccess<TSchema, TDefaultError, TOptionsMap, TParamNames> & {
@@ -906,7 +905,7 @@ type EndpointToMethod<T> = (options?: ExtractEndpointRequestOptions<T>) => Promi
  * trigger({
  *   myCallback: (api) => [
  *     api.posts.$get,           // ✓ Valid
- *     api.users[1].$get,        // ✓ Dynamic segment
+ *     api.users(1).$get,        // ✓ Dynamic segment
  *     api.nonexistent.$get,     // ✗ Type error
  *   ],
  * });
@@ -919,7 +918,7 @@ type QuerySchemaHelper<TSchema> = {
 } & (TSchema extends {
     _: infer D;
 } ? HasQueryMethods<D> extends true ? {
-    [key: number]: QuerySchemaHelper<D>;
+    <TKey extends string | number>(key: TKey): QuerySchemaHelper<D>;
 } : object : object);
 
 type PluginArray = readonly SpooshPlugin<PluginTypeConfig>[];
@@ -1066,7 +1065,7 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
      * const { data } = await api.posts.$post({ body: { title: 'Hello' } });
      *
      * // Dynamic path parameters
-     * const { data } = await api.posts[postId].$get();
+     * const { data } = await api.posts(postId).$get();
      * ```
      */
     get api(): SpooshClient<TSchema, TError, CoreRequestOptionsBase>;
@@ -1187,7 +1186,7 @@ type SpooshClientConfig = {
  *
  * // Type-safe API calls
  * const { data } = await api.posts.$get();
- * const { data: post } = await api.posts[123].$get();
+ * const { data: post } = await api.posts(123).$get();
  * ```
  */
 declare function createClient<TSchema, TDefaultError = unknown>(config: SpooshClientConfig): SpooshClient<TSchema, TDefaultError>;
@@ -1260,9 +1259,9 @@ type ProxyHandlerConfig<TOptions = SpooshOptions> = {
  * await api.posts.$get();
  *
  * // Dynamic segments via function call:
- * // api.posts[123].$get() or api.posts('123').$get()
+ * // api.posts(123).$get() or api.posts('123').$get()
  * // Executes: GET /api/posts/123
- * await api.posts[123].$get();
+ * await api.posts(123).$get();
  * ```
  */
 declare function createProxyHandler<TSchema extends object, TOptions = SpooshOptions>(config: ProxyHandlerConfig<TOptions>): TSchema;

package/dist/index.js

@@ -336,7 +336,8 @@ async function executeCoreFetch(config) {
   const maxRetries = requestOptions?.retries ?? 3;
   const baseDelay = requestOptions?.retryDelay ?? 1e3;
   const retryCount = maxRetries === false ? 0 : maxRetries;
-  const url = buildUrl(baseUrl, path, requestOptions?.query);
+  const finalPath = requestOptions?._pathTransformer?.(path) ?? path;
+  const url = buildUrl(baseUrl, finalPath, requestOptions?.query);
   let headers = await mergeHeaders(defaultHeaders, requestOptions?.headers);
   const fetchInit = {
     ...fetchDefaults,
@@ -476,11 +477,9 @@ function createProxyHandler(config) {
         nextTags
       });
     },
-    // Handles function call syntax for dynamic segments: api.posts("123"), api.users(userId)
-    // Q. Why allow this syntax?
-    // A. To support dynamic type inference in frameworks where property access with variables is not possible.
-    //    Eg. api.posts[":id"].$get() <-- TypeScript sees this as bracket notation with a string literal, can't infer param types
-    //    But api.posts(":id").$get() <-- TypeScript can capture ":id" as a template literal type, enabling params: { id: string } inference
+    // Handles function call syntax for dynamic segments: api.posts(123), api.posts(":id"), api.users(userId)
+    // This is the only way to access dynamic segments in Spoosh.
+    // The function call syntax allows TypeScript to capture the literal type, enabling params: { id: string } inference.
     apply(_target, _thisArg, args) {
       const [segment] = args;
       return createProxyHandler({
@@ -531,7 +530,7 @@ function createSelectorProxy(onCapture) {
       // Handles function call syntax for dynamic segments: api.posts("123"), api.users(userId)
       apply(_, __, args) {
         const [segment] = args;
-        return createProxy([...path, segment]);
+        return createProxy([...path, String(segment)]);
       }
     });
   };
@@ -989,7 +988,7 @@ var Spoosh = class _Spoosh {
    * const { data } = await api.posts.$post({ body: { title: 'Hello' } });
    *
    * // Dynamic path parameters
-   * const { data } = await api.posts[postId].$get();
+   * const { data } = await api.posts(postId).$get();
    * ```
    */
   get api() {

package/dist/index.mjs

@@ -281,7 +281,8 @@ async function executeCoreFetch(config) {
   const maxRetries = requestOptions?.retries ?? 3;
   const baseDelay = requestOptions?.retryDelay ?? 1e3;
   const retryCount = maxRetries === false ? 0 : maxRetries;
-  const url = buildUrl(baseUrl, path, requestOptions?.query);
+  const finalPath = requestOptions?._pathTransformer?.(path) ?? path;
+  const url = buildUrl(baseUrl, finalPath, requestOptions?.query);
   let headers = await mergeHeaders(defaultHeaders, requestOptions?.headers);
   const fetchInit = {
     ...fetchDefaults,
@@ -421,11 +422,9 @@ function createProxyHandler(config) {
         nextTags
       });
     },
-    // Handles function call syntax for dynamic segments: api.posts("123"), api.users(userId)
-    // Q. Why allow this syntax?
-    // A. To support dynamic type inference in frameworks where property access with variables is not possible.
-    //    Eg. api.posts[":id"].$get() <-- TypeScript sees this as bracket notation with a string literal, can't infer param types
-    //    But api.posts(":id").$get() <-- TypeScript can capture ":id" as a template literal type, enabling params: { id: string } inference
+    // Handles function call syntax for dynamic segments: api.posts(123), api.posts(":id"), api.users(userId)
+    // This is the only way to access dynamic segments in Spoosh.
+    // The function call syntax allows TypeScript to capture the literal type, enabling params: { id: string } inference.
     apply(_target, _thisArg, args) {
       const [segment] = args;
       return createProxyHandler({
@@ -476,7 +475,7 @@ function createSelectorProxy(onCapture) {
       // Handles function call syntax for dynamic segments: api.posts("123"), api.users(userId)
       apply(_, __, args) {
         const [segment] = args;
-        return createProxy([...path, segment]);
+        return createProxy([...path, String(segment)]);
       }
     });
   };
@@ -934,7 +933,7 @@ var Spoosh = class _Spoosh {
    * const { data } = await api.posts.$post({ body: { title: 'Hello' } });
    *
    * // Dynamic path parameters
-   * const { data } = await api.posts[postId].$get();
+   * const { data } = await api.posts(postId).$get();
    * ```
    */
   get api() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "license": "MIT",
   "description": "Type-safe API client with plugin middleware system",
   "keywords": [