@tuyau/core 0.4.1 → 1.0.0-beta.0

package/build/backend/generate_registry.d.ts

@@ -0,0 +1,182 @@
+import * as _adonisjs_assembler_routes_scanner from '@adonisjs/assembler/routes_scanner';
+import * as _poppinss_cliui_types from '@poppinss/cliui/types';
+import * as _poppinss_cliui from '@poppinss/cliui';
+import * as _poppinss_colors_types from '@poppinss/colors/types';
+import { DevServerOptions } from './types/common.ts';
+
+/**
+ * Exposes the API to start the development server in HMR, watch or static mode
+ *
+ * In HMR mode, the DevServer will exec the "bin/server.ts" file and let hot-hook
+ * manage the changes using hot module reloading.
+ *
+ * In watch mode, the DevServer will start an internal watcher and restarts the server
+ * after every file change. The files must be part of the TypeScript project (via tsconfig.json),
+ * or registered as metaFiles.
+ *
+ * In static mode, the server runs without file watching or hot reloading.
+ *
+ * @example
+ * const devServer = new DevServer(cwd, { hmr: true, hooks: [] })
+ * await devServer.start(ts)
+ */
+declare class DevServer {
+    #private;
+    /**
+     * CLI UI instance for displaying colorful messages and progress information
+     */
+    ui: {
+        colors: _poppinss_colors_types.Colors;
+        logger: _poppinss_cliui.Logger;
+        table: (tableOptions?: Partial<_poppinss_cliui_types.TableOptions>) => _poppinss_cliui.Table;
+        tasks: (tasksOptions?: Partial<_poppinss_cliui_types.TaskManagerOptions>) => _poppinss_cliui.TaskManager;
+        icons: {
+            tick: string;
+            cross: string;
+            bullet: string;
+            nodejs: string;
+            pointer: string;
+            info: string;
+            warning: string;
+            squareSmallFilled: string;
+        };
+        sticker: () => _poppinss_cliui.Instructions;
+        instructions: () => _poppinss_cliui.Instructions;
+        switchMode(modeToUse: "raw" | "silent" | "normal"): void;
+        useRenderer(rendererToUse: _poppinss_cliui_types.RendererContract): void;
+        useColors(colorsToUse: _poppinss_colors_types.Colors): void;
+    };
+    /**
+     * The mode in which the DevServer is running
+     *
+     * Returns the current operating mode of the development server:
+     * - 'hmr': Hot Module Reloading enabled
+     * - 'watch': File system watching with full restarts
+     * - 'static': No file watching or hot reloading
+     */
+    get mode(): "hmr" | "watch" | "static";
+    /**
+     * Script file to start the development server
+     */
+    scriptFile: string;
+    /**
+     * The current working directory URL
+     */
+    cwd: URL;
+    /**
+     * File path computed from the cwd
+     */
+    cwdPath: string;
+    /**
+     * Development server configuration options including hooks and environment variables
+     */
+    options: DevServerOptions;
+    /**
+     * Create a new DevServer instance
+     *
+     * @param cwd - The current working directory URL
+     * @param options - Development server configuration options
+     */
+    constructor(cwd: URL, options: DevServerOptions);
+    /**
+     * Adds listener to get notified when dev server is closed
+     *
+     * Registers a callback function that will be invoked when the development
+     * server's child process exits. The callback receives the exit code.
+     *
+     * @param callback - Function to call when dev server closes
+     * @returns This DevServer instance for method chaining
+     *
+     * @example
+     * devServer.onClose((exitCode) => {
+     *   console.log(`Server closed with exit code: ${exitCode}`)
+     * })
+     */
+    onClose(callback: (exitCode: number) => any): this;
+    /**
+     * Adds listener to get notified when dev server encounters an error
+     *
+     * Registers a callback function that will be invoked when the development
+     * server's child process encounters an error or fails to start.
+     *
+     * @param callback - Function to call when dev server encounters an error
+     * @returns This DevServer instance for method chaining
+     *
+     * @example
+     * devServer.onError((error) => {
+     *   console.error('Dev server error:', error.message)
+     * })
+     */
+    onError(callback: (error: any) => any): this;
+    /**
+     * Closes watchers and terminates the running child process
+     *
+     * Cleans up keyboard shortcuts, stops file system watchers, and kills
+     * the HTTP server child process. This should be called when shutting down
+     * the development server.
+     *
+     * @example
+     * await devServer.close()
+     */
+    close(): Promise<void>;
+    /**
+     * Starts the development server in static or HMR mode
+     *
+     * Initializes the server and starts the HTTP server. The mode is determined
+     * by the `hmr` option in DevServerOptions. In HMR mode, hot-hook is configured
+     * to enable hot module reloading.
+     *
+     * @param ts - TypeScript module reference
+     *
+     * @example
+     * const devServer = new DevServer(cwd, { hmr: true, hooks: [] })
+     * await devServer.start(ts)
+     */
+    start(): Promise<void>;
+    /**
+     * Starts the development server in watch mode and restarts on file changes
+     *
+     * Initializes the server, starts the HTTP server, and sets up a file system
+     * watcher that monitors for changes. When files are added, modified, or deleted,
+     * the server automatically restarts. The watcher respects TypeScript project
+     * configuration and metaFiles settings.
+     *
+     * @param ts - TypeScript module reference
+     * @param options - Watch options including polling mode
+     *
+     * @example
+     * const devServer = new DevServer(cwd, { hooks: [] })
+     * await devServer.startAndWatch(ts, { poll: false })
+     */
+    startAndWatch(options?: {
+        poll: boolean;
+    }): Promise<void>;
+}
+
+interface GenerateRegistryConfig {
+    /**
+     * Path to write the generated registry file
+     * @default ./.adonisjs/client/registry.ts
+     */
+    output?: string;
+    /**
+     * Routes filtering configuration
+     */
+    routes?: {
+        /**
+         * Only include routes matching these patterns (route names)
+         * Can be strings, regex patterns, or functions
+         */
+        only?: Array<string | RegExp | ((routeName: string) => boolean)>;
+        /**
+         * Exclude routes matching these patterns (route names)
+         * Can be strings, regex patterns, or functions
+         */
+        except?: Array<string | RegExp | ((routeName: string) => boolean)>;
+    };
+}
+declare function generateRegistry(options?: GenerateRegistryConfig): {
+    run(devServer: DevServer, routesScanner: _adonisjs_assembler_routes_scanner.RoutesScanner): Promise<void>;
+};
+
+export { generateRegistry };

