@stacksjs/api 0.75.431 → 0.75.439

package/README.md

@@ -7,7 +7,7 @@ A simple, powerful HTTP client that wraps the fetch API with a more elegant inte
 - 🚀 Simple, elegant API
 - 💪 Full TypeScript support
 - 🔄 JSON handling by default
-- 📦 Zero dependencies (uses native fetch)
+- 📦 Native fetch transport with browser-compatible digest hashing
 - 🎯 Type-safe requests and responses
 
 ## 🤖 Usage
@@ -79,10 +79,115 @@ interface FetcherResponse<T> {
   data: T          // The response data (typed as T)
   status: number   // HTTP status code
   headers: Headers // Response headers
-  ok: boolean      // Whether the request was successful
+  isOk: boolean    // Whether the request was successful
+  ok(): boolean    // Whether the status is exactly 200
 }
 ```
 
+### Request configuration and responses
+
+Fluent settings apply to the next request only. Starting a request consumes its headers,
+credentials, query parameters, body and attachments synchronously. Overlapping calls keep
+independent settings, including when serialization, transport or response parsing fails.
+Header overrides are case-insensitive. Query values are appended to existing parameters
+before a fragment; null and undefined values are omitted.
+
+Response data is parsed as JSON for `application/json` and `+json` media types. Empty
+responses have `data: null`; other media types return text. Invalid declared JSON rejects.
+HTTP error statuses still return a response so callers can inspect its status and data.
+
+### Digest authentication
+
+```typescript
+const response = await fetcher
+  .withDigestAuth('user', 'password')
+  .withBody({ message: 'hello' })
+  .post('/protected')
+```
+
+The client supports MD5 and SHA-256, their session variants, `auth`, `auth-int`, and legacy
+challenges without qop. It chooses SHA-256 when offered, parses quoted challenge values,
+normalizes UTF-8 credentials to NFC, and replays the exact prepared body bytes, including
+multipart boundaries, once. Unsupported
+challenges return the original 401. Digest hashing loads `hash-wasm` on demand and needs
+WebAssembly in browsers. MD5 is supported for legacy digest servers only.
+
+Digest requests omit ambient cookies and browser HTTP-auth credentials to let the client
+handle the challenge without a native login dialog. Explicit headers still apply. Challenges
+received after a redirect are not authenticated; call the final protected URL directly.
+
+### Resource serialization
+
+`JsonResource` and `ResourceCollection` can be returned directly from a route. Serialization
+uses the public projection, including nested resources and collections, without exposing
+source records or the stored request. Nested projections receive the parent request.
+Conditional values are resolved at every level and missing entries are omitted from objects
+and arrays. Nested arrays retain their shape. Cycles and excessive nesting throw before any
+raw fallback can be serialized; the shared resolution budget is 20 object or wrapper levels.
+
+```typescript
+class UserResource extends JsonResource<User> {
+  toArray() {
+    return {
+      id: this.resource.id,
+      ...this.merge({ name: this.resource.name }),
+      ...this.mergeWhen(this.resource.isPublic, { email: this.resource.email }),
+    }
+  }
+}
+```
+
+Spread merges follow ordinary object spread ordering. Named merge placeholders and explicit
+`MergeValue` instances remain supported. Special field names such as `__proto__` are retained
+as data properties. Direct paginated collections retain projected rows, metadata and links.
+Pagination requires positive safe integer page numbers and sizes and a nonnegative safe
+integer total. Empty pages report null row bounds, and empty results have one page. Links
+replace an existing `page` parameter while retaining filters, duplicate parameters and fragments.
+
+### Generated API clients and types
+
+The OpenAPI generators emit standalone TypeScript clients with no runtime imports.
+Framework contributors regenerate the checked artifacts with `./buddy docs:artifacts`
+and verify them with `./buddy docs:artifacts:check`.
+
+Methods retain flat path/query arguments when names are unique. Duplicate names,
+or collisions with a body or typed-header container that exists, use location groups:
+
+```typescript
+await client.show({ path: { id: 'alice' }, query: { id: 7 } })
+await client.upload({ headers: { 'X-Tenant': 'tenant-a' }, body: file })
+```
+
+Required headers and bodies are typed and checked before transport. Request settings
+merge in this order: client headers, bearer token, per-call headers, typed header inputs.
+Header names are case-insensitive. Dot-only path segments are rejected before sending.
+Generated method names reserve client members and stay unique after normalization.
+Documentation is escaped before it is embedded in generated comments.
+
+Query serialization supports form arrays and objects, deepObject filters with scalar
+values, and space/pipe-delimited arrays. Path and header parameters support simple
+serialization. Unsupported locations or styles fail during generation. Cookie parameters
+are unsupported because browser fetch cannot set the Cookie header directly.
+
+Bodies support JSON (including `+json`), URL-encoded forms, multipart objects or FormData,
+and raw text/binary payloads. Select among declared formats with the second argument,
+`{ contentType: 'application/x-www-form-urlencoded' }`. Multipart boundaries are set by
+fetch. Custom per-part encodings and automatic XML serialization are not provided.
+Responses are decoded by media type; declared binary schemas return Blob values, text
+stays text, and empty/HEAD responses return null. All declared successful response
+schemas contribute to the result union. HTTP error statuses return `ok: false`.
+
+Schema generation supports local component references (including recursive models),
+nullable fields, literal JSON enums, unions and intersections. Unresolved, external and
+cyclic alias references fail during generation. Request schemas omit read-only fields;
+response schemas omit write-only fields. `components.requestSchemas` exposes request
+variants alongside response `components.schemas`.
+
+TypeScript index signatures apply to named fields too. For schemas combining named
+properties and typed additional properties, the generated index includes the named
+field types and optional undefined values to remain compilable. Runtime validation
+must enforce the narrower constraints on additional properties.
+
 ## 🧪 Testing
 
 ```bash

package/dist/client-runtime.d.ts

@@ -0,0 +1,2 @@
+/** Embedded verbatim into the dependency-free generated client; exercised by consumer compilation and HTTP tests. */
+export declare const clientRuntime: string;

package/dist/client-runtime.js

