@forinda/kickjs-client 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -10,7 +10,7 @@ pnpm add @forinda/kickjs-client
10
10
  ```ts
11
11
  import { createClient } from '@forinda/kickjs-client'
12
12
 
13
- const api = createClient<KickRoutes.Api>({ baseUrl: 'https://api.example.com/api/v1' })
13
+ const api = createClient<KickApi>({ baseUrl: 'https://api.example.com/api/v1' })
14
14
 
15
15
  const task = await api.get('/tasks/:id', { params: { id: '42' } })
16
16
  // ^ the handler's actual response type — inferred, not declared
package/dist/index.d.ts CHANGED
@@ -18,6 +18,24 @@ type ClientMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
18
18
  /** Paths in the map registered under a given verb. */
19
19
  type PathsFor<Api extends ApiMap, M extends ClientMethod> = { [K in keyof Api]: K extends `${M} ${infer P}` ? P : never }[keyof Api];
20
20
  type ShapeOf<Api extends ApiMap, M extends ClientMethod, P extends string> = `${M} ${P}` extends keyof Api ? Api[`${M} ${P}`] extends RouteShapeLike ? Api[`${M} ${P}`] : never : never;
21
+ type SsePayloadOf<S> = S extends object ? '__sse' extends keyof S ? NonNullable<S['__sse']> : never : never;
22
+ /** GET paths whose response is an SSE stream (`return ctx.sse<T>()`). */
23
+ type StreamPathsFor<Api extends ApiMap> = { [K in keyof Api]: K extends `GET ${infer P}` ? Api[K] extends RouteShapeLike ? [SsePayloadOf<Api[K]['response']>] extends [never] ? never : P : never : never }[keyof Api];
24
+ type ArgsFor<S extends RouteShapeLike, M extends ClientMethod> = Record<string, never> extends RequestOptions<S, M> ? [options?: RequestOptions<S, M>] : [options: RequestOptions<S, M>];
25
+ /** One parsed server-sent event. */
26
+ interface SseEvent<T = unknown> {
27
+ /** JSON-parsed `data:` payload (raw string when not valid JSON). */
28
+ data: T;
29
+ /** The `event:` name, when the server sent one. */
30
+ event?: string;
31
+ /** The `id:` field, when the server sent one. */
32
+ id?: string;
33
+ }
34
+ /** Typed async-iterable SSE connection — `for await`, then `close()`. */
35
+ interface SseStream<T = unknown> extends AsyncIterable<SseEvent<T>> {
36
+ /** Abort the underlying request and end iteration. */
37
+ close(): void;
38
+ }
21
39
  type ParamsField<T> = unknown extends T ? {
22
40
  params?: Record<string, string | number>;
23
41
  } : Record<string, never> extends T ? {
@@ -25,7 +43,9 @@ type ParamsField<T> = unknown extends T ? {
25
43
  } : {
26
44
  params: T;
27
45
  };
28
- type BodyField<T> = unknown extends T ? {
46
+ type BodyField<T, M extends ClientMethod> = M extends 'GET' ? {
47
+ body?: never;
48
+ } : unknown extends T ? {
29
49
  body?: unknown;
30
50
  } : {
31
51
  body: T;
@@ -37,10 +57,10 @@ type QueryField<T> = unknown extends T ? {
37
57
  } : {
38
58
  query?: T;
39
59
  };
40
- type RequestOptions<S extends RouteShapeLike> = {
60
+ type RequestOptions<S extends RouteShapeLike, M extends ClientMethod = ClientMethod> = {
41
61
  /** Extra headers merged over the client-level ones. */headers?: Record<string, string>; /** AbortSignal for cancellation. */
42
62
  signal?: AbortSignal;
43
- } & ParamsField<S['params']> & BodyField<S['body']> & QueryField<S['query']>;
63
+ } & ParamsField<S['params']> & BodyField<S['body'], M> & QueryField<S['query']>;
44
64
  interface ClientOptions {
45
65
  /**
46
66
  * Base URL INCLUDING the mount prefix + version the server adds at
@@ -64,11 +84,21 @@ declare class KickClientError extends Error {
64
84
  constructor(status: number, body: unknown, response: Response);
65
85
  }
66
86
  interface KickClient<Api extends ApiMap> {
67
- get<P extends PathsFor<Api, 'GET'> & string>(path: P, options?: RequestOptions<ShapeOf<Api, 'GET', P>>): Promise<ShapeOf<Api, 'GET', P>['response']>;
68
- post<P extends PathsFor<Api, 'POST'> & string>(path: P, options?: RequestOptions<ShapeOf<Api, 'POST', P>>): Promise<ShapeOf<Api, 'POST', P>['response']>;
69
- put<P extends PathsFor<Api, 'PUT'> & string>(path: P, options?: RequestOptions<ShapeOf<Api, 'PUT', P>>): Promise<ShapeOf<Api, 'PUT', P>['response']>;
70
- delete<P extends PathsFor<Api, 'DELETE'> & string>(path: P, options?: RequestOptions<ShapeOf<Api, 'DELETE', P>>): Promise<ShapeOf<Api, 'DELETE', P>['response']>;
71
- patch<P extends PathsFor<Api, 'PATCH'> & string>(path: P, options?: RequestOptions<ShapeOf<Api, 'PATCH', P>>): Promise<ShapeOf<Api, 'PATCH', P>['response']>;
87
+ get<P extends PathsFor<Api, 'GET'> & string>(path: P, ...args: ArgsFor<ShapeOf<Api, 'GET', P>, 'GET'>): Promise<ShapeOf<Api, 'GET', P>['response']>;
88
+ /**
89
+ * Open a typed SSE connection to a route whose handler
90
+ * `return ctx.sse<T>()` — events arrive as `SseEvent<T>`:
91
+ *
92
+ * ```ts
93
+ * const stream = await api.stream('/events')
94
+ * for await (const ev of stream) console.log(ev.data) // ev.data: T
95
+ * ```
96
+ */
97
+ stream<P extends StreamPathsFor<Api> & string>(path: P, ...args: ArgsFor<ShapeOf<Api, 'GET', P>, 'GET'>): Promise<SseStream<SsePayloadOf<ShapeOf<Api, 'GET', P>['response']>>>;
98
+ post<P extends PathsFor<Api, 'POST'> & string>(path: P, ...args: ArgsFor<ShapeOf<Api, 'POST', P>, 'POST'>): Promise<ShapeOf<Api, 'POST', P>['response']>;
99
+ put<P extends PathsFor<Api, 'PUT'> & string>(path: P, ...args: ArgsFor<ShapeOf<Api, 'PUT', P>, 'PUT'>): Promise<ShapeOf<Api, 'PUT', P>['response']>;
100
+ delete<P extends PathsFor<Api, 'DELETE'> & string>(path: P, ...args: ArgsFor<ShapeOf<Api, 'DELETE', P>, 'DELETE'>): Promise<ShapeOf<Api, 'DELETE', P>['response']>;
101
+ patch<P extends PathsFor<Api, 'PATCH'> & string>(path: P, ...args: ArgsFor<ShapeOf<Api, 'PATCH', P>, 'PATCH'>): Promise<ShapeOf<Api, 'PATCH', P>['response']>;
72
102
  }
73
103
  /**
74
104
  * Create a typed client over a `KickRoutes.Api`-shaped map.
@@ -95,5 +125,5 @@ declare function createTestClient<Api extends ApiMap>(app: FetchLike, options?:
95
125
  baseUrl?: string;
96
126
  }): KickClient<Api>;
97
127
  //#endregion
98
- export { ClientMethod, ClientOptions, FetchLike, KickClient, KickClientError, RequestOptions, RouteShapeLike, createClient, createTestClient };
128
+ export { ClientMethod, ClientOptions, FetchLike, KickClient, KickClientError, RequestOptions, RouteShapeLike, SseEvent, SseStream, createClient, createTestClient };
99
129
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":"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"}
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @forinda/kickjs-client v0.1.1
2
+ * @forinda/kickjs-client v0.2.0
3
3
  *
4
4
  * Copyright (c) Felix Orinda
5
5
  *
@@ -8,5 +8,7 @@
8
8
  *
9
9
  * @license MIT
10
10
  */
11
- var KickClientError=class extends Error{status;body;response;constructor(status,body,response){super(typeof body==`object`&&body&&`detail`in body?String(body.detail):typeof body==`object`&&body&&`error`in body?String(body.error):`Request failed with status ${status}`),this.status=status,this.body=body,this.response=response,this.name=`KickClientError`}};function fillPath(path,params){return path.replace(/:([A-Za-z0-9_]+)/g,(_,name)=>{let value=params?.[name];if(value===void 0)throw Error(`@forinda/kickjs-client: missing path param ':${name}' for '${path}'`);return encodeURIComponent(String(value))})}function buildQuery(query){if(!query)return``;let qs=new URLSearchParams;for(let[key,value]of Object.entries(query))if(value!=null)if(Array.isArray(value))for(let v of value)qs.append(key,String(v));else qs.append(key,String(value));let s=qs.toString();return s?`?${s}`:``}function createClient(options){let baseUrl=options.baseUrl.replace(/\/$/,``),doFetch=options.fetch??(req=>fetch(req));async function run(method,path,opts={}){let clientHeaders=typeof options.headers==`function`?await options.headers():options.headers??{},headers=new Headers({...clientHeaders,...opts.headers}),hasBody=opts.body!==void 0;hasBody&&!headers.has(`content-type`)&&headers.set(`content-type`,`application/json`);let url=`${baseUrl}${fillPath(path,opts.params)}${buildQuery(opts.query)}`,request=new Request(url,{method,headers,body:hasBody?JSON.stringify(opts.body):void 0,signal:opts.signal}),response=await doFetch(request),contentType=response.headers.get(`content-type`)??``,body=response.status===204?void 0:contentType.includes(`json`)?await response.json().catch(()=>void 0):await response.text();if(!response.ok)throw new KickClientError(response.status,body,response);return body}return{get:(path,opts)=>run(`GET`,path,opts),post:(path,opts)=>run(`POST`,path,opts),put:(path,opts)=>run(`PUT`,path,opts),delete:(path,opts)=>run(`DELETE`,path,opts),patch:(path,opts)=>run(`PATCH`,path,opts)}}function createTestClient(app,options={}){return createClient({...options,baseUrl:options.baseUrl??`http://test/api/v1`,fetch:request=>app.fetch(request)})}export{KickClientError,createClient,createTestClient};
11
+ var KickClientError=class extends Error{status;body;response;constructor(status,body,response){super(typeof body==`object`&&body&&`detail`in body?String(body.detail):typeof body==`object`&&body&&`error`in body?String(body.error):`Request failed with status ${status}`),this.status=status,this.body=body,this.response=response,this.name=`KickClientError`}};function fillPath(path,params){return path.replace(/:([A-Za-z0-9_]+)/g,(_,name)=>{let value=params?.[name];if(value===void 0)throw Error(`@forinda/kickjs-client: missing path param ':${name}' for '${path}'`);return encodeURIComponent(String(value))})}function parseSseBlock(block){let event,id,dataLines=[];for(let line of block.split(`
12
+ `))line.startsWith(`:`)||(line.startsWith(`data:`)?dataLines.push(line.slice(5).trimStart()):line.startsWith(`event:`)?event=line.slice(6).trim():line.startsWith(`id:`)&&(id=line.slice(3).trim()));if(dataLines.length===0)return null;let raw=dataLines.join(`
13
+ `),data=raw;try{data=JSON.parse(raw)}catch{}return{data,...event?{event}:{},...id?{id}:{}}}function buildQuery(query){if(!query)return``;let qs=new URLSearchParams;for(let[key,value]of Object.entries(query))if(value!=null)if(Array.isArray(value))for(let v of value)qs.append(key,String(v));else qs.append(key,String(value));let s=qs.toString();return s?`?${s}`:``}function createClient(options){let baseUrl=options.baseUrl.replace(/\/$/,``),doFetch=options.fetch??(req=>fetch(req));async function buildRequest(method,path,opts){let clientHeaders=typeof options.headers==`function`?await options.headers():options.headers??{},headers=new Headers({...clientHeaders,...opts.headers}),hasBody=method!==`GET`&&opts.body!==void 0;hasBody&&!headers.has(`content-type`)&&headers.set(`content-type`,`application/json`);let url=`${baseUrl}${fillPath(path,opts.params)}${buildQuery(opts.query)}`;return new Request(url,{method,headers,body:hasBody?JSON.stringify(opts.body):void 0,signal:opts.signal})}async function run(method,path,opts={}){let request=await buildRequest(method,path,opts),response=await doFetch(request),contentType=response.headers.get(`content-type`)??``,body=response.status===204?void 0:contentType.includes(`json`)?await response.json().catch(()=>void 0):await response.text();if(!response.ok)throw new KickClientError(response.status,body,response);return body}async function openStream(path,opts={}){let controller=new AbortController;opts.signal?.addEventListener(`abort`,()=>controller.abort(),{once:!0});let request=await buildRequest(`GET`,path,{...opts,signal:controller.signal,headers:{accept:`text/event-stream`,...opts.headers}}),response=await doFetch(request);if(!response.ok||!response.body){let body=(response.headers.get(`content-type`)??``).includes(`json`)?await response.json().catch(()=>void 0):await response.text().catch(()=>void 0);throw new KickClientError(response.status,body,response)}let reader=response.body.getReader(),decoder=new TextDecoder;async function*events(){let buffer=``;try{for(;;){let{done,value}=await reader.read();if(done)break;buffer+=decoder.decode(value,{stream:!0});let blocks=buffer.split(/\n\n/);buffer=blocks.pop()??``;for(let block of blocks){let ev=parseSseBlock(block);ev&&(yield ev)}}}finally{controller.abort(),reader.releaseLock()}}return{[Symbol.asyncIterator]:events,close:()=>controller.abort()}}return{get:(path,opts)=>run(`GET`,path,opts),stream:(path,opts)=>openStream(path,opts??{}),post:(path,opts)=>run(`POST`,path,opts),put:(path,opts)=>run(`PUT`,path,opts),delete:(path,opts)=>run(`DELETE`,path,opts),patch:(path,opts)=>run(`PATCH`,path,opts)}}function createTestClient(app,options={}){return createClient({...options,baseUrl:options.baseUrl??`http://test/api/v1`,fetch:request=>app.fetch(request)})}export{KickClientError,createClient,createTestClient};
12
14
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// @forinda/kickjs-client — typed fetch client for KickJS APIs.\n//\n// Consumes the flat `KickRoutes.Api` map that `kick typegen` emits\n// (response-inference-design.md R3): keys are `'METHOD /path'`, values are\n// the route shapes (`params` / `body` / `query` / `response`). The client is\n// a ~150-line fetch wrapper — every type below exists so the CALL SITE\n// infers exactly:\n//\n// ```ts\n// const api = createClient<KickRoutes.Api>({ baseUrl: 'https://x/api/v1' })\n// const task = await api.post('/tasks/:id', { params: { id }, body })\n// // ^ the handler's actual response type\n// ```\n//\n// Runtime-neutral: fetch/URL/Headers only — browsers, node ≥ 20, Bun, Deno,\n// and edge workers (pairs with `@forinda/kickjs/web` on the server side).\n\n/**\n * The per-route shape `kick typegen` emits into `KickRoutes.Api`.\n * Deliberately re-declares (NOT imports) @forinda/kickjs's `RouteShape`:\n * frontends installing this client must never need the server package.\n * Keep the field list in sync with `RouteShape` in kickjs http/context.ts.\n */\nexport interface RouteShapeLike {\n params: unknown\n body: unknown\n query: unknown\n response: unknown\n}\n\n// `object`, not `Record<string, RouteShapeLike>`: the generated\n// `KickRoutes.Api` is an INTERFACE, which has no string index signature and\n// would fail a Record constraint. Key/value conformance is guaranteed by the\n// generator; PathsFor/ShapeOf only rely on `keyof Api`.\ntype ApiMap = object\n\n/** HTTP verbs the route decorators produce. */\nexport type ClientMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'\n\n/** Paths in the map registered under a given verb. */\ntype PathsFor<Api extends ApiMap, M extends ClientMethod> = {\n [K in keyof Api]: K extends `${M} ${infer P}` ? P : never\n}[keyof Api]\n\n// Fallback is `never` ON PURPOSE: P is already constrained to PathsFor, so a\n// failed key lookup means the map and the client's key math drifted — that\n// must fail loudly at the call site, not silently degrade to unknown.\ntype ShapeOf<\n Api extends ApiMap,\n M extends ClientMethod,\n P extends string,\n> = `${M} ${P}` extends keyof Api\n ? Api[`${M} ${P}`] extends RouteShapeLike\n ? Api[`${M} ${P}`]\n : never\n : never\n\n// Paramless routes emit `params: {}` and unschema'd bodies emit\n// `body: unknown` — both become OPTIONAL fields; a concrete shape is\n// required so forgetting `params` on `/users/:id` is a type error.\ntype ParamsField<T> = unknown extends T\n ? { params?: Record<string, string | number> }\n : Record<string, never> extends T\n ? { params?: T }\n : { params: T }\n\ntype BodyField<T> = unknown extends T ? { body?: unknown } : { body: T }\n\n/** Loose fallback for routes without a statically-known query shape. */\ntype LooseQuery = Record<string, string | number | boolean | Array<string | number>>\n\n// Routes with a typegen-known query shape (Zod schema or the\n// @ApiQueryParams-derived filter/sort/q/page/limit object) constrain\n// `query` — sort fields autocomplete as '-createdAt' | 'createdAt' | …\ntype QueryField<T> = unknown extends T ? { query?: LooseQuery } : { query?: T }\n\nexport type RequestOptions<S extends RouteShapeLike> = {\n /** Extra headers merged over the client-level ones. */\n headers?: Record<string, string>\n /** AbortSignal for cancellation. */\n signal?: AbortSignal\n} & ParamsField<S['params']> &\n BodyField<S['body']> &\n QueryField<S['query']>\n\nexport interface ClientOptions {\n /**\n * Base URL INCLUDING the mount prefix + version the server adds at\n * bootstrap (default `/api/v1`) — `KickRoutes.Api` keys are module-mount\n * relative: `'GET /users/:id'` + baseUrl `https://x/api/v1`.\n */\n baseUrl: string\n /** Static headers, or a factory invoked per request (auth tokens). */\n headers?:\n | Record<string, string>\n | (() => Record<string, string> | Promise<Record<string, string>>)\n /**\n * Custom fetch — inject a platform fetch, a mock, or a KickJS web app's\n * own handler for network-free tests: `{ fetch: app.fetch }`.\n */\n fetch?: (request: Request) => Promise<Response>\n}\n\n/** Non-2xx responses throw this — carries the parsed body (RFC 9457 problem details when the server used `ctx.problem`). */\nexport class KickClientError extends Error {\n constructor(\n readonly status: number,\n readonly body: unknown,\n readonly response: Response,\n ) {\n super(\n typeof body === 'object' && body !== null && 'detail' in body\n ? String((body as { detail: unknown }).detail)\n : typeof body === 'object' && body !== null && 'error' in body\n ? String((body as { error: unknown }).error)\n : `Request failed with status ${status}`,\n )\n this.name = 'KickClientError'\n }\n}\n\nexport interface KickClient<Api extends ApiMap> {\n get<P extends PathsFor<Api, 'GET'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'GET', P>>,\n ): Promise<ShapeOf<Api, 'GET', P>['response']>\n post<P extends PathsFor<Api, 'POST'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'POST', P>>,\n ): Promise<ShapeOf<Api, 'POST', P>['response']>\n put<P extends PathsFor<Api, 'PUT'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'PUT', P>>,\n ): Promise<ShapeOf<Api, 'PUT', P>['response']>\n delete<P extends PathsFor<Api, 'DELETE'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'DELETE', P>>,\n ): Promise<ShapeOf<Api, 'DELETE', P>['response']>\n patch<P extends PathsFor<Api, 'PATCH'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'PATCH', P>>,\n ): Promise<ShapeOf<Api, 'PATCH', P>['response']>\n}\n\ninterface AnyRequestOptions {\n headers?: Record<string, string>\n signal?: AbortSignal\n query?: Record<string, unknown>\n params?: Record<string, string | number>\n body?: unknown\n}\n\n/** Substitute `:param` segments; throw on any left unfilled. */\nfunction fillPath(path: string, params?: Record<string, string | number>): string {\n const filled = path.replace(/:([A-Za-z0-9_]+)/g, (_, name: string) => {\n const value = params?.[name]\n if (value === undefined) {\n throw new Error(`@forinda/kickjs-client: missing path param ':${name}' for '${path}'`)\n }\n return encodeURIComponent(String(value))\n })\n return filled\n}\n\nfunction buildQuery(query?: Record<string, unknown>): string {\n if (!query) return ''\n const qs = new URLSearchParams()\n for (const [key, value] of Object.entries(query)) {\n if (value === undefined || value === null) continue\n if (Array.isArray(value)) for (const v of value) qs.append(key, String(v))\n else qs.append(key, String(value))\n }\n const s = qs.toString()\n return s ? `?${s}` : ''\n}\n\n/**\n * Create a typed client over a `KickRoutes.Api`-shaped map.\n * Generic-only consumption — no runtime dependency on the generated file.\n */\nexport function createClient<Api extends ApiMap>(options: ClientOptions): KickClient<Api> {\n const baseUrl = options.baseUrl.replace(/\\/$/, '')\n const doFetch = options.fetch ?? ((req: Request) => fetch(req))\n\n async function run(method: ClientMethod, path: string, opts: AnyRequestOptions = {}) {\n const clientHeaders =\n typeof options.headers === 'function' ? await options.headers() : (options.headers ?? {})\n const headers = new Headers({ ...clientHeaders, ...opts.headers })\n const hasBody = opts.body !== undefined\n if (hasBody && !headers.has('content-type')) {\n headers.set('content-type', 'application/json')\n }\n\n const url = `${baseUrl}${fillPath(path, opts.params)}${buildQuery(opts.query)}`\n const request = new Request(url, {\n method,\n headers,\n body: hasBody ? JSON.stringify(opts.body) : undefined,\n signal: opts.signal,\n })\n\n const response = await doFetch(request)\n const contentType = response.headers.get('content-type') ?? ''\n const body =\n response.status === 204\n ? undefined\n : contentType.includes('json')\n ? await response.json().catch(() => undefined)\n : await response.text()\n\n if (!response.ok) throw new KickClientError(response.status, body, response)\n return body\n }\n\n return {\n get: (path, opts) => run('GET', path, opts as AnyRequestOptions),\n post: (path, opts) => run('POST', path, opts as AnyRequestOptions),\n put: (path, opts) => run('PUT', path, opts as AnyRequestOptions),\n delete: (path, opts) => run('DELETE', path, opts as AnyRequestOptions),\n patch: (path, opts) => run('PATCH', path, opts as AnyRequestOptions),\n } as KickClient<Api>\n}\n\n/** Anything with a web-standard fetch — a `createWebApp()` result, a Worker, a mock. */\nexport interface FetchLike {\n fetch(request: Request): Promise<Response>\n}\n\n/**\n * Typed client over an in-process app — network-free full-stack tests:\n *\n * ```ts\n * const app = createWebApp({ h3, modules })\n * const api = createTestClient<KickRoutes.Api>(app)\n * expect(await api.get('/tasks/:id', { params: { id: '1' } })).toEqual(...)\n * ```\n *\n * `baseUrl` defaults to `http://test/api/v1` (the bootstrap default prefix);\n * override it when the server uses a custom `apiPrefix`/version.\n */\nexport function createTestClient<Api extends ApiMap>(\n app: FetchLike,\n options: Omit<ClientOptions, 'fetch' | 'baseUrl'> & { baseUrl?: string } = {},\n): KickClient<Api> {\n return createClient<Api>({\n ...options,\n // AFTER the spread — an explicit `baseUrl: undefined` key in options\n // must not clobber the default (spread copies undefined-valued keys).\n baseUrl: options.baseUrl ?? 'http://test/api/v1',\n fetch: (request) => app.fetch(request),\n })\n}\n"],"mappings":";;;;;;;;;;AAwGA,IAAa,gBAAb,cAAqC,KAAM,CAE9B,OACA,KACA,SAHX,YACE,OACA,KACA,SACA,CACA,MACE,OAAO,MAAS,UAAY,MAAiB,WAAY,KACrD,OAAQ,KAA6B,MAAM,EAC3C,OAAO,MAAS,UAAY,MAAiB,UAAW,KACtD,OAAQ,KAA4B,KAAK,EACzC,8BAA8B,QACtC,EAVS,KAAA,OAAA,OACA,KAAA,KAAA,KACA,KAAA,SAAA,SAST,KAAK,KAAO,iBACd,CACF,EAkCA,SAAS,SAAS,KAAc,OAAkD,CAQhF,OAPe,KAAK,QAAQ,qBAAsB,EAAG,OAAiB,CACpE,IAAM,MAAQ,SAAS,MACvB,GAAI,QAAU,IAAA,GACZ,MAAU,MAAM,gDAAgD,KAAK,SAAS,KAAK,EAAE,EAEvF,OAAO,mBAAmB,OAAO,KAAK,CAAC,CACzC,CACY,CACd,CAEA,SAAS,WAAW,MAAyC,CAC3D,GAAI,CAAC,MAAO,MAAO,GACnB,IAAM,GAAK,IAAI,gBACf,IAAK,GAAM,CAAC,IAAK,SAAU,OAAO,QAAQ,KAAK,EACzC,UAAiC,KACrC,GAAI,MAAM,QAAQ,KAAK,EAAG,IAAK,IAAM,KAAK,MAAO,GAAG,OAAO,IAAK,OAAO,CAAC,CAAC,OACpE,GAAG,OAAO,IAAK,OAAO,KAAK,CAAC,EAEnC,IAAM,EAAI,GAAG,SAAS,EACtB,OAAO,EAAI,IAAI,IAAM,EACvB,CAMA,SAAgB,aAAiC,QAAyC,CACxF,IAAM,QAAU,QAAQ,QAAQ,QAAQ,MAAO,EAAE,EAC3C,QAAU,QAAQ,QAAW,KAAiB,MAAM,GAAG,GAE7D,eAAe,IAAI,OAAsB,KAAc,KAA0B,CAAC,EAAG,CACnF,IAAM,cACJ,OAAO,QAAQ,SAAY,WAAa,MAAM,QAAQ,QAAQ,EAAK,QAAQ,SAAW,CAAC,EACnF,QAAU,IAAI,QAAQ,CAAE,GAAG,cAAe,GAAG,KAAK,OAAQ,CAAC,EAC3D,QAAU,KAAK,OAAS,IAAA,GAC1B,SAAW,CAAC,QAAQ,IAAI,cAAc,GACxC,QAAQ,IAAI,eAAgB,kBAAkB,EAGhD,IAAM,IAAM,GAAG,UAAU,SAAS,KAAM,KAAK,MAAM,IAAI,WAAW,KAAK,KAAK,IACtE,QAAU,IAAI,QAAQ,IAAK,CAC/B,OACA,QACA,KAAM,QAAU,KAAK,UAAU,KAAK,IAAI,EAAI,IAAA,GAC5C,OAAQ,KAAK,MACf,CAAC,EAEK,SAAW,MAAM,QAAQ,OAAO,EAChC,YAAc,SAAS,QAAQ,IAAI,cAAc,GAAK,GACtD,KACJ,SAAS,SAAW,IAChB,IAAA,GACA,YAAY,SAAS,MAAM,EACzB,MAAM,SAAS,KAAK,CAAC,CAAC,UAAY,IAAA,EAAS,EAC3C,MAAM,SAAS,KAAK,EAE5B,GAAI,CAAC,SAAS,GAAI,MAAM,IAAI,gBAAgB,SAAS,OAAQ,KAAM,QAAQ,EAC3E,OAAO,IACT,CAEA,MAAO,CACL,KAAM,KAAM,OAAS,IAAI,MAAO,KAAM,IAAyB,EAC/D,MAAO,KAAM,OAAS,IAAI,OAAQ,KAAM,IAAyB,EACjE,KAAM,KAAM,OAAS,IAAI,MAAO,KAAM,IAAyB,EAC/D,QAAS,KAAM,OAAS,IAAI,SAAU,KAAM,IAAyB,EACrE,OAAQ,KAAM,OAAS,IAAI,QAAS,KAAM,IAAyB,CACrE,CACF,CAmBA,SAAgB,iBACd,IACA,QAA2E,CAAC,EAC3D,CACjB,OAAO,aAAkB,CACvB,GAAG,QAGH,QAAS,QAAQ,SAAW,qBAC5B,MAAQ,SAAY,IAAI,MAAM,OAAO,CACvC,CAAC,CACH"}
1
+ {"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// @forinda/kickjs-client — typed fetch client for KickJS APIs.\n//\n// Consumes the flat `KickRoutes.Api` map that `kick typegen` emits\n// (response-inference-design.md R3): keys are `'METHOD /path'`, values are\n// the route shapes (`params` / `body` / `query` / `response`). The client is\n// a ~150-line fetch wrapper — every type below exists so the CALL SITE\n// infers exactly:\n//\n// ```ts\n// const api = createClient<KickRoutes.Api>({ baseUrl: 'https://x/api/v1' })\n// const task = await api.post('/tasks/:id', { params: { id }, body })\n// // ^ the handler's actual response type\n// ```\n//\n// Runtime-neutral: fetch/URL/Headers only — browsers, node ≥ 20, Bun, Deno,\n// and edge workers (pairs with `@forinda/kickjs/web` on the server side).\n\n/**\n * The per-route shape `kick typegen` emits into `KickRoutes.Api`.\n * Deliberately re-declares (NOT imports) @forinda/kickjs's `RouteShape`:\n * frontends installing this client must never need the server package.\n * Keep the field list in sync with `RouteShape` in kickjs http/context.ts.\n */\nexport interface RouteShapeLike {\n params: unknown\n body: unknown\n query: unknown\n response: unknown\n}\n\n// `object`, not `Record<string, RouteShapeLike>`: the generated\n// `KickRoutes.Api` is an INTERFACE, which has no string index signature and\n// would fail a Record constraint. Key/value conformance is guaranteed by the\n// generator; PathsFor/ShapeOf only rely on `keyof Api`.\ntype ApiMap = object\n\n/** HTTP verbs the route decorators produce. */\nexport type ClientMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'\n\n/** Paths in the map registered under a given verb. */\ntype PathsFor<Api extends ApiMap, M extends ClientMethod> = {\n [K in keyof Api]: K extends `${M} ${infer P}` ? P : never\n}[keyof Api]\n\n// Fallback is `never` ON PURPOSE: P is already constrained to PathsFor, so a\n// failed key lookup means the map and the client's key math drifted — that\n// must fail loudly at the call site, not silently degrade to unknown.\ntype ShapeOf<\n Api extends ApiMap,\n M extends ClientMethod,\n P extends string,\n> = `${M} ${P}` extends keyof Api\n ? Api[`${M} ${P}`] extends RouteShapeLike\n ? Api[`${M} ${P}`]\n : never\n : never\n\n// ── SSE typing ────────────────────────────────────────────────────────\n// Server handlers that `return ctx.sse<T>()` put an `SseHandler<T>` into the\n// map's response slot; its phantom `__sse` property carries T structurally,\n// so the client detects SSE routes without importing server types. The\n// optional-property check must be non-vacuous — `'__sse' extends keyof S`,\n// NOT `S extends { __sse?: … }` (every object vacuously extends the latter).\ntype SsePayloadOf<S> = S extends object\n ? '__sse' extends keyof S\n ? NonNullable<S['__sse']>\n : never\n : never\n\n/** GET paths whose response is an SSE stream (`return ctx.sse<T>()`). */\ntype StreamPathsFor<Api extends ApiMap> = {\n [K in keyof Api]: K extends `GET ${infer P}`\n ? Api[K] extends RouteShapeLike\n ? [SsePayloadOf<Api[K]['response']>] extends [never]\n ? never\n : P\n : never\n : never\n}[keyof Api]\n\n// Options argument is OPTIONAL only when the shape requires nothing\n// (no concrete params, no required body) — otherwise omitting it must be\n// a compile error, not a runtime missing-param throw.\ntype ArgsFor<S extends RouteShapeLike, M extends ClientMethod> =\n Record<string, never> extends RequestOptions<S, M>\n ? [options?: RequestOptions<S, M>]\n : [options: RequestOptions<S, M>]\n\n/** One parsed server-sent event. */\nexport interface SseEvent<T = unknown> {\n /** JSON-parsed `data:` payload (raw string when not valid JSON). */\n data: T\n /** The `event:` name, when the server sent one. */\n event?: string\n /** The `id:` field, when the server sent one. */\n id?: string\n}\n\n/** Typed async-iterable SSE connection — `for await`, then `close()`. */\nexport interface SseStream<T = unknown> extends AsyncIterable<SseEvent<T>> {\n /** Abort the underlying request and end iteration. */\n close(): void\n}\n\n// Paramless routes emit `params: {}` and unschema'd bodies emit\n// `body: unknown` — both become OPTIONAL fields; a concrete shape is\n// required so forgetting `params` on `/users/:id` is a type error.\ntype ParamsField<T> = unknown extends T\n ? { params?: Record<string, string | number> }\n : Record<string, never> extends T\n ? { params?: T }\n : { params: T }\n\n// GET requests must not carry a body — `new Request(url, { method: 'GET',\n// body })` throws at runtime, so the type forbids it up front.\ntype BodyField<T, M extends ClientMethod> = M extends 'GET'\n ? { body?: never }\n : unknown extends T\n ? { body?: unknown }\n : { body: T }\n\n/** Loose fallback for routes without a statically-known query shape. */\ntype LooseQuery = Record<string, string | number | boolean | Array<string | number>>\n\n// Routes with a typegen-known query shape (Zod schema or the\n// @ApiQueryParams-derived filter/sort/q/page/limit object) constrain\n// `query` — sort fields autocomplete as '-createdAt' | 'createdAt' | …\ntype QueryField<T> = unknown extends T ? { query?: LooseQuery } : { query?: T }\n\nexport type RequestOptions<S extends RouteShapeLike, M extends ClientMethod = ClientMethod> = {\n /** Extra headers merged over the client-level ones. */\n headers?: Record<string, string>\n /** AbortSignal for cancellation. */\n signal?: AbortSignal\n} & ParamsField<S['params']> &\n BodyField<S['body'], M> &\n QueryField<S['query']>\n\nexport interface ClientOptions {\n /**\n * Base URL INCLUDING the mount prefix + version the server adds at\n * bootstrap (default `/api/v1`) — `KickRoutes.Api` keys are module-mount\n * relative: `'GET /users/:id'` + baseUrl `https://x/api/v1`.\n */\n baseUrl: string\n /** Static headers, or a factory invoked per request (auth tokens). */\n headers?:\n | Record<string, string>\n | (() => Record<string, string> | Promise<Record<string, string>>)\n /**\n * Custom fetch — inject a platform fetch, a mock, or a KickJS web app's\n * own handler for network-free tests: `{ fetch: app.fetch }`.\n */\n fetch?: (request: Request) => Promise<Response>\n}\n\n/** Non-2xx responses throw this — carries the parsed body (RFC 9457 problem details when the server used `ctx.problem`). */\nexport class KickClientError extends Error {\n constructor(\n readonly status: number,\n readonly body: unknown,\n readonly response: Response,\n ) {\n super(\n typeof body === 'object' && body !== null && 'detail' in body\n ? String((body as { detail: unknown }).detail)\n : typeof body === 'object' && body !== null && 'error' in body\n ? String((body as { error: unknown }).error)\n : `Request failed with status ${status}`,\n )\n this.name = 'KickClientError'\n }\n}\n\nexport interface KickClient<Api extends ApiMap> {\n get<P extends PathsFor<Api, 'GET'> & string>(\n path: P,\n ...args: ArgsFor<ShapeOf<Api, 'GET', P>, 'GET'>\n ): Promise<ShapeOf<Api, 'GET', P>['response']>\n /**\n * Open a typed SSE connection to a route whose handler\n * `return ctx.sse<T>()` — events arrive as `SseEvent<T>`:\n *\n * ```ts\n * const stream = await api.stream('/events')\n * for await (const ev of stream) console.log(ev.data) // ev.data: T\n * ```\n */\n stream<P extends StreamPathsFor<Api> & string>(\n path: P,\n ...args: ArgsFor<ShapeOf<Api, 'GET', P>, 'GET'>\n ): Promise<SseStream<SsePayloadOf<ShapeOf<Api, 'GET', P>['response']>>>\n post<P extends PathsFor<Api, 'POST'> & string>(\n path: P,\n ...args: ArgsFor<ShapeOf<Api, 'POST', P>, 'POST'>\n ): Promise<ShapeOf<Api, 'POST', P>['response']>\n put<P extends PathsFor<Api, 'PUT'> & string>(\n path: P,\n ...args: ArgsFor<ShapeOf<Api, 'PUT', P>, 'PUT'>\n ): Promise<ShapeOf<Api, 'PUT', P>['response']>\n delete<P extends PathsFor<Api, 'DELETE'> & string>(\n path: P,\n ...args: ArgsFor<ShapeOf<Api, 'DELETE', P>, 'DELETE'>\n ): Promise<ShapeOf<Api, 'DELETE', P>['response']>\n patch<P extends PathsFor<Api, 'PATCH'> & string>(\n path: P,\n ...args: ArgsFor<ShapeOf<Api, 'PATCH', P>, 'PATCH'>\n ): Promise<ShapeOf<Api, 'PATCH', P>['response']>\n}\n\ninterface AnyRequestOptions {\n headers?: Record<string, string>\n signal?: AbortSignal\n query?: Record<string, unknown>\n params?: Record<string, string | number>\n body?: unknown\n}\n\n/** Substitute `:param` segments; throw on any left unfilled. */\nfunction fillPath(path: string, params?: Record<string, string | number>): string {\n const filled = path.replace(/:([A-Za-z0-9_]+)/g, (_, name: string) => {\n const value = params?.[name]\n if (value === undefined) {\n throw new Error(`@forinda/kickjs-client: missing path param ':${name}' for '${path}'`)\n }\n return encodeURIComponent(String(value))\n })\n return filled\n}\n\n/** Parse one SSE block (lines until a blank line) into an event. */\nfunction parseSseBlock(block: string): SseEvent | null {\n let event: string | undefined\n let id: string | undefined\n const dataLines: string[] = []\n for (const line of block.split('\\n')) {\n if (line.startsWith(':')) continue // comment / keep-alive\n if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart())\n else if (line.startsWith('event:')) event = line.slice(6).trim()\n else if (line.startsWith('id:')) id = line.slice(3).trim()\n }\n if (dataLines.length === 0) return null\n const raw = dataLines.join('\\n')\n let data: unknown = raw\n try {\n data = JSON.parse(raw)\n } catch {\n // Non-JSON payloads pass through as the raw string.\n }\n return { data, ...(event ? { event } : {}), ...(id ? { id } : {}) }\n}\n\nfunction buildQuery(query?: Record<string, unknown>): string {\n if (!query) return ''\n const qs = new URLSearchParams()\n for (const [key, value] of Object.entries(query)) {\n if (value === undefined || value === null) continue\n if (Array.isArray(value)) for (const v of value) qs.append(key, String(v))\n else qs.append(key, String(value))\n }\n const s = qs.toString()\n return s ? `?${s}` : ''\n}\n\n/**\n * Create a typed client over a `KickRoutes.Api`-shaped map.\n * Generic-only consumption — no runtime dependency on the generated file.\n */\nexport function createClient<Api extends ApiMap>(options: ClientOptions): KickClient<Api> {\n const baseUrl = options.baseUrl.replace(/\\/$/, '')\n const doFetch = options.fetch ?? ((req: Request) => fetch(req))\n\n async function buildRequest(\n method: ClientMethod,\n path: string,\n opts: AnyRequestOptions,\n ): Promise<Request> {\n const clientHeaders =\n typeof options.headers === 'function' ? await options.headers() : (options.headers ?? {})\n const headers = new Headers({ ...clientHeaders, ...opts.headers })\n // Defensive: fetch's Request constructor throws on GET-with-body; the\n // types already forbid it, but casts can smuggle one through.\n const hasBody = method !== 'GET' && opts.body !== undefined\n if (hasBody && !headers.has('content-type')) {\n headers.set('content-type', 'application/json')\n }\n\n const url = `${baseUrl}${fillPath(path, opts.params)}${buildQuery(opts.query)}`\n return new Request(url, {\n method,\n headers,\n body: hasBody ? JSON.stringify(opts.body) : undefined,\n signal: opts.signal,\n })\n }\n\n async function run(method: ClientMethod, path: string, opts: AnyRequestOptions = {}) {\n const request = await buildRequest(method, path, opts)\n\n const response = await doFetch(request)\n const contentType = response.headers.get('content-type') ?? ''\n const body =\n response.status === 204\n ? undefined\n : contentType.includes('json')\n ? await response.json().catch(() => undefined)\n : await response.text()\n\n if (!response.ok) throw new KickClientError(response.status, body, response)\n return body\n }\n\n async function openStream(path: string, opts: AnyRequestOptions = {}): Promise<SseStream> {\n // Own controller so close() works even without a caller-provided signal;\n // chain the caller's signal into it when present.\n const controller = new AbortController()\n opts.signal?.addEventListener('abort', () => controller.abort(), { once: true })\n const request = await buildRequest('GET', path, {\n ...opts,\n signal: controller.signal,\n headers: { accept: 'text/event-stream', ...opts.headers },\n })\n\n const response = await doFetch(request)\n if (!response.ok || !response.body) {\n const contentType = response.headers.get('content-type') ?? ''\n const body = contentType.includes('json')\n ? await response.json().catch(() => undefined)\n : await response.text().catch(() => undefined)\n throw new KickClientError(response.status, body, response)\n }\n\n const reader = response.body.getReader()\n const decoder = new TextDecoder()\n\n async function* events(): AsyncGenerator<SseEvent> {\n let buffer = ''\n try {\n for (;;) {\n const { done, value } = await reader.read()\n if (done) break\n buffer += decoder.decode(value, { stream: true })\n // Events are separated by a blank line; keep the trailing partial.\n const blocks = buffer.split(/\\n\\n/)\n buffer = blocks.pop() ?? ''\n for (const block of blocks) {\n const ev = parseSseBlock(block)\n if (ev) yield ev\n }\n }\n } finally {\n controller.abort()\n reader.releaseLock()\n }\n }\n\n return {\n [Symbol.asyncIterator]: events,\n close: () => controller.abort(),\n }\n }\n\n return {\n get: (path: string, opts?: unknown) => run('GET', path, opts as AnyRequestOptions),\n stream: (path: string, opts?: unknown) =>\n openStream(path, (opts ?? {}) as AnyRequestOptions) as never,\n post: (path: string, opts?: unknown) => run('POST', path, opts as AnyRequestOptions),\n put: (path: string, opts?: unknown) => run('PUT', path, opts as AnyRequestOptions),\n delete: (path: string, opts?: unknown) => run('DELETE', path, opts as AnyRequestOptions),\n patch: (path: string, opts?: unknown) => run('PATCH', path, opts as AnyRequestOptions),\n } as unknown as KickClient<Api>\n}\n\n/** Anything with a web-standard fetch — a `createWebApp()` result, a Worker, a mock. */\nexport interface FetchLike {\n fetch(request: Request): Promise<Response>\n}\n\n/**\n * Typed client over an in-process app — network-free full-stack tests:\n *\n * ```ts\n * const app = createWebApp({ h3, modules })\n * const api = createTestClient<KickRoutes.Api>(app)\n * expect(await api.get('/tasks/:id', { params: { id: '1' } })).toEqual(...)\n * ```\n *\n * `baseUrl` defaults to `http://test/api/v1` (the bootstrap default prefix);\n * override it when the server uses a custom `apiPrefix`/version.\n */\nexport function createTestClient<Api extends ApiMap>(\n app: FetchLike,\n options: Omit<ClientOptions, 'fetch' | 'baseUrl'> & { baseUrl?: string } = {},\n): KickClient<Api> {\n return createClient<Api>({\n ...options,\n // AFTER the spread — an explicit `baseUrl: undefined` key in options\n // must not clobber the default (spread copies undefined-valued keys).\n baseUrl: options.baseUrl ?? 'http://test/api/v1',\n fetch: (request) => app.fetch(request),\n })\n}\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@forinda/kickjs-client",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Typed fetch client for KickJS APIs — end-to-end response types from the kick typegen KickRoutes augmentation",
5
5
  "keywords": [
6
6
  "kickjs",
@@ -28,7 +28,7 @@
28
28
  "reflect-metadata": "^0.2.2",
29
29
  "typescript": "^6.0.3",
30
30
  "vitest": "^4.1.8",
31
- "@forinda/kickjs": "6.2.0"
31
+ "@forinda/kickjs": "6.3.0"
32
32
  },
33
33
  "publishConfig": {
34
34
  "access": "public"