package/build/backend/generate_registry.js

@@ -0,0 +1,88 @@
+// src/backend/generate_registry.ts
+import { dirname } from "path";
+import string from "@adonisjs/core/helpers/string";
+import { writeFile, mkdir } from "fs/promises";
+async function writeOutputFile(filePath, content) {
+  const dir = dirname(filePath);
+  await mkdir(dir, { recursive: true });
+  await writeFile(filePath, content);
+}
+function matchesPattern(routeName, pattern) {
+  if (typeof pattern === "string") return routeName.includes(pattern);
+  if (pattern instanceof RegExp) return pattern.test(routeName);
+  if (typeof pattern === "function") return pattern(routeName);
+  return false;
+}
+function filterRoutes(routes, filters) {
+  if (!filters) return routes;
+  const { only, except } = filters;
+  if (only && except)
+    throw new Error('Cannot use both "only" and "except" filters at the same time');
+  if (only) {
+    return routes.filter((route) => only.some((pattern) => matchesPattern(route.name, pattern)));
+  }
+  if (except) {
+    return routes.filter((route) => !except.some((pattern) => matchesPattern(route.name, pattern)));
+  }
+  return routes;
+}
+function generateRouteParams(route) {
+  const dynamicParams = route.tokens.filter((token) => token.type === 1);
+  const paramsType = dynamicParams.map((token) => `${token.val}: string`).join("; ");
+  const paramsTuple = dynamicParams.map(() => "string").join(", ");
+  return { paramsType, paramsTuple };
+}
+function generateRegistryEntry(route) {
+  const requestType = route.request?.type || "{}";
+  const responseType = route.response?.type || "unknown";
+  const { paramsType, paramsTuple } = generateRouteParams(route);
+  const routeName = route.name.split(".").map((segment) => string.camelCase(segment)).join(".");
+  return `  '${routeName}': {
+    methods: ${JSON.stringify(route.methods)},
+    pattern: '${route.pattern}',
+    tokens: ${JSON.stringify(route.tokens)},
+    types: placeholder as {
+      body: ${requestType}
+      paramsTuple: [${paramsTuple}]
+      params: ${paramsType ? `{ ${paramsType} }` : "{}"}
+      query: {}
+      response: ${responseType}
+    },
+  }`;
+}
+function generateRegistryContent(routes) {
+  const registryEntries = routes.map(generateRegistryEntry).join(",\n");
+  return `/* eslint-disable prettier/prettier */
+import type { AdonisEndpoint } from '@tuyau/core/types'
+import type { Infer } from '@vinejs/vine/types'
+
+const placeholder: any = {}
+export const registry = {
+${registryEntries}
+} as const satisfies Record<string, AdonisEndpoint>
+
+declare module '@tuyau/core/types' {
+  type Registry = typeof registry
+  export interface UserRegistry extends Registry {}
+}
+`;
+}
+function generateRegistry(options) {
+  const config = {
+    output: "./.adonisjs/client/registry.ts",
+    ...options
+  };
+  return {
+    async run(devServer, routesScanner) {
+      const startTime = process.hrtime();
+      const scannedRoutes = routesScanner.getScannedRoutes();
+      const filteredRoutes = filterRoutes(scannedRoutes, config.routes);
+      const registryContent = generateRegistryContent(filteredRoutes);
+      await writeOutputFile(config.output, registryContent);
+      devServer.ui.logger.info(`created ${config.output}`, { startTime });
+    }
+  };
+}
+export {
+  generateRegistry
+};