@@ -0,0 +1,154 @@
+export const clientRuntime=String.raw`
+export type ApiResult<T> =
+  | { ok: true, status: number, data: T, headers: Headers }
+  | { ok: false, status: number, error: unknown, headers: Headers }
+
+export interface ClientConfig {
+  baseUrl: string
+  token?: string
+  headers?: Record<string, string>
+  fetch?: typeof fetch
+}
+export interface RequestOptions {
+  signal?: AbortSignal
+  headers?: Record<string, string>
+  /** Select one of the operation's declared request media types. */
+  contentType?: string
+}
+interface Parameter {
+  name: string
+  in: string
+  required: boolean
+  group?: string
+  style?: string
+  explode?: boolean
+}
+interface BodyDescription { required: boolean, content: string[] }
+
+function parameterValue(input: Record<string, unknown>, parameter: Parameter): unknown {
+  const fields = parameter.group ? input[parameter.group] : input
+  if (parameter.in === 'header' && fields && typeof fields === 'object') {
+    const entries = Object.entries(fields).filter(([key]) => key.toLowerCase() === parameter.name.toLowerCase())
+    return entries.at(-1)?.[1]
+  }
+  return fields && typeof fields === 'object' && Object.hasOwn(fields, parameter.name)
+    ? (fields as Record<string, unknown>)[parameter.name] : undefined
+}
+function scalar(value: unknown): string {
+  if (typeof value === 'object' && value !== null) throw new TypeError('Nested parameter values require an explicit supported serialization')
+  return String(value)
+}
+function queryParameter(url: URL, parameter: Parameter, value: unknown): void {
+  const style = parameter.style ?? 'form'
+  const explode = parameter.explode ?? style === 'form'
+  if (style === 'deepObject') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('deepObject requires an object')
+    for (const [key, item] of Object.entries(value)) url.searchParams.append(parameter.name + '[' + key + ']', scalar(item))
+  }
+  else if (Array.isArray(value)) {
+    if (style === 'form' && explode) {
+      for (const item of value) url.searchParams.append(parameter.name, scalar(item))
+    }
+    else url.searchParams.append(parameter.name, value.map(scalar).join(style === 'spaceDelimited' ? ' ' : style === 'pipeDelimited' ? '|' : ','))
+  }
+  else if (value && typeof value === 'object') {
+    if (style !== 'form') throw new TypeError('Object queries require form or deepObject style')
+    if (explode) for (const [key, item] of Object.entries(value)) url.searchParams.append(key, scalar(item))
+    else url.searchParams.append(parameter.name, Object.entries(value).flatMap(([key, item]) => [key, scalar(item)]).join(','))
+  }
+  else url.searchParams.append(parameter.name, scalar(value))
+}
+function simpleParameter(value: unknown, explode: boolean, encode: (value: string) => string): string {
+  if (Array.isArray(value)) return value.map(item => encode(scalar(item))).join(',')
+  if (value && typeof value === 'object') return Object.entries(value).map(([key, item]) => encode(key) + (explode ? '=' : ',') + encode(scalar(item))).join(',')
+  return encode(scalar(value))
+}
+function buildUrl(config: ClientConfig, route: string, input: Record<string, unknown>, parameters: Parameter[], headers: Headers): string {
+  const path = new Map<string, string>()
+  for (const parameter of parameters) {
+    const value = parameterValue(input, parameter)
+    if (value === undefined || value === null) {
+      if (parameter.required) throw new TypeError('Missing required ' + parameter.in + ' parameter: ' + parameter.name)
+      continue
+    }
+    if (parameter.in === 'path') {
+      const segment = simpleParameter(value, parameter.explode ?? false, encodeURIComponent)
+      if (segment === '.' || segment === '..') throw new TypeError('Dot-only path parameters are not allowed')
+      path.set(parameter.name, segment)
+    }
+    else if (parameter.in === 'header') headers.set(parameter.name, simpleParameter(value, parameter.explode ?? false, value => value))
+  }
+  const filled = route.replace(/\{([^{}]+)\}/g, (_, key: string) => {
+    const value = path.get(key)
+    if (value === undefined) throw new TypeError('Missing path parameter: ' + key)
+    return value
+  })
+  const url = new URL(filled.replace(/^\/+/, '/'), config.baseUrl.endsWith('/') ? config.baseUrl : config.baseUrl + '/')
+  for (const parameter of parameters) {
+    const value = parameterValue(input, parameter)
+    if (parameter.in === 'query' && value !== undefined && value !== null) queryParameter(url, parameter, value)
+  }
+  return url.toString()
+}
+function isJson(type: string): boolean { return type === 'application/json' || type.endsWith('+json') }
+function mediaType(type: string): string { return type.split(';')[0]!.trim().toLowerCase() }
+function requestBody(value: unknown, description: BodyDescription | null, headers: Headers, options?: RequestOptions): BodyInit | undefined {
+  if (!description) return undefined
+  if (value === undefined) {
+    if (description.required) throw new TypeError('Missing required request body')
+    return undefined
+  }
+  const declared = description.content
+  const selected = options?.contentType ?? headers.get('content-type') ?? declared.find(isJson) ?? declared[0]
+  if (!selected || !declared.some(type => mediaType(type) === mediaType(selected))) throw new TypeError('Request media type is not declared by this operation')
+  const type = mediaType(selected)
+  headers.set('content-type', selected)
+  if (isJson(type)) return JSON.stringify(value)
+  if (type === 'application/x-www-form-urlencoded' || type === 'multipart/form-data') {
+    if (type === 'multipart/form-data' && value instanceof FormData) { headers.delete('content-type'); return value }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('Form bodies require an object')
+    if (type === 'application/x-www-form-urlencoded') {
+      const form = new URLSearchParams()
+      for (const [name, field] of Object.entries(value)) {
+        for (const item of Array.isArray(field) ? field : [field]) if (item != null) form.append(name, scalar(item))
+      }
+      return form.toString()
+    }
+    const form = new FormData()
+    for (const [name, field] of Object.entries(value)) {
+      for (const item of Array.isArray(field) ? field : [field]) {
+        if (item == null) continue
+        form.append(name, item instanceof Blob ? item : typeof item === 'object' ? JSON.stringify(item) : String(item))
+      }
+    }
+    headers.delete('content-type')
+    return form
+  }
+  if (value instanceof Blob || value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return value as BodyInit
+  if (typeof value === 'string') return value
+  throw new TypeError('Non-JSON request bodies require text or binary data')
+}
+async function request<T>(config: ClientConfig, method: string, route: string, input: Record<string, unknown>, parameters: Parameter[], description: BodyDescription | null, accept: string, binary: string[], options?: RequestOptions): Promise<ApiResult<T>> {
+  const headers = new Headers({ Accept: accept })
+  for (const [name, value] of Object.entries(config.headers ?? {})) headers.set(name, value)
+  if (config.token) headers.set('authorization', 'Bearer ' + config.token)
+  for (const [name, value] of Object.entries(options?.headers ?? {})) headers.set(name, value)
+  const url = buildUrl(config, route, input, parameters, headers)
+  const body = requestBody(input.body, description, headers, options)
+  const response = await (config.fetch ?? fetch)(url, { method, headers, body, signal: options?.signal })
+  const type = mediaType(response.headers.get('content-type') ?? '')
+  let parsed: unknown
+  if (method === 'HEAD' || response.status === 204 || response.status === 205) parsed = null
+  else if (binary.includes(type)) parsed = await response.blob()
+  else {
+    const text = await response.text()
+    // Keep malformed JSON available as evidence, without parsing other media as JSON.
+    if (!text.length) parsed = type.startsWith('text/') ? '' : null
+    else if (isJson(type)) { try { parsed = JSON.parse(text) } catch { parsed = text } }
+    else parsed = text
+  }
+  return response.ok
+    ? { ok: true, status: response.status, data: parsed as T, headers: response.headers }
+    : { ok: false, status: response.status, error: parsed, headers: response.headers }
+}
+`;

package/dist/digest.d.ts

@@ -0,0 +1,4 @@
+/** RFC 7616 authentication. MD5 is used only when a legacy server challenges with it. */
+export declare function digestAuthorization(header: string, credentials: DigestCredentials, method: string, url: string, body: Uint8Array): Promise<string | null>;
+export declare interface DigestCredentials { username: string, password: string }
+declare type Challenge = Record<string, string>;

package/dist/digest.js

@@ -0,0 +1 @@
+import{md5,sha256}from"hash-wasm";function digestChallenges(header){const parts=[];let quoted=!1,escaped=!1,start=0;for(let index=0;index<header.length;index++){const char=header[index];if(escaped){escaped=!1;continue}if(quoted&&char==="\\"){escaped=!0;continue}if(char==='"')quoted=!quoted;if(char===","&&!quoted){parts.push(header.slice(start,index));start=index+1}}if(quoted||escaped)return[];parts.push(header.slice(start));const challenges=[];let current;for(let part of parts){part=part.trim();const scheme=/^([a-z][a-z0-9_-]*)[ \t]+(?=[^ \t=])/i.exec(part);if(scheme){current=scheme[1].toLowerCase()==="digest"?Object.create(null):void 0;if(current)challenges.push(current);part=part.slice(scheme[0].length)}if(!current)continue;const parameter=/^([a-z][a-z0-9_-]*)\s*=\s*("(?:\\.|[^"\\])*"|[^\s]+)$/i.exec(part);if(!parameter){current=void 0;challenges.pop();continue}const key=parameter[1].toLowerCase();if(key in current){current=void 0;challenges.pop();continue}const raw=parameter[2];current[key]=raw.startsWith('"')?raw.slice(1,-1).replace(/\\(.)/g,"$1"):raw}return challenges}export async function digestAuthorization(header,credentials,method,url,body){const candidates=digestChallenges(header).filter((challenge)=>/^(?:MD5|SHA-256)(?:-sess)?$/i.test(challenge.algorithm??"MD5")).sort((a,b)=>Number(/^SHA-256/i.test(b.algorithm??""))-Number(/^SHA-256/i.test(a.algorithm??"")));for(const challenge of candidates){if(challenge.realm===void 0||!challenge.nonce)continue;if(challenge.charset&&challenge.charset.toUpperCase()!=="UTF-8")continue;const user=challenge.charset?credentials.username.normalize("NFC"):credentials.username,password=challenge.charset?credentials.password.normalize("NFC"):credentials.password,offered=challenge.qop?.split(",").map((value)=>value.trim().toLowerCase()),qop=offered?.includes("auth")?"auth":offered?.includes("auth-int")?"auth-int":void 0;if(offered&&!qop)continue;const algorithm=(challenge.algorithm??"MD5").toUpperCase(),session=algorithm.endsWith("-SESS"),base=algorithm.startsWith("SHA-256")?"SHA-256":"MD5",hash=base==="MD5"?md5:sha256,quote=(value)=>`"${value.replace(/[\\"]/g,"\\$&")}"`,cnonce=Array.from(crypto.getRandomValues(new Uint8Array(16)),(value)=>value.toString(16).padStart(2,"0")).join(""),nonceCount="00000001",target=new URL(url),uri=target.pathname+target.search;let ha1=await hash(`${user}:${challenge.realm}:${password}`);if(session)ha1=await hash(`${ha1}:${challenge.nonce}:${cnonce}`);const ha2=await hash(`${method}:${uri}${qop==="auth-int"?`:${await hash(body)}`:""}`),response=await hash(qop?`${ha1}:${challenge.nonce}:${nonceCount}:${cnonce}:${qop}:${ha2}`:`${ha1}:${challenge.nonce}:${ha2}`),username=challenge.userhash?.toLowerCase()==="true"?await hash(`${user}:${challenge.realm}`):user,encodedUsername=encodeURIComponent(username).replace(/['()*]/g,(char)=>`%${char.charCodeAt(0).toString(16).toUpperCase()}`),fields=[/[^\x20-\x7E]/.test(username)?`username*=UTF-8''${encodedUsername}`:`username=${quote(username)}`,`realm=${quote(challenge.realm)}`,`nonce=${quote(challenge.nonce)}`,`uri=${quote(uri)}`,`algorithm=${base}${session?"-sess":""}`,`response=${quote(response)}`];if(qop)fields.push(`qop=${qop}`,`nc=${nonceCount}`);if(qop||session)fields.push(`cnonce=${quote(cnonce)}`);if(challenge.opaque!==void 0)fields.push(`opaque=${quote(challenge.opaque)}`);if(challenge.userhash?.toLowerCase()==="true")fields.push("userhash=true");return`Digest ${fields.join(", ")}`}return null}

package/dist/fetcher.js

