svelte-ag 1.2.8 → 1.3.1

package/src/lib/api/form.svelte.ts

@@ -6,12 +6,11 @@ import type { SuperForm } from 'sveltekit-superforms';
 import { valibot } from 'sveltekit-superforms/adapters';
 import type {
   ApiRequestFunction,
-  HTTPMethod,
   ApiEndpoints,
   ApiInput,
   ApiSuccessBody,
   ApiErrorBody,
-  ApiSchema
+  ApiEndpointContract
 } from 'ts-ag';
 import { safeParse, safeParseAsync } from 'valibot';
 
@@ -51,22 +50,19 @@ type FormErrorBody<
 /**
  * Creates a strongly-typed form factory for an API schema.
  *
- * Call the returned function with `{ path, method, ... }` to get a `SuperForm`
+ * Call the returned function with `{ endpoint, ... }` to get a `SuperForm`
  * that:
  * - Validates using the Valibot schema for the given endpoint.
  * - Submits via the provided `request` function on each valid update.
  * - Maps API errors to `sveltekit-superforms` field errors / messages.
  * - Optionally two-way binds external state through the `bind` adapter.
  */
-export type ApiRequestForm<
-  API extends ApiEndpoints
-  // Schemas extends Partial<Record<API['path'], Partial<Record<string, ApiSchema>>>>
-> = <Path extends API['path'], Method extends Extract<API, { path: Path }>['method']>(a: {
-  /** API path key used to select a schema and to call `request(path, method, data)` */
-  path: Path;
-
-  /** HTTP method used to select a schema and to call `request(path, method, data)` */
-  method: Method;
+export type ApiRequestForm<API extends ApiEndpoints> = <
+  Path extends API['path'],
+  Method extends Extract<API, { path: Path }>['method']
+>(a: {
+  /** Endpoint contract used to select a schema and submit the request. */
+  endpoint: ApiEndpointContract<API, Path, Method>;
 
   /**
    * Optional lifecycle hooks for consumers.
@@ -127,37 +123,30 @@ export type ApiRequestForm<
    * If you pass `onSubmit` / `onUpdate` here it will override the defaults in this helper.
    */
   formProps?: Parameters<typeof superForm<ValidInput<API, Path, Method>>>[1];
-
-  // /**
-  //  *  Schema override to be used in place of the schemas from the creation of
-  //  *  the form function
-  //  */
-  // schema?: NonNullable<Schemas[Path]>[Method];
 }) => SuperForm<ValidInput<API, Path, Method>>;
 
 /**
  * Build an endpoint-specific Superforms factory.
  *
- * @param schemas A `{[path]: {[method]: schema}}` mapping used to pick the Valibot schema for each endpoint.
- * @param request An API request function that performs `(path, method, data)` and returns a fetch-like `Response`.
+ * @param request An API request function that performs `(endpoint, data)` and returns a fetch-like `Response`.
  *
- * @returns A function that creates a `SuperForm` for a particular `{path, method}` pair.
+ * @returns A function that creates a `SuperForm` for a particular endpoint contract.
  */
-export function createFormFunction<API extends ApiEndpoints>(
-  schemas: Partial<Record<API['path'], Partial<Record<HTTPMethod, ApiSchema>>>>,
-  request: ApiRequestFunction<API>
-): ApiRequestForm<API> {
-  return ({ path, method, actions, defaultValue, formProps, bind }) => {
-    const schema = schemas[path]?.[method];
-    if (schema === undefined) throw new Error('Invalid schema for form');
+export function createFormFunction<API extends ApiEndpoints>(request: ApiRequestFunction<API>): ApiRequestForm<API> {
+  return ({ endpoint, actions, defaultValue, formProps, bind }) => {
+    const schema = endpoint.schema;
 
     const defaultFormData = defaults(defaultValue, valibot(schema));
     const boundFormData =
       bind && schema.async === false
-        ? (safeParse(schema, bind.get(defaultFormData)).output as ValidInput<API, typeof path, typeof method>)
+        ? (safeParse(schema, bind.get(defaultFormData)).output as ValidInput<
+            API,
+            typeof endpoint.path,
+            typeof endpoint.method
+          >)
         : defaultFormData;
 
-    const form = superForm<ValidInput<API, typeof path, typeof method>>(boundFormData, {
+    const form = superForm<ValidInput<API, typeof endpoint.path, typeof endpoint.method>>(boundFormData, {
       SPA: true,
       resetForm: true,
       applyAction: false, // Prevents the form redirecting to the same page on submit
@@ -186,10 +175,10 @@ export function createFormFunction<API extends ApiEndpoints>(
         if (!props.form.valid) return;
 
         // console.log('onUpdate: sending data', form.data);
-        const res = await request(path, method, props.form.data);
+        const res = await request(endpoint, props.form.data);
 
         if (res.ok === false) {
-          const body = (await res.json()) as FormErrorBody<API, typeof path, typeof method>;
+          const body = (await res.json()) as FormErrorBody<API, typeof endpoint.path, typeof endpoint.method>;
 
           // TODO set some kind of overall form error if there is no field
           if (!body.field) {
@@ -204,7 +193,7 @@ export function createFormFunction<API extends ApiEndpoints>(
         } else {
           setMessage(props.form, 'Success');
           if (actions && actions.onSuccess) {
-            const body = (await res.json()) as ApiSuccessBody<API, typeof path, typeof method>;
+            const body = (await res.json()) as ApiSuccessBody<API, typeof endpoint.path, typeof endpoint.method>;
             await actions.onSuccess({ ...props, body });
           }
         }
@@ -219,7 +208,11 @@ export function createFormFunction<API extends ApiEndpoints>(
        */
       const bindGet = async () => {
         const formData = get(form.form);
-        return (await safeParseAsync(schema, bind.get(formData))).output as ValidInput<API, typeof path, typeof method>;
+        return (await safeParseAsync(schema, bind.get(formData))).output as ValidInput<
+          API,
+          typeof endpoint.path,
+          typeof endpoint.method
+        >;
       };
 
       form.form.subscribe((v) => {

package/src/lib/api/query/entrypoint.svelte.ts

@@ -1,5 +1,6 @@
 import { SvelteMap } from 'svelte/reactivity';
-import type { ApiEndpoints, ApiRequestFunction, ApiInput, ApiResponse } from 'ts-ag';
+import { endpointKey } from 'ts-ag';
+import type { ApiEndpointContract, ApiEndpoints, ApiRequestFunction, ApiInput, ApiResponse } from 'ts-ag';
 
 import { Cache } from './cache.svelte.js';
 import { Requestor, Query } from './query.svelte.js';
@@ -29,10 +30,24 @@ export type BatchDetails<
 };
 
 export type ApiBatchDetails<API extends ApiEndpoints> = {
-  [Path in API['path']]?: {
-    [Method in Extract<API, { path: Path }>['method']]?: BatchDetails<API, Path, Method>;
-  };
-};
+  [Path in API['path']]: {
+    [Method in Extract<API, { path: Path }>['method']]: {
+      endpoint: ApiEndpointContract<API, Path, Method>;
+      details: BatchDetails<API, Path, Method>;
+    };
+  }[Extract<API, { path: Path }>['method']];
+}[API['path']][];
+
+export function batchEndpoint<
+  API extends ApiEndpoints,
+  Path extends API['path'],
+  Method extends Extract<API, { path: Path }>['method']
+>(
+  endpoint: ApiEndpointContract<API, Path, Method>,
+  details: BatchDetails<API, Path, Method>
+): ApiBatchDetails<API>[number] {
+  return { endpoint, details };
+}
 
 /**
  * Helper function to use once so that creating queries is easier.
@@ -45,21 +60,23 @@ export function createQueryFunction<API extends ApiEndpoints>(
   request: ApiRequestFunction<API>,
   batchDetails: ApiBatchDetails<API>
 ) {
+  // eslint-disable-next-line
+  const batchDetailsByEndpoint = new Map(batchDetails.map((entry) => [endpointKey(entry.endpoint), entry.details]));
+
   return <Path extends API['path'], Method extends Extract<API, { path: Path }>['method']>(
-    path: Path,
-    method: Method,
+    endpoint: ApiEndpointContract<API, Path, Method>,
     input: ApiInput<API, Path, Method>,
     opts?: ConstructorParameters<typeof Query<API, Path, Method>>[0]['opts']
   ): Query<API, Path, Method> => {
-    const queryKey = cacheKey(path, method, input);
+    const queryKey = cacheKey(endpoint, input);
     if (!queries.has(queryKey)) {
-      const key = batchQueryKey(path, method);
+      const key = batchQueryKey(endpoint);
       if (!requestors.has(key)) {
-        requestors.set(key, new Requestor(path, method, request, cache, batchDetails[path]?.[method]));
+        requestors.set(key, new Requestor(endpoint, request, cache, batchDetailsByEndpoint.get(key)));
       }
       const requestor = requestors.get(key)!;
 
-      queries.set(queryKey, new Query<API, Path, Method>({ path, method, input, requestor, cache, opts }));
+      queries.set(queryKey, new Query<API, Path, Method>({ endpoint, input, requestor, cache, opts }));
     }
     const query = queries.get(queryKey)!;
 

package/src/lib/api/query/entrypoint.unit.test.ts

@@ -1,4 +1,4 @@
-import { createApiRequest, type ApiEndpoints } from 'ts-ag';
+import { createApiRequest, type ApiEndpointContract, type ApiEndpoints } from 'ts-ag';
 import * as v from 'valibot';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
@@ -17,11 +17,11 @@ type UsersApi = {
 
 const API_URL = 'https://api.example.test';
 
-const schemas = {
-  '/users': {
-    POST: v.union([v.object({ id: v.number(), group: v.optional(v.string()) }), v.object({ ids: v.array(v.number()) })])
-  }
-};
+const users_POST = {
+  path: '/users',
+  method: 'POST',
+  schema: v.union([v.object({ id: v.number(), group: v.optional(v.string()) }), v.object({ ids: v.array(v.number()) })])
+} satisfies ApiEndpointContract<UsersApi, '/users', 'POST'>;
 
 function getUserId(input: UsersApi['requestInput']): number {
   return 'id' in input ? input.id : input.ids[0]!;
@@ -49,39 +49,37 @@ describe('createQueryFunction', () => {
 
   it('returns the same query instance for the same path, method, and input', async () => {
     const { createQueryFunction } = await import('./entrypoint.svelte.js');
-    const request = createApiRequest<UsersApi>(schemas, API_URL, 'test');
-    const createQuery = createQueryFunction<UsersApi>(request, {});
+    const request = createApiRequest<UsersApi>(API_URL, 'test');
+    const createQuery = createQueryFunction<UsersApi>(request, []);
 
-    const query1 = createQuery('/users', 'POST', { id: 1 });
-    const query2 = createQuery('/users', 'POST', { id: 1 });
-    const query3 = createQuery('/users', 'POST', { id: 2 });
+    const query1 = createQuery(users_POST, { id: 1 });
+    const query2 = createQuery(users_POST, { id: 1 });
+    const query3 = createQuery(users_POST, { id: 2 });
 
     expect(query1).toBe(query2);
     expect(query3).not.toBe(query1);
   });
 
   it('reuses requestors so separate queries can batch together', async () => {
-    const { createQueryFunction } = await import('./entrypoint.svelte.js');
+    const { batchEndpoint, createQueryFunction } = await import('./entrypoint.svelte.js');
     const fetchMock = vi.fn(async () => jsonFetchResponse({ 1: 'one', 2: 'two' }));
     vi.stubGlobal('fetch', fetchMock);
     vi.stubGlobal('fetch', fetchMock);
-    const request = createApiRequest<UsersApi>(schemas, API_URL, 'test');
-    const createQuery = createQueryFunction<UsersApi>(request, {
-      '/users': {
-        POST: {
-          canBatch: () => 'users',
-          batchInput: (inputs) => ({ ids: inputs.map(getUserId) }),
-          unBatchOutput: async (inputs, outputs) => {
-            return inputs.map(() => {
-              return outputs;
-            });
-          }
+    const request = createApiRequest<UsersApi>(API_URL, 'test');
+    const createQuery = createQueryFunction<UsersApi>(request, [
+      batchEndpoint(users_POST, {
+        canBatch: () => 'users',
+        batchInput: (inputs) => ({ ids: inputs.map(getUserId) }),
+        unBatchOutput: async (inputs, outputs) => {
+          return inputs.map(() => {
+            return outputs;
+          });
         }
-      }
-    });
+      })
+    ]);
 
-    const query1 = createQuery('/users', 'POST', { id: 1 });
-    const query2 = createQuery('/users', 'POST', { id: 2 });
+    const query1 = createQuery(users_POST, { id: 1 });
+    const query2 = createQuery(users_POST, { id: 2 });
 
     const p1 = query1.request();
     const p2 = query2.request();

package/src/lib/api/query/query.svelte.ts

@@ -1,5 +1,13 @@
 import { stringify } from 'devalue';
-import type { ApiEndpoints, ApiInput, ApiRequestFunction, ApiSuccessBody, ApiErrorBody, ApiResponse } from 'ts-ag';
+import type {
+  ApiEndpointContract,
+  ApiEndpoints,
+  ApiInput,
+  ApiRequestFunction,
+  ApiSuccessBody,
+  ApiErrorBody,
+  ApiResponse
+} from 'ts-ag';
 
 import type { Cache } from './cache.svelte';
 import type { BatchDetails } from './entrypoint.svelte';
@@ -17,8 +25,7 @@ export class Query<
   #TIMEOUT = 1000 * 60 * 5; // 5 minutes
 
   // -------- Set in constructor --------
-  #path: Path;
-  #method: Method;
+  #endpoint: ApiEndpointContract<API, Path, Method>;
   #input: ApiInput<API, Path, Method>;
   #inputString: string;
   #cacheKey: string;
@@ -37,15 +44,13 @@ export class Query<
 
   // -------- Functions --------
   constructor({
-    path,
-    method,
+    endpoint,
     input,
     requestor,
     cache,
     opts
   }: {
-    path: Path;
-    method: Method;
+    endpoint: ApiEndpointContract<API, Path, Method>;
     input: ApiInput<API, Path, Method>;
     requestor: Requestor<API, Path, Method>;
     cache: Cache;
@@ -56,14 +61,13 @@ export class Query<
     this.#requestor = requestor;
     this.#cache = cache;
 
-    this.#path = path;
-    this.#method = method;
+    this.#endpoint = endpoint;
 
     // if (this.#cachekey) this.#cache.deregister(this.#cachekey);
 
     this.#input = input;
     this.#inputString = stringify(input);
-    this.#cacheKey = cacheKey(path, method, input);
+    this.#cacheKey = cacheKey(endpoint, input);
 
     this.#cache.register(this.#cacheKey, opts?.cache ?? { timeout: this.#TIMEOUT });
   }
@@ -141,8 +145,7 @@ export class Requestor<
   #batchDelay = 100;
 
   // -------- Set in constructor --------
-  #path: Path;
-  #method: Method;
+  #endpoint: ApiEndpointContract<API, Path, Method>;
   #request: ApiRequestFunction<API>;
 
   #canBatch: BatchDetails<API, Path, Method>['canBatch'];
@@ -164,14 +167,12 @@ export class Requestor<
   #batchTimers: Record<string, NodeJS.Timeout | null> = {};
 
   constructor(
-    path: Path,
-    method: Method,
+    endpoint: ApiEndpointContract<API, Path, Method>,
     request: ApiRequestFunction<API>,
     _cache: Cache,
     batchDetails?: BatchDetails<API, Path, Method>
   ) {
-    this.#path = path;
-    this.#method = method;
+    this.#endpoint = endpoint;
     this.#request = request;
     this.#limiter = new RateLimiter();
     // this.#cache = cache;
@@ -187,7 +188,7 @@ export class Requestor<
     // if ('PUBLIC_ENVIRONMENT' in env && env.PUBLIC_ENVIRONMENT === 'development') {
     //   await sleep(1000);
     // }
-    return await this.#limiter.add(() => this.#request(this.#path, this.#method, input));
+    return await this.#limiter.add(() => this.#request(this.#endpoint, input));
   }
 
   /**

package/src/lib/api/query/query.unit.test.ts

@@ -1,5 +1,5 @@
 import { stringify } from 'devalue';
-import { createApiRequest, type ApiEndpoints } from 'ts-ag';
+import { createApiRequest, type ApiEndpointContract, type ApiEndpoints } from 'ts-ag';
 import * as v from 'valibot';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
@@ -30,17 +30,17 @@ type BatchedUsersApi = {
 
 const API_URL = 'https://api.example.test';
 
-const plainSchemas = {
-  '/users': {
-    GET: v.object({ id: v.number() })
-  }
-};
+const plainUsers_GET = {
+  path: '/users',
+  method: 'GET',
+  schema: v.object({ id: v.number() })
+} satisfies ApiEndpointContract<PlainUsersApi, '/users', 'GET'>;
 
-const batchedSchemas = {
-  '/users': {
-    POST: v.union([v.object({ id: v.number(), group: v.optional(v.string()) }), v.object({ ids: v.array(v.number()) })])
-  }
-};
+const batchedUsers_POST = {
+  path: '/users',
+  method: 'POST',
+  schema: v.union([v.object({ id: v.number(), group: v.optional(v.string()) }), v.object({ ids: v.array(v.number()) })])
+} satisfies ApiEndpointContract<BatchedUsersApi, '/users', 'POST'>;
 
 function getSingleId(input: BatchedUsersApi['requestInput']): number {
   return 'id' in input ? input.id : input.ids[0]!;
@@ -97,23 +97,22 @@ function deferred<T>() {
 }
 
 function createPlainRequest() {
-  return createApiRequest<PlainUsersApi>(plainSchemas, API_URL, 'test');
+  return createApiRequest<PlainUsersApi>(API_URL, 'test');
 }
 
 function createBatchedRequest() {
-  return createApiRequest<BatchedUsersApi>(batchedSchemas, API_URL, 'test');
+  return createApiRequest<BatchedUsersApi>(API_URL, 'test');
 }
 
 function createPlainRequestor() {
-  return new Requestor<PlainUsersApi, '/users', 'GET'>('/users', 'GET', createPlainRequest(), new Cache());
+  return new Requestor<PlainUsersApi, '/users', 'GET'>(plainUsers_GET, createPlainRequest(), new Cache());
 }
 
 function createBatchedRequestor(
-  batchDetails?: ConstructorParameters<typeof Requestor<BatchedUsersApi, '/users', 'POST'>>[4]
+  batchDetails?: ConstructorParameters<typeof Requestor<BatchedUsersApi, '/users', 'POST'>>[3]
 ) {
   return new Requestor<BatchedUsersApi, '/users', 'POST'>(
-    '/users',
-    'POST',
+    batchedUsers_POST,
     createBatchedRequest(),
     new Cache(),
     batchDetails
@@ -355,8 +354,7 @@ describe('Query', () => {
     const fetchMock = vi.fn().mockReturnValue(pending.promise);
     vi.stubGlobal('fetch', fetchMock);
     const query = new Query<PlainUsersApi, '/users', 'GET'>({
-      path: '/users',
-      method: 'GET',
+      endpoint: plainUsers_GET,
       input: { id: 1 },
       requestor: createPlainRequestor(),
       cache: new Cache()
@@ -378,8 +376,7 @@ describe('Query', () => {
     const fetchMock = vi.fn(async () => jsonFetchResponse({ id: 1, name: 'Ada' }));
     vi.stubGlobal('fetch', fetchMock);
     const query = new Query<PlainUsersApi, '/users', 'GET'>({
-      path: '/users',
-      method: 'GET',
+      endpoint: plainUsers_GET,
       input: { id: 1 },
       requestor: createPlainRequestor(),
       cache: new Cache()
@@ -400,8 +397,7 @@ describe('Query', () => {
     );
     vi.stubGlobal('fetch', fetchMock);
     const query = new Query<PlainUsersApi, '/users', 'GET'>({
-      path: '/users',
-      method: 'GET',
+      endpoint: plainUsers_GET,
       input: { id: 1 },
       requestor: createPlainRequestor(),
       cache: new Cache()
@@ -430,8 +426,7 @@ describe('Query', () => {
     const fetchMock = vi.fn(async () => withResponseOverrides(jsonFetchResponse({ id: 1 })));
     vi.stubGlobal('fetch', fetchMock);
     const query = new Query<PlainUsersApi, '/users', 'GET'>({
-      path: '/users',
-      method: 'GET',
+      endpoint: plainUsers_GET,
       input: { id: 1 },
       requestor: createPlainRequestor(),
       cache: new Cache()
@@ -457,8 +452,7 @@ describe('Query', () => {
     const fetchMock = vi.fn(async () => jsonFetchResponse({ id: 1, active: true }));
     vi.stubGlobal('fetch', fetchMock);
     const query = new Query<PlainUsersApi, '/users', 'GET'>({
-      path: '/users',
-      method: 'GET',
+      endpoint: plainUsers_GET,
       input: { id: 1 },
       requestor: createPlainRequestor(),
       cache: new Cache()
@@ -476,8 +470,7 @@ describe('Query', () => {
     const fetchMock = vi.fn(async () => jsonFetchResponse({ message: 'missing' }, 404));
     vi.stubGlobal('fetch', fetchMock);
     const query = new Query<PlainUsersApi, '/users', 'GET'>({
-      path: '/users',
-      method: 'GET',
+      endpoint: plainUsers_GET,
       input: { id: 99 },
       requestor: createPlainRequestor(),
       cache: new Cache()
@@ -505,8 +498,7 @@ describe('Query', () => {
     });
     vi.stubGlobal('fetch', fetchMock);
     const query = new Query<PlainUsersApi, '/users', 'GET'>({
-      path: '/users',
-      method: 'GET',
+      endpoint: plainUsers_GET,
       input: { id: 1 },
       requestor: createPlainRequestor(),
       cache: new Cache()
@@ -532,8 +524,7 @@ describe('Query', () => {
     });
     vi.stubGlobal('fetch', fetchMock);
     const query = new Query<PlainUsersApi, '/users', 'GET'>({
-      path: '/users',
-      method: 'GET',
+      endpoint: plainUsers_GET,
       input: { id: 1 },
       requestor: createPlainRequestor(),
       cache: new Cache()
@@ -558,8 +549,7 @@ describe('Query', () => {
     });
     vi.stubGlobal('fetch', fetchMock);
     const query = new Query<PlainUsersApi, '/users', 'GET'>({
-      path: '/users',
-      method: 'GET',
+      endpoint: plainUsers_GET,
       input: { id: 1 },
       requestor: createPlainRequestor(),
       cache: new Cache(),

package/src/lib/api/query/utils.svelte.ts

@@ -1,9 +1,10 @@
 import { stringify } from 'devalue';
+import { endpointKey } from 'ts-ag';
 
-export function batchQueryKey(path: string, method: string) {
-  return `${path}_${method}`;
+export function batchQueryKey(endpoint: { path: string; method: string }) {
+  return endpointKey(endpoint);
 }
 
-export function cacheKey(path: string, method: string, input: any) {
-  return `${path}_${method}_${stringify(input)}`;
+export function cacheKey(endpoint: { path: string; method: string }, input: any) {
+  return `${endpointKey(endpoint)} ${stringify(input)}`;
 }