package/build/client/index.d.ts

@@ -0,0 +1,82 @@
+import { UrlFor } from '@adonisjs/http-server/client/url_builder';
+import { AdonisEndpoint, TuyauConfiguration, BuildNamed, RegistryGroupedByMethod, PatternsByMethod, RequestArgs, EndpointByMethodPattern, StrKeys, Method } from './types/index.js';
+import { KyResponse, KyRequest, HTTPError } from 'ky';
+
+/**
+ * Main client class for making HTTP requests to AdonisJS endpoints
+ * Provides both fluent API and direct method calling capabilities
+ */
+declare class Tuyau<R extends Record<string, AdonisEndpoint>> {
+    #private;
+    private config;
+    readonly api: BuildNamed<R>;
+    readonly urlFor: UrlFor<RegistryGroupedByMethod<R>>;
+    /**
+     * Initializes the Tuyau client with provided configuration
+     */
+    constructor(config: TuyauConfiguration<R>);
+    /**
+     * Makes a GET request to the specified pattern
+     */
+    get<P extends PatternsByMethod<R, 'GET'>>(pattern: P, args: RequestArgs<EndpointByMethodPattern<R, 'GET', P>>): Promise<EndpointByMethodPattern<R, 'GET', P>['types']['response']>;
+    /**
+     * Makes a POST request to the specified pattern
+     */
+    post<P extends PatternsByMethod<R, 'POST'>>(pattern: P, args: RequestArgs<EndpointByMethodPattern<R, 'POST', P>>): Promise<EndpointByMethodPattern<R, 'POST', P>['types']['response']>;
+    /**
+     * Makes a PUT request to the specified pattern
+     */
+    put<P extends PatternsByMethod<R, 'PUT'>>(pattern: P, args: RequestArgs<EndpointByMethodPattern<R, 'PUT', P>>): Promise<EndpointByMethodPattern<R, 'PUT', P>['types']['response']>;
+    /**
+     * Makes a PATCH request to the specified pattern
+     */
+    patch<P extends PatternsByMethod<R, 'PATCH'>>(pattern: P, args: RequestArgs<EndpointByMethodPattern<R, 'PATCH', P>>): Promise<EndpointByMethodPattern<R, 'PATCH', P>['types']['response']>;
+    /**
+     * Makes a DELETE request to the specified pattern
+     */
+    delete<P extends PatternsByMethod<R, 'DELETE'>>(pattern: P, args: RequestArgs<EndpointByMethodPattern<R, 'DELETE', P>>): Promise<EndpointByMethodPattern<R, 'DELETE', P>['types']['response']>;
+    /**
+     * Makes a HEAD request to the specified pattern
+     */
+    head<P extends PatternsByMethod<R, 'HEAD'>>(pattern: P, args: RequestArgs<EndpointByMethodPattern<R, 'HEAD', P>>): Promise<EndpointByMethodPattern<R, 'HEAD', P>['types']['response']>;
+    /**
+     * Makes a request to a named endpoint
+     */
+    request<Name extends StrKeys<R>>(name: Name, args: RequestArgs<R[Name]>): Promise<R[Name]['types']['response']>;
+    /**
+     * Gets route information by name including URL and HTTP method
+     */
+    getRoute<Name extends StrKeys<R>>(name: Name, args: RequestArgs<R[Name]>): {
+        url: string;
+        methods: Method[];
+    };
+    /**
+     * Creates a proxy-based fluent API for accessing endpoints by name
+     */
+    private makeNamed;
+}
+/**
+ * Factory function to create a new Tuyau client instance
+ */
+declare function createTuyau<R extends Record<string, AdonisEndpoint>>(config: TuyauConfiguration<R>): Tuyau<R>;
+
+declare function parseResponse(response?: KyResponse): Promise<unknown>;
+declare class TuyauHTTPError extends Error {
+    status: number | undefined;
+    rawResponse: KyResponse | undefined;
+    rawRequest: KyRequest | undefined;
+    response: any;
+    constructor(kyError: HTTPError, response: any);
+}
+/**
+ * Network error that occurs when the server is unreachable or the client is offline
+ */
+declare class TuyauNetworkError extends Error {
+    cause: Error;
+    constructor(cause: Error, request?: {
+        url: string;
+        method: string;
+    });
+}
+
+export { Tuyau, TuyauHTTPError, TuyauNetworkError, createTuyau, parseResponse };