@@ -1 +1 @@
-class FetcherResponseImpl{data;status;headers;isOk;constructor(data,status,headers,isOk){this.data=data;this.status=status;this.headers=headers;this.isOk=isOk}ok(){return this.status===200}created(){return this.status===201}accepted(){return this.status===202}noContent(){return this.status===204}movedPermanently(){return this.status===301}found(){return this.status===302}badRequest(){return this.status===400}unauthorized(){return this.status===401}paymentRequired(){return this.status===402}forbidden(){return this.status===403}notFound(){return this.status===404}requestTimeout(){return this.status===408}conflict(){return this.status===409}unprocessableEntity(){return this.status===422}tooManyRequests(){return this.status===429}serverError(){return this.status===500}}class Fetcher{defaultHeaders={Accept:"application/json","Content-Type":"application/json"};queryParams;bodyData;isFormData=!1;customHeaders={};attachments=[];isMultipart=!1;digestAuth;withQueryParams(params){this.queryParams=params;return this}withHeaders(headers){this.customHeaders={...this.customHeaders,...headers};return this}accept(contentType){this.defaultHeaders.Accept=contentType;return this}acceptJson(){return this.accept("application/json")}withToken(token){this.customHeaders.Authorization=`Bearer ${token}`;return this}withBasicAuth(username,password){const credentials=btoa(`${username}:${password}`);this.customHeaders.Authorization=`Basic ${credentials}`;return this}withDigestAuth(username,password){this.digestAuth={username,password};return this}withBody(data){this.bodyData=data;return this}asForm(){this.isFormData=!0;this.defaultHeaders["Content-Type"]="application/x-www-form-urlencoded";return this}attach(name,content,filename,headers){const blobContent=typeof content==="string"?new Blob([content],{type:headers?.["Content-Type"]||"text/plain"}):content;this.attachments.push({name,content:blobContent,filename,headers});this.isMultipart=!0;delete this.defaultHeaders["Content-Type"];return this}getHeaders(){return{...this.defaultHeaders,...this.customHeaders}}addQueryParams(url){if(!this.queryParams)return url;const searchParams=new URLSearchParams;Object.entries(this.queryParams).forEach(([key,value])=>{if(value!=null)searchParams.append(key,String(value))});const queryString=searchParams.toString();if(!queryString)return url;const hasParams=url.includes("?");return url+(hasParams?"&":"?")+queryString}async formatBody(body){const finalBody=body||this.bodyData;if(this.isMultipart){const formData=new FormData;if(finalBody)Object.entries(finalBody).forEach(([key,value])=>{formData.append(key,String(value))});for(const attachment of this.attachments)if(attachment.headers){const blob=attachment.content instanceof Blob?new Blob([attachment.content],{type:attachment.headers["Content-Type"]}):attachment.content;formData.append(attachment.name,blob,attachment.filename)}else formData.append(attachment.name,attachment.content,attachment.filename);return formData}if(this.isFormData&&finalBody){const formData=new URLSearchParams;Object.entries(finalBody).forEach(([key,value])=>{if(value!=null)formData.append(key,String(value))});return formData.toString()}return finalBody?JSON.stringify(finalBody):void 0}resetState(){this.queryParams=void 0;this.bodyData=void 0;this.isFormData=!1;this.isMultipart=!1;this.customHeaders={};this.attachments=[];this.digestAuth=void 0;this.defaultHeaders["Content-Type"]="application/json"}async handleDigestAuth(response,url,method,body){if(response.status!==401||!this.digestAuth)return response;const authHeader=response.headers.get("WWW-Authenticate");if(!authHeader?.startsWith("Digest "))return response;const challenge=authHeader.substring(7).split(",").reduce((acc,part)=>{const[key,value]=part.trim().split("=");if(key)acc[key]=value?.replace(/["']/g,"")??"";return acc},{}),ha1=await this.generateMD5(`${this.digestAuth.username}:${challenge.realm}:${this.digestAuth.password}`),ha2=await this.generateMD5(`${method}:${url}`),nonceCount="00000001",cnonce=await this.generateMD5(Date.now().toString()).then((hash)=>hash.substring(0,8)),response_value=await this.generateMD5(`${ha1}:${challenge.nonce}:${nonceCount}:${cnonce}:${challenge.qop}:${ha2}`),digestResponse={username:`"${this.digestAuth.username}"`,realm:`"${challenge.realm}"`,nonce:`"${challenge.nonce}"`,uri:`"${url}"`,algorithm:challenge.algorithm?`"${challenge.algorithm}"`:void 0,qop:`"${challenge.qop}"`,nc:nonceCount,cnonce:`"${cnonce}"`,response:`"${response_value}"`,opaque:challenge.opaque?`"${challenge.opaque}"`:void 0},authValue=Object.entries(digestResponse).filter(([_,value])=>value!==void 0).map(([key,value])=>`${key}=${value}`).join(", ");this.customHeaders.Authorization=`Digest ${authValue}`;return fetch(url,{method,headers:this.getHeaders(),body:body?await this.formatBody(body):void 0})}async generateMD5(str){const data=new TextEncoder().encode(str),hashBuffer=await crypto.subtle.digest("SHA-256",data);return Array.from(new Uint8Array(hashBuffer)).map((b)=>b.toString(16).padStart(2,"0")).join("")}async request(url,method,body){const urlWithParams=this.addQueryParams(url),formattedBody=await this.formatBody(body);let response=await fetch(urlWithParams,{method,headers:this.getHeaders(),body:formattedBody});if(this.digestAuth)response=await this.handleDigestAuth(response,urlWithParams,method,body);const data=await response.json();this.resetState();return new FetcherResponseImpl(data,response.status,response.headers,response.ok)}async get(url){return this.request(url,"GET")}async post(url,body){return this.request(url,"POST",body)}async put(url,body){return this.request(url,"PUT",body)}async patch(url,body){return this.request(url,"PATCH",body)}async delete(url){return this.request(url,"DELETE")}}export const fetcher=new Fetcher;
+import{withQuery}from"./query";class FetcherResponseImpl{data;status;headers;isOk;constructor(data,status,headers,isOk){this.data=data;this.status=status;this.headers=headers;this.isOk=isOk}ok(){return this.status===200}created(){return this.status===201}accepted(){return this.status===202}noContent(){return this.status===204}movedPermanently(){return this.status===301}found(){return this.status===302}badRequest(){return this.status===400}unauthorized(){return this.status===401}paymentRequired(){return this.status===402}forbidden(){return this.status===403}notFound(){return this.status===404}requestTimeout(){return this.status===408}conflict(){return this.status===409}unprocessableEntity(){return this.status===422}tooManyRequests(){return this.status===429}serverError(){return this.status===500}}class Fetcher{defaultHeaders={Accept:"application/json","Content-Type":"application/json"};queryParams;bodyData;isFormData=!1;customHeaders={};attachments=[];isMultipart=!1;digestAuth;withQueryParams(params){this.queryParams=params;return this}withHeaders(headers){for(const[name,value]of Object.entries(headers))this.customHeaders[name.toLowerCase()]=value;return this}accept(contentType){this.defaultHeaders.Accept=contentType;return this}acceptJson(){return this.accept("application/json")}withToken(token){this.customHeaders.authorization=`Bearer ${token}`;return this}withBasicAuth(username,password){const credentials=btoa(`${username}:${password}`);this.customHeaders.authorization=`Basic ${credentials}`;return this}withDigestAuth(username,password){this.digestAuth={username,password};return this}withBody(data){this.bodyData=data;return this}asForm(){this.isFormData=!0;this.defaultHeaders["Content-Type"]="application/x-www-form-urlencoded";return this}attach(name,content,filename,headers){const blobContent=typeof content==="string"?new Blob([content],{type:headers?.["Content-Type"]||"text/plain"}):content;this.attachments.push({name,content:blobContent,filename,headers});this.isMultipart=!0;delete this.defaultHeaders["Content-Type"];return this}getHeaders(){const headers=new Headers(this.defaultHeaders);for(const[name,value]of Object.entries(this.customHeaders))headers.set(name,value);return headers}addQueryParams(url){if(!this.queryParams)return url;return withQuery(url,this.queryParams)}async formatBody(body){const finalBody=body||this.bodyData;if(this.isMultipart){const formData=new FormData;if(finalBody)Object.entries(finalBody).forEach(([key,value])=>{formData.append(key,String(value))});for(const attachment of this.attachments)if(attachment.headers){const blob=attachment.content instanceof Blob?new Blob([attachment.content],{type:attachment.headers["Content-Type"]}):attachment.content;formData.append(attachment.name,blob,attachment.filename)}else formData.append(attachment.name,attachment.content,attachment.filename);return formData}if(this.isFormData&&finalBody){const formData=new URLSearchParams;Object.entries(finalBody).forEach(([key,value])=>{if(value!=null)formData.append(key,String(value))});return formData.toString()}return finalBody?JSON.stringify(finalBody):void 0}resetState(){this.queryParams=void 0;this.bodyData=void 0;this.isFormData=!1;this.isMultipart=!1;this.customHeaders={};this.attachments=[];this.digestAuth=void 0;this.defaultHeaders={Accept:"application/json","Content-Type":"application/json"}}request(url,method,body){const owned=new Fetcher;Object.assign(owned,this,{defaultHeaders:{...this.defaultHeaders},customHeaders:{...this.customHeaders},attachments:[...this.attachments],digestAuth:this.digestAuth?{...this.digestAuth}:void 0});this.resetState();return owned.perform(url,method,body)}async perform(url,method,body){const urlWithParams=this.addQueryParams(url),formattedBody=await this.formatBody(body),headers=this.getHeaders();if(this.isMultipart)headers.delete("content-type");const prepared=new Request(urlWithParams,{method,headers,body:formattedBody});let response;if(this.digestAuth){const bytes=prepared.body?new Uint8Array(await prepared.arrayBuffer()):void 0,send=(requestHeaders)=>fetch(prepared.url,{method,headers:requestHeaders,body:bytes,credentials:"omit"});response=await send(prepared.headers);const target=new URL(prepared.url);target.hash="";const respondedAt=new URL(response.url);respondedAt.hash="";if(response.status===401&&respondedAt.href===target.href){const challenge=response.headers.get("www-authenticate");if(challenge){const{digestAuthorization}=await import("./digest"),authorization=await digestAuthorization(challenge,this.digestAuth,method,target.href,bytes??new Uint8Array);if(authorization){await response.body?.cancel();const authenticated=new Headers(prepared.headers);authenticated.set("authorization",authorization);response=await send(authenticated)}}}}else response=await fetch(prepared);const text=await response.text(),contentType=response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase()??"",json=contentType==="application/json"||contentType.endsWith("+json"),data=text===""?null:json?JSON.parse(text):text;this.resetState();return new FetcherResponseImpl(data,response.status,response.headers,response.ok)}async get(url){return this.request(url,"GET")}async post(url,body){return this.request(url,"POST",body)}async put(url,body){return this.request(url,"PUT",body)}async patch(url,body){return this.request(url,"PATCH",body)}async delete(url){return this.request(url,"DELETE")}}export const fetcher=new Fetcher;

package/dist/generate-client.d.ts

@@ -12,11 +12,4 @@ import type { OpenApiDocument } from './generate-types';
  * numbering the second one tells the reader nothing.
  */
 export declare function methodName(operationId: string): string;
-/**
- * Render the client for a document.
- *
- * Exported separately from the file writing so it can be tested on a document
- * built in memory, which is the only way to assert what it does with a shape
- * the current app happens not to have.
- */
 export declare function renderApiClient(document: OpenApiDocument, options?: { name?: string }): string;

package/dist/generate-client.js

@@ -1,108 +1,21 @@
-import{readFileSync,writeFileSync}from"node:fs";import{resolve}from"node:path";import{schemaType}from"./generate-types";const METHODS=["get","put","post","delete","options","head","patch"];export function methodName(operationId){const parts=operationId.replace(/[{}]/g,"").split(/[^a-z0-9]+/i).filter(Boolean),trimmed=parts[0]?.toLowerCase()==="api"?parts.slice(1):parts[1]?.toLowerCase()==="api"?[parts[0],...parts.slice(2)]:parts,[first,...rest]=trimmed;if(!first)return"call";const head=first.charAt(0).toLowerCase()+first.slice(1),tail=rest.map((part)=>part.charAt(0).toUpperCase()+part.slice(1)),name=[head,...tail].join("");return/^[a-z_$]/i.test(name)?name:`call${name.charAt(0).toUpperCase()}${name.slice(1)}`}function successType(operation){const responses=operation.responses??{},status=Object.keys(responses).find((code)=>code.startsWith("2"));if(!status)return"unknown";const content=responses[status]?.content,json=content?.["application/json"]??Object.values(content??{})[0];return json?.schema?schemaType(json.schema):"unknown"}function comment(lines,indent="  "){const kept=lines.filter(Boolean);if(!kept.length)return"";return`${indent}/**
+import{readFileSync,writeFileSync}from"node:fs";import{resolve}from"node:path";import{clientRuntime}from"./client-runtime";import{operationParameters,renderSchemaComponents,resolveOpenApiReference,schemaType}from"./generate-types";const METHODS=["get","put","post","delete","options","head","patch"];export function methodName(operationId){const parts=operationId.replace(/[{}]/g,"").split(/[^a-z0-9]+/i).filter(Boolean),trimmed=parts[0]?.toLowerCase()==="api"?parts.slice(1):parts[1]?.toLowerCase()==="api"?[parts[0],...parts.slice(2)]:parts,[first,...rest]=trimmed;if(!first)return"call";const head=first.charAt(0).toLowerCase()+first.slice(1),tail=rest.map((part)=>part.charAt(0).toUpperCase()+part.slice(1)),name=[head,...tail].join("");return/^[a-z_$]/i.test(name)?name:`call${name.charAt(0).toUpperCase()}${name.slice(1)}`}function successType(operation,document,method){if(method==="head")return"null";const types=[];for(const[status,entry]of Object.entries(operation.responses??{})){if(!/^2(?:\d\d|XX)$/i.test(status))continue;const response=resolveOpenApiReference(entry,document);if(status==="204"||status==="205"||!Object.keys(response.content??{}).length)types.push("null");else for(const media of Object.values(response.content??{}))types.push(schemaType(media.schema,{document,direction:"response"}))}return types.includes("unknown")?"unknown":[...new Set(types)].join(" | ")||"unknown"}function comment(lines,indent="  "){const kept=lines.filter(Boolean).flatMap((line)=>line.replace(/\*\//g,"*\\/").split(/\r?\n/));return kept.length?`${indent}/**
 ${kept.map((line)=>`${indent} * ${line}`).join(`
 `)}
 ${indent} */
-`}function renderOperation(route,method,operation,name){const parameters=operation.parameters??[],pathParams=parameters.filter((parameter)=>parameter.in==="path"),queryParams=parameters.filter((parameter)=>parameter.in==="query"),bodySchema=operation.requestBody?.content?.["application/json"]?.schema,bodyRequired=Boolean(operation.requestBody?.required),fields=[];for(const parameter of[...pathParams,...queryParams]){const required=parameter.in==="path"||parameter.required;fields.push(`${JSON.stringify(parameter.name)}${required?"":"?"}: ${schemaType(parameter.schema)}`)}if(bodySchema)fields.push(`body${bodyRequired?"":"?"}: ${schemaType(bodySchema)}`);const everyFieldOptional=[...pathParams,...queryParams].every((p)=>p.in!=="path"&&!p.required)&&(!bodySchema||!bodyRequired),argument=fields.length?`input${everyFieldOptional?"?":""}: { ${fields.join("; ")} }, `:"",queryList=queryParams.length?`[${queryParams.map((parameter)=>JSON.stringify(parameter.name)).join(", ")}]`:"[]";return`${comment([operation.summary&&operation.summary!==route?operation.summary:`${method.toUpperCase()} ${route}`,operation.description??""])}  ${name}(${argument}options?: RequestOptions): Promise<ApiResult<${successType(operation)}>> {
-    return request(config, ${JSON.stringify(method.toUpperCase())}, ${JSON.stringify(route)}, ${fields.length?"input ?? {}":"{}"}, ${queryList}, ${bodySchema?"true":"false"}, options)
-  },`}export function renderApiClient(document,options={}){const title=options.name??"API",used=new Map,methods=[];for(const[route,item]of Object.entries(document.paths??{}))for(const method of METHODS){const operation=item[method];if(!operation)continue;const preferred=methodName(operation.operationId??`${method}_${route}`),seen=used.get(preferred)??0;used.set(preferred,seen+1);methods.push(renderOperation(route,method,operation,seen===0?preferred:`${preferred}${seen+1}`))}return`/* eslint-disable */
-/**
- * ${title} client, generated from the OpenAPI document.
- *
- * Do not edit. Run \`buddy generate:openapi\` to rebuild it from the routes.
- *
- * No imports and no dependencies: copy this file anywhere that has \`fetch\`.
- */
-
-/** Every call answers with one of these. Nothing here throws for a 4xx. */
-export type ApiResult<T> =
-  | { ok: true, status: number, data: T, headers: Headers }
-  | { ok: false, status: number, error: unknown, headers: Headers }
-
-export interface ClientConfig {
-  /** Where the API lives, e.g. \`https://example.com\`. No trailing slash needed. */
-  baseUrl: string
-  /** Sent as \`Authorization: Bearer \u2026\` when present. */
-  token?: string
-  /** Extra headers on every request. */
-  headers?: Record<string, string>
-  /** Swap in a different fetch - a test double, or one that retries. */
-  fetch?: typeof fetch
-}
-
-export interface RequestOptions {
-  /** Abort in flight. */
-  signal?: AbortSignal
-  /** Headers for this call only, merged over the client's. */
-  headers?: Record<string, string>
-}
-
-function buildUrl(config: ClientConfig, route: string, input: Record<string, unknown>, query: string[]): string {
-  // Path parameters are substituted, never appended: a \`{id}\` left in the URL
-  // is a 404 whose message is about the literal string "{id}".
-  const filled = route.replace(/\\{(\\w+)\\}/g, (_, key: string) => encodeURIComponent(String(input[key] ?? '')))
-  const url = new URL(filled.replace(/^\\/+/, '/'), config.baseUrl.endsWith('/') ? config.baseUrl : \`\${config.baseUrl}/\`)
-
-  for (const key of query) {
-    const value = input[key]
-    // Absent means absent. Sending \`?path=\` asks for the file called empty
-    // string, which is a different question from not filtering.
-    if (value === undefined || value === null) continue
-    url.searchParams.set(key, String(value))
-  }
-
-  return url.toString()
-}
-
-async function request<T>(
-  config: ClientConfig,
-  method: string,
-  route: string,
-  input: Record<string, unknown>,
-  query: string[],
-  hasBody: boolean,
-  options?: RequestOptions,
-): Promise<ApiResult<T>> {
-  const call = config.fetch ?? fetch
-  const url = buildUrl(config, route, input, query)
-
-  const headers: Record<string, string> = {
-    Accept: 'application/json',
-    ...(config.headers ?? {}),
-    ...(options?.headers ?? {}),
-  }
-  if (config.token) headers.Authorization = \`Bearer \${config.token}\`
-
-  const body = hasBody && input.body !== undefined ? JSON.stringify(input.body) : undefined
-  if (body !== undefined) headers['Content-Type'] = 'application/json'
-
-  const response = await call(url, { method, headers, body, signal: options?.signal })
-
-  const text = await response.text()
-  let parsed: unknown = text
-  if (text.length) {
-    // A non-JSON body is kept verbatim rather than replaced with a parse error.
-    // An endpoint that answered with HTML is worth seeing.
-    try { parsed = JSON.parse(text) } catch { parsed = text }
-  }
-  else {
-    parsed = null
-  }
-
-  return response.ok
-    ? { ok: true, status: response.status, data: parsed as T, headers: response.headers }
-    : { ok: false, status: response.status, error: parsed, headers: response.headers }
-}
+`:""}function renderOperation(route,method,operation,item,name,document){const parameters=operationParameters(item,operation,document),body=operation.requestBody&&resolveOpenApiReference(operation.requestBody,document),pathAndQuery=parameters.filter((parameter)=>parameter.in==="path"||parameter.in==="query"),names=pathAndQuery.map((parameter)=>parameter.name),grouped=new Set(names).size!==names.length||Boolean(body)&&names.includes("body")||parameters.some((parameter)=>parameter.in==="header")&&names.includes("headers"),descriptors=parameters.map((parameter)=>{const styles=parameter.in==="query"?["form","deepObject","spaceDelimited","pipeDelimited"]:["simple"];if(!["path","query","header"].includes(parameter.in)||parameter.style&&!styles.includes(parameter.style))throw TypeError(`Unsupported parameter serialization: ${parameter.in} ${parameter.style??""}`);return{name:parameter.name,in:parameter.in,required:parameter.in==="path"||Boolean(parameter.required),...parameter.in==="header"?{group:"headers"}:grouped?{group:parameter.in}:{},...parameter.style?{style:parameter.style}:{},...parameter.explode!==void 0?{explode:parameter.explode}:{}}}),fields=[],required=(parameter)=>parameter.in==="path"||parameter.required,field=(parameter)=>`${JSON.stringify(parameter.name)}${required(parameter)?"":"?"}: ${schemaType(parameter.schema,{document,direction:"request"})}`;if(!grouped)fields.push(...pathAndQuery.map(field));for(const location of[...grouped?["path","query"]:[],"header"]){const entries=parameters.filter((parameter)=>parameter.in===location);if(entries.length)fields.push(`${location==="header"?"headers":location}${entries.some(required)?"":"?"}: { ${entries.map(field).join("; ")} }`)}const content=Object.keys(body?.content??{});if(body&&!content.length)throw TypeError("Request body must declare a media type");if(body){const bodyTypes=Object.entries(body.content??{}).map(([type,media])=>{const shape=schemaType(media.schema,{document,direction:"request"});return type==="multipart/form-data"?`${shape} | FormData`:shape});fields.push(`body${body.required?"":"?"}: ${[...new Set(bodyTypes)].join(" | ")}`)}const everyFieldOptional=!parameters.some(required)&&!body?.required,argument=fields.length?`input${everyFieldOptional?"?":""}: { ${fields.join("; ")} }, `:"",documentation=comment([operation.summary&&operation.summary!==route?operation.summary:`${method.toUpperCase()} ${route}`,operation.description??""]),accept=[...new Set(Object.values(operation.responses??{}).flatMap((entry)=>Object.keys(resolveOpenApiReference(entry,document).content??{})))].join(", ")||"application/json",binary=[...new Set(Object.values(operation.responses??{}).flatMap((entry)=>Object.entries(resolveOpenApiReference(entry,document).content??{}).filter(([,media])=>{const schema=resolveOpenApiReference(media.schema??{},document);return schema.type==="string"&&schema.format==="binary"}).map(([type])=>type.split(";")[0].trim().toLowerCase())))];return`${documentation}  ${name}(${argument}options?: RequestOptions): Promise<ApiResult<${successType(operation,document,method)}>> {
+    return request(config, ${JSON.stringify(method.toUpperCase())}, ${JSON.stringify(route)}, ${fields.length?"input ?? {}":"{}"}, ${JSON.stringify(descriptors)}, ${body?JSON.stringify({required:Boolean(body.required),content}):"null"}, ${JSON.stringify(accept)}, ${JSON.stringify(binary)}, options)
+  },`}export function renderApiClient(document,options={}){const operations=Object.entries(document.paths??{}).flatMap(([route,item])=>METHODS.flatMap((method)=>{const operation=item[method];return operation?[{route,item,method,operation,preferred:methodName(operation.operationId??`${method}_${route}`)}]:[]})),reserved=new Set(["config","then","constructor","prototype","__proto__"]),preferred=new Set(operations.map((operation)=>operation.preferred)),used=new Set(reserved),methods=operations.map((entry)=>{let name=entry.preferred,suffix=2;if(used.has(name))do name=`${entry.preferred}${suffix++}`;while(used.has(name)||preferred.has(name));used.add(name);return renderOperation(entry.route,entry.method,entry.operation,entry.item,name,document)});return`/* eslint-disable */
+${comment([`${options.name??"API"} client, generated from OpenAPI.`,"Do not edit; run buddy generate:openapi.","No imports or dependencies."],"")}
+${clientRuntime}
+${renderSchemaComponents(document)}
 
 export function createClient(config: ClientConfig) {
   return {
-    /** The configuration in use, so a caller can rebuild a variant of it. */
     config,
-
 ${methods.join(`
 
 `)}
   }
 }
-
 export type Client = ReturnType<typeof createClient>
 `}if(import.meta.main){const apiRoot=resolve(import.meta.dir,"../../../api"),input=resolve(process.argv[2]||resolve(apiRoot,"openapi.json")),output=resolve(process.argv[3]||resolve(apiRoot,"client.ts")),document=JSON.parse(readFileSync(input,"utf8"));writeFileSync(output,renderApiClient(document));console.log(`Generated ${output}`)}

package/dist/generate-types.d.ts

@@ -1,27 +1,70 @@
-export declare function schemaType(schema?: SchemaObject): string;
+/** Local JSON references only. Missing, external and cyclic aliases fail during generation. */
+export declare function resolveOpenApiReference<T extends object>(value: T | OpenApiReference, document: OpenApiDocument): T;
+/** Parameters are unique by location and name; operation declarations override inherited ones. */
+export declare function operationParameters(item: OpenApiPathItem, operation: OpenApiOperation, document: OpenApiDocument): OpenApiParameter[];
+/** Render schemas for their use in a request or response, preserving recursive component references. */
+export declare function schemaType(schema?: SchemaObject, options?: SchemaTypeOptions): string;
+export declare function renderSchemaComponents(document: OpenApiDocument): string;
 export declare function renderOpenApiTypes(document: OpenApiDocument): string;
 export declare interface SchemaObject {
   [key: string]: unknown
+  $ref?: string
   type?: string
+  nullable?: boolean
+  readOnly?: boolean
+  writeOnly?: boolean
   enum?: unknown[]
   properties?: Record<string, SchemaObject>
   required?: string[]
   items?: SchemaObject
   additionalProperties?: boolean | SchemaObject
+  oneOf?: SchemaObject[]
+  anyOf?: SchemaObject[]
+  allOf?: SchemaObject[]
 }
-declare interface OpenApiParameter {
+export declare interface OpenApiReference { $ref: string }
+export declare interface OpenApiParameter {
   name: string
   in: string
   required?: boolean
   schema?: SchemaObject
+  description?: string
+  style?: string
+  explode?: boolean
 }
-declare interface OpenApiOperation {
+export declare interface OpenApiMedia { schema?: SchemaObject }
+export declare interface OpenApiRequestBody { required?: boolean, content?: Record<string, OpenApiMedia> }
+export declare interface OpenApiResponse { description?: string, content?: Record<string, OpenApiMedia> }
+export declare interface OpenApiOperation {
   operationId?: string
-  parameters?: OpenApiParameter[]
-  requestBody?: { required?: boolean, content?: Record<string, { schema?: SchemaObject }> }
-  responses?: Record<string, { content?: Record<string, { schema?: SchemaObject }> }>
+  summary?: string
+  description?: string
+  parameters?: Array<OpenApiParameter | OpenApiReference>
+  requestBody?: OpenApiRequestBody | OpenApiReference
+  responses?: Record<string, OpenApiResponse | OpenApiReference>
+}
+export declare interface OpenApiPathItem {
+  [key: string]: unknown
+  parameters?: Array<OpenApiParameter | OpenApiReference>
+  get?: OpenApiOperation
+  put?: OpenApiOperation
+  post?: OpenApiOperation
+  delete?: OpenApiOperation
+  options?: OpenApiOperation
+  head?: OpenApiOperation
+  patch?: OpenApiOperation
+  trace?: OpenApiOperation
 }
 export declare interface OpenApiDocument {
-  paths?: Record<string, Record<string, OpenApiOperation>>
-  components?: { schemas?: Record<string, SchemaObject> }
+  paths?: Record<string, OpenApiPathItem>
+  components?: {
+    schemas?: Record<string, SchemaObject>
+    parameters?: Record<string, OpenApiParameter | OpenApiReference>
+    requestBodies?: Record<string, OpenApiRequestBody | OpenApiReference>
+    responses?: Record<string, OpenApiResponse | OpenApiReference>
+  }
+}
+export declare interface SchemaTypeOptions {
+  document?: OpenApiDocument
+  direction?: 'request' | 'response'
 }

package/dist/generate-types.js

@@ -1,31 +1,31 @@
-import{readFileSync,writeFileSync}from"node:fs";import{resolve}from"node:path";const methods=["get","put","post","delete","options","head","patch","trace"];function literal(value){return typeof value==="string"?JSON.stringify(value):String(value)}export function schemaType(schema){if(!schema)return"unknown";if(schema.enum?.length)return schema.enum.map(literal).join(" | ");if(schema.type==="string")return"string";if(schema.type==="number"||schema.type==="integer")return"number";if(schema.type==="boolean")return"boolean";if(schema.type==="null")return"null";if(schema.type==="array")return`Array<${schemaType(schema.items)}>`;if(schema.type==="object"||schema.properties||schema.additionalProperties){const required=new Set(schema.required||[]),fields=Object.entries(schema.properties||{}).map(([name,value])=>`${JSON.stringify(name)}${required.has(name)?"":"?"}: ${schemaType(value)}`);if(schema.additionalProperties){const value=schema.additionalProperties===!0?"unknown":schemaType(schema.additionalProperties);fields.push(`[key: string]: ${value}`)}return fields.length?`{ ${fields.join("; ")} }`:"Record<string, unknown>"}return"unknown"}function parameterGroups(parameters=[]){return`    parameters: {
-${["query","header","path","cookie"].map((location)=>{const entries=parameters.filter((parameter)=>parameter.in===location);if(!entries.length)return`      ${location}?: never`;const fields=entries.map((parameter)=>`${JSON.stringify(parameter.name)}${parameter.required?"":"?"}: ${schemaType(parameter.schema)}`);return`      ${location}${entries.every((parameter)=>!parameter.required)?"?":""}: { ${fields.join("; ")} }`}).join(`
+import{readFileSync,writeFileSync}from"node:fs";import{resolve}from"node:path";const methods=["get","put","post","delete","options","head","patch","trace"];export function resolveOpenApiReference(value,document){const visited=new Set;let current=value;while(current&&typeof current==="object"&&"$ref"in current){const ref=current.$ref;if(!ref.startsWith("#/")||visited.has(ref))throw TypeError(`Unsupported or cyclic OpenAPI reference: ${ref}`);visited.add(ref);let target=document;for(const key of decodeURIComponent(ref.slice(2)).split("/").map((part)=>part.replace(/~1/g,"/").replace(/~0/g,"~"))){if(!target||typeof target!=="object"||!Object.hasOwn(target,key))throw TypeError(`Missing OpenAPI reference: ${ref}`);target=target[key]}current=target}if(!current||typeof current!=="object"||Array.isArray(current))throw TypeError("OpenAPI reference must resolve to an object");return current}export function operationParameters(item,operation,document){const parameters=new Map;for(const entry of[...item.parameters??[],...operation.parameters??[]]){const parameter=resolveOpenApiReference(entry,document),name=parameter.in==="header"?parameter.name.toLowerCase():parameter.name;parameters.set(`${parameter.in}:${name}`,parameter)}return[...parameters.values()]}function literal(value,ancestors=new Set){if(value===null)return"null";if(typeof value==="string")return JSON.stringify(value);if(typeof value==="number"&&Number.isFinite(value))return String(value);if(typeof value==="boolean")return String(value);if(!value||typeof value!=="object"||ancestors.has(value))throw TypeError("OpenAPI enums must contain finite JSON values");ancestors.add(value);try{if(Array.isArray(value))return`[${value.map((item)=>literal(item,ancestors)).join(", ")}]`;return`{ ${Object.entries(value).map(([key,item])=>`${JSON.stringify(key)}: ${literal(item,ancestors)}`).join("; ")} }`}finally{ancestors.delete(value)}}function union(types){return types.includes("unknown")?"unknown":[...new Set(types)].join(" | ")||"never"}export function schemaType(schema,options={}){return renderSchema(schema,options,new Set)}function renderSchema(schema,options,ancestors){if(!schema)return"unknown";if(ancestors.has(schema))throw TypeError("Recursive schemas must use component references");ancestors.add(schema);const render=(value)=>renderSchema(value,options,ancestors);try{if(schema.$ref){if(!options.document||!schema.$ref.startsWith("#/components/schemas/"))throw TypeError(`Unsupported schema reference: ${schema.$ref}`);resolveOpenApiReference(schema,options.document);const pointer=decodeURIComponent(schema.$ref.slice(21));if(pointer.includes("/"))return render(resolveOpenApiReference(schema,options.document));const name=pointer.replace(/~1/g,"/").replace(/~0/g,"~");return`components[${JSON.stringify(options.direction==="request"?"requestSchemas":"schemas")}][${JSON.stringify(name)}]`}if(schema.enum?.length)return union(schema.enum.map((value)=>literal(value)));let base;if(schema.type==="string")base=schema.format==="binary"?"Blob":"string";else if(schema.type==="number"||schema.type==="integer")base="number";else if(schema.type==="boolean")base="boolean";else if(schema.type==="null")base="null";else if(schema.type==="array")base=`Array<${render(schema.items)}>`;else if(schema.type==="object"||schema.properties||schema.additionalProperties!==void 0){const required=new Set(schema.required??[]),propertyTypes=Object.entries(schema.properties??{}).filter(([,value])=>{const resolved=value.$ref&&options.document?resolveOpenApiReference(value,options.document):value;return!(options.direction==="request"&&resolved.readOnly)&&!(options.direction==="response"&&resolved.writeOnly)}).map(([name,value])=>({name,type:render(value),optional:!required.has(name)})),fields=propertyTypes.map(({name,type,optional})=>`${JSON.stringify(name)}${optional?"?":""}: ${type}`);if(schema.additionalProperties){const extra=schema.additionalProperties===!0?"unknown":render(schema.additionalProperties),index=union([extra,...propertyTypes.map((field)=>field.type),...propertyTypes.some((field)=>field.optional)?["undefined"]:[]]);fields.push(`[key: string]: ${index}`)}base=fields.length?`{ ${fields.join("; ")} }`:schema.additionalProperties===!1?"Record<string, never>":"Record<string, unknown>"}const composed=[];if(base)composed.push(base);for(const variants of[schema.oneOf,schema.anyOf])if(variants?.length)composed.push(union(variants.map(render)));if(schema.allOf?.length)composed.push(...schema.allOf.map(render));const result=composed.length>1?composed.map((type)=>`(${type})`).join(" & "):composed[0]??"unknown";return schema.nullable&&schema.type?union([result,"null"]):result}finally{ancestors.delete(schema)}}export function renderSchemaComponents(document){const map=(direction)=>Object.entries(document.components?.schemas??{}).map(([name,schema])=>`    ${JSON.stringify(name)}: ${schemaType(schema,{document,direction})}`).join(`
+`);return`export interface components {
+  schemas: {
+${map("response")}
+  }
+  requestSchemas: {
+${map("request")}
+  }
+}`}function parameterGroups(parameters,document){return`    parameters: {
+${["query","header","path","cookie"].map((location)=>{const entries=parameters.filter((parameter)=>parameter.in===location);if(!entries.length)return`      ${location}?: never`;const required=(parameter)=>parameter.in==="path"||parameter.required,fields=entries.map((parameter)=>`${JSON.stringify(parameter.name)}${required(parameter)?"":"?"}: ${schemaType(parameter.schema,{document,direction:"request"})}`);return`      ${location}${entries.every((parameter)=>!required(parameter))?"?":""}: { ${fields.join("; ")} }`}).join(`
 `)}
-    }`}function contentTypes(content){if(!content||!Object.keys(content).length)return"never";return`{ ${Object.entries(content).map(([type,value])=>`${JSON.stringify(type)}: ${schemaType(value.schema)}`).join("; ")} }`}function renderOperation(operation){const requestBody=operation.requestBody?`
-    requestBody${operation.requestBody.required?"":"?"}: { content: ${contentTypes(operation.requestBody.content)} }`:`
-    requestBody?: never`,responses=Object.entries(operation.responses||{}).map(([status,response])=>`      ${JSON.stringify(status)}: { content: ${contentTypes(response.content)} }`);return`{
-${parameterGroups(operation.parameters)}${requestBody}
+    }`}function contentTypes(content,document,direction){if(!content||!Object.keys(content).length)return"never";return`{ ${Object.entries(content).map(([type,value])=>`${JSON.stringify(type)}: ${schemaType(value.schema,{document,direction})}`).join("; ")} }`}function renderOperation(item,operation,document){const body=operation.requestBody&&resolveOpenApiReference(operation.requestBody,document),requestBody=body?`
+    requestBody${body.required?"":"?"}: { content: ${contentTypes(body.content,document,"request")} }`:`
+    requestBody?: never`,responses=Object.entries(operation.responses??{}).map(([status,entry])=>{const response=resolveOpenApiReference(entry,document);return`      ${JSON.stringify(status)}: { content: ${contentTypes(response.content,document,"response")} }`});return`{
+${parameterGroups(operationParameters(item,operation,document),document)}${requestBody}
     responses: {
 ${responses.join(`
 `)}
     }
-  }`}export function renderOpenApiTypes(document){const paths=Object.entries(document.paths||{}).map(([route,item])=>{const operations=methods.map((method)=>{const operation=item[method];return operation?`    ${method}: ${renderOperation(operation)}`:`    ${method}?: never`});return`  ${JSON.stringify(route)}: {
-${operations.join(`
-`)}
-  }`}),schemas=Object.entries(document.components?.schemas||{}).map(([name,schema])=>`    ${JSON.stringify(name)}: ${schemaType(schema)}`);return`/**
- * Generated from storage/framework/api/openapi.json by @stacksjs/api.
- * Do not edit this file directly; run bun run docs:artifacts to regenerate it.
- */
+  }`}export function renderOpenApiTypes(document){return`/** Generated from OpenAPI. Do not edit; run buddy generate:openapi. */
 
 export interface paths {
-${paths.join(`
+${Object.entries(document.paths??{}).map(([route,item])=>{const operations=methods.map((method)=>{const operation=item[method];return operation?`    ${method}: ${renderOperation(item,operation,document)}`:`    ${method}?: never`});return`  ${JSON.stringify(route)}: {
+${operations.join(`
 `)}
-}
-
-export interface components {
-  schemas: {
-${schemas.join(`
+  }`}).join(`
 `)}
-  }
 }
+
+${renderSchemaComponents(document)}
 `}if(import.meta.main){const apiRoot=resolve(import.meta.dir,"../../../api"),input=resolve(process.argv[2]||resolve(apiRoot,"openapi.json")),output=resolve(process.argv[3]||resolve(apiRoot,"api-types.ts")),document=JSON.parse(readFileSync(input,"utf8"));writeFileSync(output,renderOpenApiTypes(document));console.log(`Generated ${output}`)}

package/dist/query.d.ts

@@ -0,0 +1,2 @@
+/** Add query values without moving them into a URL fragment. Relative paths stay relative. */
+export declare function withQuery(url: string, values: Record<string, unknown>, replace?: boolean): string;

package/dist/query.js

@@ -0,0 +1 @@
+export function withQuery(url,values,replace=!1){const hashIndex=url.indexOf("#"),fragment=hashIndex<0?"":url.slice(hashIndex),head=hashIndex<0?url:url.slice(0,hashIndex),queryIndex=head.indexOf("?"),path=queryIndex<0?head:head.slice(0,queryIndex),params=new URLSearchParams(queryIndex<0?"":head.slice(queryIndex+1));for(const[name,value]of Object.entries(values))if(value!=null)if(replace)params.set(name,String(value));else params.append(name,String(value));const query=params.toString();return path+(query?`?${query}`:"")+fragment}

package/dist/resource.d.ts

@@ -32,29 +32,7 @@ export declare interface PaginatedData<T> {
   meta: PaginationMeta
   links: PaginationLinks
 }
-/**
- * API Resources
- *
- * Laravel-like API resources for transforming models and collections
- * into JSON responses with fine-grained control.
- *
- * @example
- * class UserResource extends JsonResource<User> {
- *   toArray() {
- *     return {
- *       id: this.resource.id,
- *       name: this.resource.name,
- *       email: this.resource.email,
- *       posts: PostResource.collection(this.whenLoaded('posts')),
- *       created_at: this.resource.created_at,
- *     }
- *   }
- * }
- *
- * // Usage
- * return new UserResource(user).toResponse()
- * return UserResource.collection(users).toResponse()
- */
+declare interface ResolutionContext { depth: number, ancestors: WeakSet<object> }
 declare type Request = Record<string, unknown>;
 /**
  * Wrapper value types for conditional inclusion
@@ -91,6 +69,7 @@ export declare abstract class JsonResource<T = unknown> {
   withRequest(request: Request): this;
   withAdditional(data: Record<string, any>): this;
   resolve(request?: Request): Record<string, any>;
+  resolveAt(request: Request | undefined, context: ResolutionContext): Record<string, any>;
   toResponse(request?: Request): Record<string, any>;
   toJson(request?: Request): string;
   toJSON(): Record<string, unknown>;
@@ -99,8 +78,8 @@ export declare abstract class JsonResource<T = unknown> {
   protected whenNotNull<V>(value: V | null | undefined, transform?: (v: V) => any): any | MissingValue;
   protected whenLoaded<V>(relationship: string, value?: V | (() => V), defaultValue?: any): V | any[] | MissingValue;
   protected whenCounted(relationship: string, defaultValue?: number): number | MissingValue;
-  protected merge(data: Record<string, any>): MergeValue;
-  protected mergeWhen(condition: boolean | (() => boolean), data: Record<string, any> | (() => Record<string, any>)): MergeValue | MissingValue;
+  protected merge(data: Record<string, any>): Record<string, any>;
+  protected mergeWhen(condition: boolean | (() => boolean), data: Record<string, any> | (() => Record<string, any>)): Record<string, any> | MissingValue;
   static withoutWrapping(): void;
   static wrapWith(key: string): void;
 }
@@ -119,8 +98,10 @@ export declare class ResourceCollection<T = unknown, R extends JsonResource<T> =
   withRequest(request: Request): this;
   withAdditional(data: Record<string, any>): this;
   resolve(request?: Request): Record<string, any>[];
+  resolveAt(request: Request | undefined, context: ResolutionContext): Record<string, any>[];
   toResponse(request?: Request): Record<string, any>;
   toJson(request?: Request): string;
+  toJSON(): Record<string, unknown>;
   count(): number;
   isEmpty(): boolean;
   isNotEmpty(): boolean;

package/dist/resource.js

@@ -1 +1 @@
-export class MissingValue{static instance=new MissingValue;isMissing(){return!0}}export class MergeValue{data;constructor(data){this.data=data}}export class ConditionalValue{condition;value;defaultValue;constructor(condition,value,defaultValue=new MissingValue){this.condition=condition;this.value=value;this.defaultValue=defaultValue}resolve(){return(typeof this.condition==="function"?this.condition():this.condition)?this.value:this.defaultValue}}export class JsonResource{resource;additional={};request;static wrap="data";static additionalMeta={};constructor(resource){this.resource=resource}withRequest(request){this.request=request;return this}withAdditional(data){this.additional={...this.additional,...data};return this}resolve(request){const data=this.toArray(request||this.request);return this.filterAndResolve(data)}toResponse(request){const data=this.resolve(request),wrap=this.constructor.wrap;if(wrap)return{[wrap]:data,...this.additional};return{...data,...this.additional}}toJson(request){return JSON.stringify(this.toResponse(request))}toJSON(){return this.toResponse()}static collection(resources){return new ResourceCollection(resources,this)}when(condition,value,defaultValue){if(typeof condition==="function"?condition():condition)return typeof value==="function"?value():value;return defaultValue!==void 0?defaultValue:MissingValue.instance}whenNotNull(value,transform){if(value===null||value===void 0)return MissingValue.instance;return transform?transform(value):value}whenLoaded(relationship,value,defaultValue){const resource=this.resource;if(!((relationship in resource)&&resource[relationship]!==void 0))return defaultValue!==void 0?defaultValue:MissingValue.instance;if(value!==void 0)return typeof value==="function"?value():value;return resource[relationship]}whenCounted(relationship,defaultValue){const resource=this.resource,countKey=`${relationship}_count`;if(countKey in resource)return Number(resource[countKey]);return defaultValue!==void 0?defaultValue:MissingValue.instance}merge(data){return new MergeValue(data)}mergeWhen(condition,data){if(!(typeof condition==="function"?condition():condition))return MissingValue.instance;const resolvedData=typeof data==="function"?data():data;return new MergeValue(resolvedData)}static MAX_RESOLVE_DEPTH=20;filterAndResolve(data,depth=0){if(depth>=JsonResource.MAX_RESOLVE_DEPTH)return data;const result={};for(const[key,value]of Object.entries(data)){if(value instanceof MissingValue)continue;if(value instanceof MergeValue){Object.assign(result,this.filterAndResolve(value.data,depth+1));continue}if(value instanceof ConditionalValue){const resolved=value.resolve();if(!(resolved instanceof MissingValue))result[key]=resolved;continue}if(value!==null&&typeof value==="object"&&!Array.isArray(value)&&!(value instanceof Date)){result[key]=this.filterAndResolve(value,depth+1);continue}if(Array.isArray(value)){result[key]=value.filter((item)=>!(item instanceof MissingValue)).map((item)=>{if(item instanceof MergeValue)return item.data;if(item!==null&&typeof item==="object"&&!(item instanceof Date))return this.filterAndResolve(item,depth+1);return item});continue}result[key]=value}return result}static withoutWrapping(){this.wrap=null}static wrapWith(key){this.wrap=key}}export class ResourceCollection{resources;ResourceClass;additional={};request;static wrap="data";constructor(resources,ResourceClass){this.resources=resources;this.ResourceClass=ResourceClass}withRequest(request){this.request=request;return this}withAdditional(data){this.additional={...this.additional,...data};return this}resolve(request){const req=request||this.request;return this.resources.map((resource)=>{const instance=new this.ResourceClass(resource);if(req)instance.withRequest(req);return instance.resolve(req)})}toResponse(request){const data=this.resolve(request),wrap=this.constructor.wrap;if(wrap)return{[wrap]:data,...this.additional};return{data,...this.additional}}toJson(request){return JSON.stringify(this.toResponse(request))}count(){return this.resources.length}isEmpty(){return this.resources.length===0}isNotEmpty(){return this.resources.length>0}}export class PaginatedResourceCollection extends ResourceCollection{meta;links;constructor(paginatedData,ResourceClass){super(paginatedData.data,ResourceClass);this.meta=paginatedData.meta;this.links=paginatedData.links}static fromPagination(data,ResourceClass,options){const{currentPage,perPage,total,baseUrl=""}=options,lastPage=Math.ceil(total/perPage),from=total>0?(currentPage-1)*perPage+1:null,to=total>0?Math.min(currentPage*perPage,total):null;return new PaginatedResourceCollection({data,meta:{current_page:currentPage,from,last_page:lastPage,per_page:perPage,to,total},links:{first:`${baseUrl}?page=1`,last:`${baseUrl}?page=${lastPage}`,prev:currentPage>1?`${baseUrl}?page=${currentPage-1}`:null,next:currentPage<lastPage?`${baseUrl}?page=${currentPage+1}`:null}},ResourceClass)}toResponse(request){return{data:this.resolve(request),meta:this.meta,links:this.links,...this.additional}}}export function resource(data,transform){const transformed=transform(data);return{toResponse:()=>({data:transformed}),toJson:()=>JSON.stringify({data:transformed})}}export function collection(data,transform){const transformed=data.map(transform);return{toResponse:()=>({data:transformed}),toJson:()=>JSON.stringify({data:transformed})}}
+import{toPaginator}from"@stacksjs/pagination";import{withQuery}from"./query";export class MissingValue{static instance=new MissingValue;isMissing(){return!0}}export class MergeValue{data;constructor(data){this.data=data}}export class ConditionalValue{condition;value;defaultValue;constructor(condition,value,defaultValue=new MissingValue){this.condition=condition;this.value=value;this.defaultValue=defaultValue}resolve(){return(typeof this.condition==="function"?this.condition():this.condition)?this.value:this.defaultValue}}const mergePayloads=new WeakMap,MAX_RESOLVE_DEPTH=20;function resolveValue(value,request,context){if(value instanceof MissingValue||value===null||typeof value!=="object"||value instanceof Date)return value;if(context.depth>=MAX_RESOLVE_DEPTH)throw RangeError("Resource serialization exceeded the maximum depth");if(context.ancestors.has(value))throw TypeError("Resource serialization contains a cycle");context.ancestors.add(value);const next={depth:context.depth+1,ancestors:context.ancestors};try{if(value instanceof ConditionalValue)return resolveValue(value.resolve(),request,next);if(value instanceof MergeValue)return resolveValue(value.data,request,next);const merge=mergePayloads.get(value);if(merge)return resolveValue(merge,request,next);if(value instanceof JsonResource||value instanceof ResourceCollection)return value.resolveAt(request,next);if(Array.isArray(value)){const result=[];for(const item of value){const resolved=resolveValue(item,request,next);if(!(resolved instanceof MissingValue))result.push(resolved)}return result}if("toJSON"in value&&typeof value.toJSON==="function")return resolveValue(value.toJSON(),request,next);const entries=[];for(const[key,item]of Object.entries(value)){const resolved=resolveValue(item,request,next);if(resolved instanceof MissingValue)continue;if(item instanceof MergeValue||item!==null&&typeof item==="object"&&mergePayloads.has(item))entries.push(...Object.entries(resolved));else entries.push([key,resolved])}return Object.fromEntries(entries)}finally{context.ancestors.delete(value)}}export class JsonResource{resource;additional={};request;static wrap="data";static additionalMeta={};constructor(resource){this.resource=resource}withRequest(request){this.request=request;return this}withAdditional(data){this.additional={...this.additional,...data};return this}resolve(request){return resolveValue(this,request,{depth:0,ancestors:new WeakSet})}resolveAt(request,context){const req=request??this.request;return resolveValue(this.toArray(req),req,context)}toResponse(request){const data=this.resolve(request),wrap=this.constructor.wrap;if(wrap)return{[wrap]:data,...this.additional};return{...data,...this.additional}}toJson(request){return JSON.stringify(this.toResponse(request))}toJSON(){return this.toResponse()}static collection(resources){return new ResourceCollection(resources,this)}when(condition,value,defaultValue){if(typeof condition==="function"?condition():condition)return typeof value==="function"?value():value;return defaultValue!==void 0?defaultValue:MissingValue.instance}whenNotNull(value,transform){if(value===null||value===void 0)return MissingValue.instance;return transform?transform(value):value}whenLoaded(relationship,value,defaultValue){const resource=this.resource;if(!((relationship in resource)&&resource[relationship]!==void 0))return defaultValue!==void 0?defaultValue:MissingValue.instance;if(value!==void 0)return typeof value==="function"?value():value;return resource[relationship]}whenCounted(relationship,defaultValue){const resource=this.resource,countKey=`${relationship}_count`;if(countKey in resource)return Number(resource[countKey]);return defaultValue!==void 0?defaultValue:MissingValue.instance}merge(data){const spreadable={...data};mergePayloads.set(spreadable,data);return spreadable}mergeWhen(condition,data){if(!(typeof condition==="function"?condition():condition))return MissingValue.instance;const resolvedData=typeof data==="function"?data():data;return this.merge(resolvedData)}static withoutWrapping(){this.wrap=null}static wrapWith(key){this.wrap=key}}export class ResourceCollection{resources;ResourceClass;additional={};request;static wrap="data";constructor(resources,ResourceClass){this.resources=resources;this.ResourceClass=ResourceClass}withRequest(request){this.request=request;return this}withAdditional(data){this.additional={...this.additional,...data};return this}resolve(request){return resolveValue(this,request,{depth:0,ancestors:new WeakSet})}resolveAt(request,context){const req=request??this.request,resources=this.resources.map((resource)=>{const instance=new this.ResourceClass(resource);if(req)instance.withRequest(req);return instance});return resolveValue(resources,req,context)}toResponse(request){const data=this.resolve(request),wrap=this.constructor.wrap;if(wrap)return{[wrap]:data,...this.additional};return{data,...this.additional}}toJson(request){return JSON.stringify(this.toResponse(request))}toJSON(){return this.toResponse()}count(){return this.resources.length}isEmpty(){return this.resources.length===0}isNotEmpty(){return this.resources.length>0}}export class PaginatedResourceCollection extends ResourceCollection{meta;links;constructor(paginatedData,ResourceClass){super(paginatedData.data,ResourceClass);this.meta=paginatedData.meta;this.links=paginatedData.links}static fromPagination(data,ResourceClass,options){const{currentPage,perPage,total,baseUrl=""}=options;for(const[name,value]of Object.entries({currentPage,perPage,total}))if(!Number.isSafeInteger(value)||value<(name==="total"?0:1))throw RangeError(`${name} must be a safe integer ${name==="total"?"at least zero":"greater than zero"}`);const offset=(currentPage-1)*perPage;if(!Number.isSafeInteger(offset)||!Number.isSafeInteger(offset+data.length)||data.length>perPage||data.length>0&&offset+data.length>total)throw RangeError("Pagination rows do not fit the requested page and total");const page=toPaginator({data,meta:{page:currentPage,perPage,total,lastPage:Math.ceil(total/perPage)}}),link=(number)=>withQuery(baseUrl,{page:number},!0);return new PaginatedResourceCollection({data,meta:{current_page:currentPage,from:page.from,last_page:page.last_page,per_page:perPage,to:page.to,total},links:{first:link(1),last:link(page.last_page),prev:currentPage>1?link(currentPage-1):null,next:page.has_more_pages?link(currentPage+1):null}},ResourceClass)}toResponse(request){return{data:this.resolve(request),meta:this.meta,links:this.links,...this.additional}}}export function resource(data,transform){const transformed=transform(data);return{toResponse:()=>({data:transformed}),toJson:()=>JSON.stringify({data:transformed})}}export function collection(data,transform){const transformed=data.map(transform);return{toResponse:()=>({data:transformed}),toJson:()=>JSON.stringify({data:transformed})}}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/api",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.431",
+  "version": "0.75.439",
   "description": "The Stacks API utilities.",
   "author": "Chris Breuer",
   "contributors": [
@@ -61,15 +61,17 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.75.431",
-    "@stacksjs/path": "0.75.431"
+    "@stacksjs/config": "0.75.439",
+    "@stacksjs/path": "0.75.439",
+    "@stacksjs/pagination": "0.75.439",
+    "hash-wasm": "^4.12.0"
   },
   "devDependencies": {
-    "@stacksjs/utils": "0.75.431",
+    "@stacksjs/utils": "0.75.439",
     "better-dx": "^0.2.24"
   },
   "peerDependencies": {
-    "@stacksjs/router": "0.75.431"
+    "@stacksjs/router": "0.75.439"
   },
   "peerDependenciesMeta": {
     "@stacksjs/router": {