@tuyau/core 1.0.0 → 1.2.0

package/build/index-SVztBh2W.d.ts

@@ -0,0 +1,438 @@
+import { Options, KyResponse, KyRequest, HTTPError } from 'ky';
+import { ClientRouteMatchItTokens } from '@adonisjs/http-server/client/url_builder';
+
+/**
+ * Supported HTTP methods for API endpoints
+ */
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Options for the `current` method to match params and/or query
+ */
+interface CurrentRouteOptions {
+    params?: Record<string, any>;
+    query?: Record<string, any>;
+}
+/**
+ * Base endpoint types structure
+ */
+interface EndpointTypes {
+    paramsTuple: [...any[]];
+    params: Record<string, string | number | boolean | bigint | (string | number | boolean | bigint)[]>;
+    query: Record<string, any>;
+    body: unknown;
+    response: unknown;
+    errorResponse?: unknown;
+}
+/**
+ * Schema endpoint, used in generated registry.schema.d.ts
+ * Does not include tokens (only present in runtime routes)
+ */
+interface SchemaEndpoint {
+    methods: Method[];
+    pattern: string;
+    types: EndpointTypes;
+}
+/**
+ * Definition of an AdonisJS endpoint with types and metadata
+ * Includes tokens for runtime route building
+ */
+interface AdonisEndpoint extends SchemaEndpoint {
+    tokens: ClientRouteMatchItTokens[];
+}
+/**
+ * Extract query params from a validator type if it has a 'query' property.
+ * Used in generated registry to separate query params from body for POST/PUT/PATCH/DELETE.
+ * For GET/HEAD, use ExtractQueryForGet instead.
+ */
+type ExtractQuery<T> = 'query' extends keyof T ? T extends {
+    query?: infer Q;
+} ? Q : {} : {};
+/**
+ * Extract query params for GET/HEAD requests.
+ * Excludes headers, cookies, and params from the validator type since these are not query params.
+ */
+type ExtractQueryForGet<T> = Omit<T, 'headers' | 'cookies' | 'params'>;
+/**
+ * Extract body from a validator type, excluding reserved properties.
+ * Excludes 'query', 'params', 'headers', and 'cookies' as these are handled separately by AdonisJS.
+ */
+type ExtractBody<T> = Omit<T, 'query' | 'params' | 'headers' | 'cookies'>;
+/**
+ * Success status codes (2xx)
+ */
+type SuccessStatus = 200 | 201 | 202 | 203 | 204 | 205 | 206;
+/**
+ * Extract the actual response type from a controller return type.
+ * - Success responses (2xx): extracts `__response`
+ * - Error responses (non-2xx with __response/__status): returns `never` to filter from unions
+ * - Plain types (no __status): returns as-is
+ */
+type ExtractResponse<T> = T extends {
+    __response: infer R;
+    __status: SuccessStatus;
+} ? R : T extends {
+    __response: unknown;
+    __status: number;
+} ? never : T;
+/**
+ * Inverse of ExtractResponse — extracts non-2xx status types as a discriminated union.
+ * Each member has `{ status: S; response: R }` for narrowing via `isStatus()`.
+ */
+type ExtractErrorResponse<T> = T extends {
+    __response: infer R;
+    __status: infer S;
+} ? S extends SuccessStatus ? never : {
+    status: S;
+    response: R;
+} : never;
+/**
+ * Registry mapping endpoint names to their definitions
+ */
+interface AdonisRegistry extends Record<string, AdonisEndpoint> {
+}
+type ValueOf<T> = T[keyof T];
+/**
+ * Convert a union type to an intersection type
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Structure of a Tuyau registry containing routes and optional tree
+ */
+interface TuyauRegistry<Routes extends Record<string, AdonisEndpoint> = Record<string, AdonisEndpoint>, Tree = unknown> {
+    routes: Routes;
+    $tree?: Tree;
+}
+/**
+ * Extracts the $tree type from a registry
+ * Uses direct access instead of conditional type for performance
+ */
+type InferTree<R extends TuyauRegistry> = R['$tree'];
+/**
+ * Extracts the routes from a registry
+ */
+type InferRoutes<R extends TuyauRegistry> = R['routes'];
+type Endpoints = ValueOf<AdonisRegistry>;
+type EndpointByName<Name extends keyof AdonisRegistry & string> = AdonisRegistry[Name];
+/**
+ * Supported response types for overriding Content-Type based parsing
+ */
+type ResponseType = 'json' | 'text' | 'arrayBuffer' | 'blob';
+/**
+ * Tuyau-specific request options (not part of Ky)
+ */
+type TuyauRequestOptions = {
+    responseType?: ResponseType;
+};
+/**
+ * Pre-computed base Ky options to avoid recomputing Omit on every request
+ */
+type BaseRequestOptions = Omit<Options, 'body' | 'params' | 'searchParams' | 'method' | 'json' | 'prefixUrl'>;
+/**
+ * Helper types for optional/required fields - using literal types instead of mapped types
+ */
+type ParamsArg<T> = keyof T extends never ? {} : {} extends T ? {
+    params?: T;
+} : {
+    params: T;
+};
+type QueryArg<T> = keyof T extends never ? {} : {} extends T ? {
+    query?: T;
+} : {
+    query: T;
+};
+type BodyArg<T> = keyof T extends never ? {} : {} extends T ? {
+    body?: T;
+} : {
+    body: T;
+};
+/**
+ * Request args without ky options
+ */
+type RawRequestArgs<E extends SchemaEndpoint> = ParamsArg<E['types']['params']> & QueryArg<E['types']['query']> & BodyArg<E['types']['body']>;
+/**
+ * Constructs the request arguments type for an endpoint
+ */
+type RequestArgs<E extends SchemaEndpoint> = RawRequestArgs<E> & BaseRequestOptions & TuyauRequestOptions;
+/**
+ * Extracts response type from an endpoint
+ */
+type ResponseOf<E extends SchemaEndpoint> = E['types']['response'];
+/**
+ * Extracts error response type from an endpoint
+ */
+type ErrorResponseOf<E extends SchemaEndpoint> = E['types'] extends {
+    errorResponse: infer ER;
+} ? ER : unknown;
+/**
+ * Normalizes the error type to satisfy TuyauError's constraint.
+ * Routes without typed errors pass `unknown`, which maps to `{ response: any }`.
+ * Always includes a `{ status: number; response: unknown }` fallback so that
+ * catch-all blocks after exhaustive `isStatus()` checks never resolve to `never`.
+ */
+type NormalizeError$1<E> = (E extends {
+    response: any;
+} ? E : {
+    response: any;
+}) | {
+    status: number;
+    response: unknown;
+};
+/**
+ * Function type for calling an endpoint
+ */
+type EndpointFn<E extends SchemaEndpoint> = (args: RequestArgs<E>) => TuyauPromise<E['types']['response'], ErrorResponseOf<E>>;
+/**
+ * Function type for an endpoint with inlined args
+ */
+type EndpointFnInline<E extends AdonisEndpoint> = (args: ParamsArg<E['types']['params']> & QueryArg<E['types']['query']> & BodyArg<E['types']['body']> & BaseRequestOptions & TuyauRequestOptions) => TuyauPromise<E['types']['response'], ErrorResponseOf<E>>;
+/**
+ * Transforms a pre-computed ApiDefinition tree into callable endpoint functions
+ * This recursively converts each endpoint in the tree to a callable function
+ * Handles intersection types where a node is both an endpoint AND has children
+ */
+type TransformApiDefinition<T> = {
+    [K in keyof T]: T[K] extends AdonisEndpoint ? EndpointFnInline<T[K]> & TransformApiDefinition<Omit<T[K], keyof AdonisEndpoint>> : TransformApiDefinition<T[K]>;
+};
+/**
+ * Filters endpoints by HTTP method
+ */
+type EndpointsByMethod<Reg extends Record<string, AdonisEndpoint>, M extends Method> = {
+    [K in keyof Reg]: M extends Reg[K]['methods'][number] ? Reg[K] : never;
+}[keyof Reg];
+type StrKeys<R> = Extract<keyof R, string>;
+type RegValues<R> = R[StrKeys<R>];
+/**
+ * Gets URL patterns for endpoints matching a specific HTTP method
+ */
+type PatternsByMethod<Reg extends Record<string, AdonisEndpoint>, M extends Method> = EndpointsByMethod<Reg, M>['pattern'];
+/**
+ * Finds an endpoint by HTTP method and URL pattern
+ */
+type EndpointByMethodPattern<R extends Record<string, AdonisEndpoint>, M extends Method, P extends PatternsByMethod<R, M>> = FilterByMethodPathForRegistry<R, M, P>;
+/**
+ * Plugin function type for extending Tuyau functionality
+ */
+interface TuyauPlugin {
+    (params: {
+        options: TuyauConfiguration<any>;
+    }): void;
+}
+type MaybeArray<T> = T | T[];
+/**
+ * Type for URL query parameters
+ */
+type QueryParameterPrimitive = string | number | boolean | Date | null | undefined;
+interface QueryParameters extends Record<string, QueryParameterPrimitive | Array<QueryParameterPrimitive | QueryParameters> | QueryParameters> {
+}
+/**
+ * Configuration options for creating a Tuyau client
+ */
+interface TuyauConfiguration<T extends TuyauRegistry> extends Omit<Options, 'prefixUrl' | 'body' | 'json' | 'method' | 'searchParams'> {
+    registry: T;
+    baseUrl: string;
+    plugins?: TuyauPlugin[];
+}
+/**
+ * Should be augmented by the user to provide their endpoint registry
+ * Structure: { routes: Record<string, AdonisEndpoint>, $tree: ApiDefinition }
+ */
+interface UserRegistry {
+}
+type UserAdonisRegistry = UserRegistry extends {
+    routes: infer R;
+} ? R extends Record<string, AdonisEndpoint> ? R : Record<string, AdonisEndpoint> : Record<string, AdonisEndpoint>;
+type UserEndpointByName<Name extends keyof UserAdonisRegistry> = UserAdonisRegistry[Name];
+type FilterByMethodPathForRegistry<Reg extends Record<string, AdonisEndpoint>, M extends Method, P extends ValueOf<Reg>['pattern'] & string> = {
+    [K in keyof Reg]: Reg[K]['pattern'] extends P ? M extends Reg[K]['methods'][number] ? Reg[K] : never : never;
+}[keyof Reg];
+type EndpointByNameForRegistry<Reg extends Record<string, AdonisEndpoint>, Name extends keyof Reg> = Reg[Name];
+/**
+ * Internal type utilities for working with endpoints by HTTP method and path pattern
+ * Accepts a registry as generic parameter
+ */
+declare namespace PathWithRegistry {
+    type Request<Reg extends Record<string, AdonisEndpoint>, M extends Method, P extends PatternsByMethod<Reg, M>> = RequestArgs<FilterByMethodPathForRegistry<Reg, M, P>>;
+    type Response<Reg extends Record<string, AdonisEndpoint>, M extends Method, P extends PatternsByMethod<Reg, M>> = ResponseOf<FilterByMethodPathForRegistry<Reg, M, P>>;
+    type Params<Reg extends Record<string, AdonisEndpoint>, M extends Method, P extends PatternsByMethod<Reg, M>> = FilterByMethodPathForRegistry<Reg, M, P>['types']['params'];
+    type Body<Reg extends Record<string, AdonisEndpoint>, M extends Method, P extends PatternsByMethod<Reg, M>> = FilterByMethodPathForRegistry<Reg, M, P>['types']['body'];
+    type Query<Reg extends Record<string, AdonisEndpoint>, M extends Method, P extends PatternsByMethod<Reg, M>> = FilterByMethodPathForRegistry<Reg, M, P>['types']['query'];
+    type Error<Reg extends Record<string, AdonisEndpoint>, M extends Method, P extends PatternsByMethod<Reg, M>> = TuyauError<NormalizeError$1<ErrorResponseOf<FilterByMethodPathForRegistry<Reg, M, P>>>>;
+}
+/**
+ * Internal type utilities for working with endpoints by route name
+ * Accepts a registry as generic parameter
+ */
+declare namespace RouteWithRegistry {
+    type Request<Reg extends Record<string, AdonisEndpoint>, Name extends keyof Reg> = RequestArgs<EndpointByNameForRegistry<Reg, Name>>;
+    type Response<Reg extends Record<string, AdonisEndpoint>, Name extends keyof Reg> = ResponseOf<EndpointByNameForRegistry<Reg, Name>>;
+    type Params<Reg extends Record<string, AdonisEndpoint>, Name extends keyof Reg> = EndpointByNameForRegistry<Reg, Name>['types']['params'];
+    type Body<Reg extends Record<string, AdonisEndpoint>, Name extends keyof Reg> = EndpointByNameForRegistry<Reg, Name>['types']['body'];
+    type Query<Reg extends Record<string, AdonisEndpoint>, Name extends keyof Reg> = EndpointByNameForRegistry<Reg, Name>['types']['query'];
+    type Error<Reg extends Record<string, AdonisEndpoint>, Name extends keyof Reg> = TuyauError<NormalizeError$1<ErrorResponseOf<EndpointByNameForRegistry<Reg, Name>>>>;
+}
+/**
+ * Type utilities for working with endpoints by HTTP method and path pattern
+ * Uses the user-augmented registry
+ */
+declare namespace Path {
+    type Request<M extends Method, P extends PatternsByMethod<UserAdonisRegistry, M>> = RequestArgs<FilterByMethodPathForRegistry<UserAdonisRegistry, M, P>>;
+    type Response<M extends Method, P extends PatternsByMethod<UserAdonisRegistry, M>> = ResponseOf<FilterByMethodPathForRegistry<UserAdonisRegistry, M, P>>;
+    type Params<M extends Method, P extends PatternsByMethod<UserAdonisRegistry, M>> = FilterByMethodPathForRegistry<UserAdonisRegistry, M, P>['types']['params'];
+    type Body<M extends Method, P extends PatternsByMethod<UserAdonisRegistry, M>> = FilterByMethodPathForRegistry<UserAdonisRegistry, M, P>['types']['body'];
+    type Query<M extends Method, P extends PatternsByMethod<UserAdonisRegistry, M>> = FilterByMethodPathForRegistry<UserAdonisRegistry, M, P>['types']['query'];
+    type Error<M extends Method, P extends PatternsByMethod<UserAdonisRegistry, M>> = TuyauError<NormalizeError$1<ErrorResponseOf<FilterByMethodPathForRegistry<UserAdonisRegistry, M, P>>>>;
+}
+/**
+ * Type utilities for working with endpoints by route name
+ * Uses the user-augmented registry
+ */
+declare namespace Route {
+    type Request<Name extends keyof UserAdonisRegistry> = RequestArgs<UserEndpointByName<Name>>;
+    type Response<Name extends keyof UserAdonisRegistry> = ResponseOf<UserEndpointByName<Name>>;
+    type Params<Name extends keyof UserAdonisRegistry> = UserEndpointByName<Name>['types']['params'];
+    type Body<Name extends keyof UserAdonisRegistry> = UserEndpointByName<Name>['types']['body'];
+    type Query<Name extends keyof UserAdonisRegistry> = UserEndpointByName<Name>['types']['query'];
+    type Error<Name extends keyof UserAdonisRegistry> = TuyauError<NormalizeError$1<ErrorResponseOf<UserEndpointByName<Name>>>>;
+}
+/**
+ * Extracts literal status codes from E, filtering out the wide `number` from the fallback.
+ * `number extends 404` is false → keep. `number extends number` is true → skip.
+ */
+type KnownStatuses<E> = E extends {
+    status: infer S extends number;
+} ? number extends S ? never : S : never;
+type ParamsShape<E> = E extends {
+    types: {
+        paramsTuple: infer PT;
+        params: infer P;
+    };
+} ? (PT extends [] ? {
+    paramsTuple?: PT;
+} : {
+    paramsTuple: PT;
+}) & (keyof P extends never ? {} : {
+    params: P;
+}) : never;
+type RegistryGroupedByMethod<R extends Record<string, AdonisEndpoint>, M extends Method = Method> = {
+    [K in M | 'ALL']: {
+        [Route in keyof R as K extends 'ALL' ? Route : K extends R[Route]['methods'][number] ? Route : never]: ParamsShape<R[Route]>;
+    };
+};
+
+/**
+ * Base class for all errors exposed by Tuyau.
+ *
+ * `isStatus()` can be used to narrow HTTP errors to a specific typed response payload.
+ */
+declare class TuyauError<E extends {
+    response: any;
+} = {
+    response: any;
+}> extends Error {
+    /**
+     * Error kind exposed by Tuyau.
+     * - `'http'`: the server responded with a non-2xx status code.
+     * - `'network'`: the request failed before receiving a response.
+     */
+    kind: 'http' | 'network';
+    /**
+     * HTTP status code returned by the server.
+     * `undefined` when the request failed before a response was received.
+     */
+    status: number | undefined;
+    /**
+     * Original Ky response object for HTTP errors.
+     * `undefined` for network errors.
+     */
+    rawResponse: KyResponse | undefined;
+    /**
+     * Original Ky request object when available.
+     */
+    rawRequest: KyRequest | undefined;
+    /**
+     * Parsed error payload returned by the server.
+     * `undefined` for network errors.
+     */
+    response: E['response'] | undefined;
+    constructor(message: string, options?: ErrorOptions);
+    /**
+     * Type guard that narrows the error to a specific HTTP status code.
+     * After calling `isStatus(422)`, the `response` property is narrowed
+     * to the type associated with that status code.
+     */
+    isStatus<S extends KnownStatuses<E> | (number & {})>(status: S): this is TuyauHTTPError<Extract<E, {
+        status: S;
+    }>>;
+    /**
+     * Type guard that narrows to a 422 validation error.
+     * Alias for `isStatus(422)`.
+     */
+    isValidationError(): this is TuyauHTTPError<Extract<E, {
+        status: 422;
+    }>>;
+}
+declare class TuyauHTTPError<E extends {
+    response: any;
+} = {
+    response: any;
+}> extends TuyauError<E> {
+    kind: 'http';
+    status: number | undefined;
+    rawResponse: KyResponse | undefined;
+    rawRequest: KyRequest | undefined;
+    response: E['response'];
+    constructor(kyError: HTTPError, response: any);
+}
+/**
+ * Network error that occurs when the server is unreachable or the client is offline
+ */
+declare class TuyauNetworkError extends TuyauError<{
+    response: never;
+}> {
+    kind: 'network';
+    status: undefined;
+    rawResponse: undefined;
+    rawRequest: KyRequest | undefined;
+    response: undefined;
+    constructor(cause: Error, request?: {
+        url: string;
+        method: string;
+    });
+}
+
+/**
+ * Normalizes the error type to satisfy TuyauError's constraint.
+ * Routes without typed errors pass `unknown`, which maps to `{ response: any }`.
+ * Always includes a `{ status: number; response: unknown }` fallback so that
+ * catch-all blocks after exhaustive `isStatus()` checks never resolve to `never`.
+ */
+type NormalizeError<E> = (E extends {
+    response: any;
+} ? E : {
+    response: any;
+}) | {
+    status: number;
+    response: unknown;
+};
+/**
+ * A promise wrapper that adds `.safe()` for non-throwing error handling.
+ * Implements PromiseLike so `await` works transparently.
+ */
+declare class TuyauPromise<Data, Errors = unknown> implements PromiseLike<Data> {
+    #private;
+    constructor(promise: Promise<Data>);
+    then<R1 = Data, R2 = never>(onfulfilled?: ((value: Data) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: any) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    catch<R = never>(onrejected?: ((reason: any) => R | PromiseLike<R>) | null): Promise<Data | R>;
+    finally(onfinally?: (() => void) | null): Promise<Data>;
+    /**
+     * Returns a tuple instead of throwing on error.
+     * - On success: `[data, null]`
+     * - On error: `[null, TuyauError]`
+     */
+    safe(): Promise<[
+        data: Data,
+        error: null
+    ] | [data: null, error: TuyauError<NormalizeError<Errors>>]>;
+}
+
+export { type AdonisEndpoint as A, type BaseRequestOptions as B, type CurrentRouteOptions as C, type TuyauPlugin as D, type EndpointByMethodPattern as E, type MaybeArray as F, type UserRegistry as G, PathWithRegistry as H, type InferRoutes as I, RouteWithRegistry as J, Path as K, Route as L, type Method as M, type KnownStatuses as N, type PatternsByMethod as P, type QueryParameters as Q, type RegistryGroupedByMethod as R, type StrKeys as S, type TuyauRegistry as T, type UnionToIntersection as U, type ValueOf as V, type TuyauConfiguration as a, type TransformApiDefinition as b, type InferTree as c, type RequestArgs as d, TuyauPromise as e, type ErrorResponseOf as f, TuyauError as g, TuyauHTTPError as h, TuyauNetworkError as i, type EndpointTypes as j, type SchemaEndpoint as k, type ExtractQuery as l, type ExtractQueryForGet as m, type ExtractBody as n, type ExtractResponse as o, type ExtractErrorResponse as p, type AdonisRegistry as q, type Endpoints as r, type EndpointByName as s, type ResponseType as t, type TuyauRequestOptions as u, type RawRequestArgs as v, type ResponseOf as w, type EndpointFn as x, type EndpointsByMethod as y, type RegValues as z };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tuyau/core",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "E2E typesafe client for AdonisJS",
   "author": "Julien Ripouteau <julien@ripouteau.com>",
   "license": "MIT",
@@ -48,22 +48,22 @@
     }
   },
   "dependencies": {
-    "ky": "^1.14.2",
+    "ky": "^1.14.3",
     "object-to-formdata": "^4.5.1"
   },
   "devDependencies": {
-    "@adonisjs/assembler": "^8.0.0-next.27",
-    "@adonisjs/core": "^7.0.0-next.16",
-    "@adonisjs/http-server": "^8.0.0-next.16",
-    "@faker-js/faker": "^10.1.0",
-    "@poppinss/ts-exec": "^1.4.1",
-    "@types/node": "^25.0.3",
+    "@adonisjs/assembler": "^8.0.0",
+    "@adonisjs/core": "^7.0.1",
+    "@adonisjs/http-server": "^8.0.0",
+    "@faker-js/faker": "^10.3.0",
+    "@poppinss/ts-exec": "^1.4.4",
+    "@types/node": "^25.3.3",
     "@typescript/analyze-trace": "^0.10.1",
-    "@vinejs/vine": "^4.2.0"
+    "@vinejs/vine": "^4.3.0"
   },
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "latest"
   },
   "c8": {
     "reporter": [
@@ -90,7 +90,7 @@
     "clean": "del-cli build",
     "copy:templates": "copyfiles --up 1 \"stubs/**/*.stub\" build",
     "typecheck": "tsc --noEmit",
-    "format": "prettier --write .",
+    "format": "oxfmt --write .",
     "quick:test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts --force-exit",
     "test": "c8 npm run quick:test",
     "index:commands": "adonis-kit index build/commands",