package/build/client/index.js

@@ -0,0 +1,291 @@
+// src/client/tuyau.ts
+import ky, { HTTPError } from "ky";
+import { serialize } from "object-to-formdata";
+import { createUrlBuilder } from "@adonisjs/http-server/client/url_builder";
+
+// src/client/errors.ts
+async function parseResponse(response) {
+  if (!response) return;
+  const responseType = response.headers.get("Content-Type")?.split(";")[0];
+  if (responseType === "application/json") {
+    return await response.json();
+  } else if (responseType === "application/octet-stream") {
+    return await response.arrayBuffer();
+  }
+  return await response.text();
+}
+var TuyauHTTPError = class extends Error {
+  status;
+  rawResponse;
+  rawRequest;
+  response;
+  constructor(kyError, response) {
+    const status = kyError.response?.status;
+    const reason = status ? `status code ${status}` : "an unknown error";
+    const url = kyError.request?.url.replace(kyError.options.prefixUrl || "", "");
+    const message = kyError.response ? `Request failed with ${reason}: ${kyError.request?.method.toUpperCase()} /${url}` : `Request failed with ${reason}`;
+    super(message, { cause: kyError });
+    this.rawResponse = kyError.response;
+    this.response = response;
+    this.status = kyError.response?.status;
+    this.rawRequest = kyError.request;
+    this.name = "TuyauHTTPError";
+  }
+};
+var TuyauNetworkError = class extends Error {
+  constructor(cause, request) {
+    const message = request ? `Network error: ${request.method.toUpperCase()} ${request.url}` : "Network error occurred";
+    super(message, { cause });
+    this.cause = cause;
+    this.name = "TuyauNetworkError";
+  }
+};
+
+// src/client/utils.ts
+function buildSearchParams(query) {
+  if (!query) return;
+  let stringified = "";
+  const append = (key, value, isArray = false) => {
+    if (value === void 0 || value === null) return;
+    const encodedKey = encodeURIComponent(key);
+    const encodedValue = encodeURIComponent(value);
+    const keyValuePair = `${encodedKey}${isArray ? "[]" : ""}=${encodedValue}`;
+    stringified += (stringified ? "&" : "?") + keyValuePair;
+  };
+  for (const [key, value] of Object.entries(query)) {
+    if (!value) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) append(key, v, true);
+    } else {
+      append(key, `${value}`);
+    }
+  }
+  return stringified;
+}
+function removeSlash(value) {
+  return value.replace(/^\//, "");
+}
+function isObject(value) {
+  return typeof value === "object" && !Array.isArray(value) && value !== null;
+}
+var isServer = typeof FileList === "undefined";
+var isReactNative = typeof navigator !== "undefined" && navigator.product === "ReactNative";
+
+// src/client/tuyau.ts
+var Tuyau = class {
+  /**
+   * Initializes the Tuyau client with provided configuration
+   */
+  constructor(config) {
+    this.config = config;
+    this.api = this.makeNamed([]);
+    this.#entries = Object.entries(this.config.registry);
+    this.urlFor = this.#createUrlBuilder();
+    this.#applyPlugins();
+    this.#client = ky.create(this.#mergeKyConfiguration());
+  }
+  api;
+  urlFor;
+  #entries;
+  #client;
+  /**
+   * Merges the default Ky configuration with user-provided config
+   */
+  #mergeKyConfiguration() {
+    return {
+      prefixUrl: this.config.baseUrl,
+      ...this.config,
+      hooks: {
+        ...this.config.hooks,
+        beforeRequest: [
+          ...this.config.hooks?.beforeRequest || [],
+          this.#appendCsrfToken.bind(this)
+        ]
+      }
+    };
+  }
+  /**
+   * Applies registered plugins to the client configuration
+   */
+  #applyPlugins() {
+    this.config.plugins?.forEach((plugin) => plugin({ options: this.config }));
+  }
+  /**
+   * Creates a URL builder instance for generating URLs based on the route registry
+   */
+  #createUrlBuilder() {
+    const rootEntries = this.#entries.map(([name, entry]) => ({ name, domain: "root", ...entry }));
+    return createUrlBuilder({ root: rootEntries }, buildSearchParams);
+  }
+  /**
+   * Automatically appends CSRF token from cookies to requests
+   */
+  #appendCsrfToken(request) {
+    const xCsrfToken = globalThis.document?.cookie.split("; ").find((row) => row.startsWith("XSRF-TOKEN="));
+    if (!xCsrfToken) return;
+    request.headers.set("X-XSRF-TOKEN", decodeURIComponent(xCsrfToken.split("=")[1]));
+  }
+  /**
+   * Checks if a value represents a file for upload
+   */
+  #isFile(v) {
+    if (isReactNative && isObject(v) && v.uri) return true;
+    if (isServer) return v instanceof Blob;
+    return v instanceof FileList || v instanceof File;
+  }
+  /**
+   * Checks if an object contains any file uploads
+   */
+  #hasFile(obj) {
+    if (!obj) return false;
+    return Object.values(obj).some((val) => {
+      if (Array.isArray(val)) return val.some(this.#isFile);
+      return this.#isFile(val);
+    });
+  }
+  #getLowercaseMethod(method) {
+    return method.toLowerCase();
+  }
+  #buildUrl(name, method, args) {
+    const lowercaseMethod = this.#getLowercaseMethod(method);
+    const usedMethod = lowercaseMethod === "head" || lowercaseMethod === "options" ? "get" : lowercaseMethod;
+    return this.urlFor[usedMethod](name, args?.params || {}).url;
+  }
+  /**
+   * Performs the actual HTTP request with proper body formatting
+   */
+  async #doFetch(name, method, args) {
+    const url = this.#buildUrl(name, method, args);
+    let key = "json";
+    let body = args.body;
+    if (!(body instanceof FormData) && this.#hasFile(body)) {
+      body = serialize(body, { indices: true });
+      key = "body";
+    } else if (body instanceof FormData) {
+      key = "body";
+    }
+    const isGetOrHead = ["GET", "HEAD"].includes(method);
+    const { body: _, ...restArgs } = args;
+    const requestOptions = {
+      searchParams: buildSearchParams(args?.query || {}),
+      [key]: !isGetOrHead ? body : void 0,
+      ...restArgs
+    };
+    try {
+      const res = await this.#client[this.#getLowercaseMethod(method)](
+        removeSlash(url),
+        requestOptions
+      );
+      let data;
+      const responseType = res.headers.get("Content-Type")?.split(";")[0];
+      if (responseType === "application/json") {
+        data = await res.json();
+      } else if (responseType === "application/octet-stream") {
+        data = await res.arrayBuffer();
+      } else {
+        data = await res.text();
+      }
+      return data;
+    } catch (originalError) {
+      if (originalError instanceof HTTPError) {
+        const parsedResponse = await parseResponse(originalError.response);
+        throw new TuyauHTTPError(originalError, parsedResponse);
+      }
+      throw new TuyauNetworkError(originalError, { url, method });
+    }
+  }
+  /**
+   * Finds an endpoint definition by HTTP method and pattern
+   */
+  #byMethodPath(method, pattern) {
+    const [name, endpoint] = this.#entries.find(
+      ([, e]) => e.methods[0] === method && e.pattern === pattern
+    ) || [null, null];
+    if (!name || !endpoint) throw new Error(`No ${method} ${pattern}`);
+    return { name, endpoint };
+  }
+  /**
+   * Makes a request to a specific endpoint using method and pattern
+   */
+  #request(method, pattern, args) {
+    const { name, endpoint } = this.#byMethodPath(method, pattern);
+    return this.#doFetch(name, endpoint.methods[0], args);
+  }
+  /**
+   * Makes a GET request to the specified pattern
+   */
+  get(pattern, args) {
+    return this.#request("GET", pattern, args);
+  }
+  /**
+   * Makes a POST request to the specified pattern
+   */
+  post(pattern, args) {
+    return this.#request("POST", pattern, args);
+  }
+  /**
+   * Makes a PUT request to the specified pattern
+   */
+  put(pattern, args) {
+    return this.#request("PUT", pattern, args);
+  }
+  /**
+   * Makes a PATCH request to the specified pattern
+   */
+  patch(pattern, args) {
+    return this.#request("PATCH", pattern, args);
+  }
+  /**
+   * Makes a DELETE request to the specified pattern
+   */
+  delete(pattern, args) {
+    return this.#request("DELETE", pattern, args);
+  }
+  /**
+   * Makes a HEAD request to the specified pattern
+   */
+  head(pattern, args) {
+    return this.#request("HEAD", pattern, args);
+  }
+  /**
+   * Makes a request to a named endpoint
+   */
+  request(name, args) {
+    const def = this.config.registry[name];
+    return this.#doFetch(name, def.methods[0], args);
+  }
+  /**
+   * Gets route information by name including URL and HTTP method
+   */
+  getRoute(name, args) {
+    const def = this.config.registry[name];
+    if (!def) throw new Error(`Route ${String(name)} not found`);
+    const url = this.#buildUrl(name, def.methods[0], args);
+    return { url, methods: def.methods };
+  }
+  /**
+   * Creates a proxy-based fluent API for accessing endpoints by name
+   */
+  makeNamed(segments) {
+    const dot = segments.join(".");
+    const def = this.config.registry[dot];
+    if (def) {
+      const fn = (args) => this.#doFetch(dot, def.methods[0], args);
+      return new Proxy(fn, {
+        get: (_t, prop) => this.makeNamed([...segments, String(prop)]),
+        apply: (_t, _this, argArray) => fn(...argArray)
+      });
+    }
+    return new Proxy({}, { get: (_t, prop) => this.makeNamed([...segments, String(prop)]) });
+  }
+};
+function createTuyau(config) {
+  return new Tuyau(config);
+}
+export {
+  Tuyau,
+  TuyauHTTPError,
+  TuyauNetworkError,
+  createTuyau,
+  parseResponse
+};