@tuyau/query-core 1.1.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2023
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/build/index.d.ts

@@ -0,0 +1,174 @@
+import { QueryFilters, SkipToken, skipToken, QueryFunctionContext } from '@tanstack/query-core';
+import { RawRequestArgs, BaseRequestOptions } from '@tuyau/core/types';
+import { Tuyau } from '@tuyau/core/client';
+
+/**
+ * Discriminator for the type of TanStack Query operation.
+ * Used in query keys to differentiate between regular queries,
+ * infinite queries, and catch-all path filters
+ */
+type QueryType = 'any' | 'infinite' | 'query';
+/**
+ * Structured query key used by Tuyau's TanStack Query integration.
+ * First element is the route path segments, second is an optional
+ * metadata object containing the request arguments and query type
+ */
+type TuyauQueryKey = [
+    readonly string[],
+    {
+        request?: RawRequestArgs<any>;
+        type?: Exclude<QueryType, 'any'>;
+    }?
+];
+/**
+ * Structured mutation key used by Tuyau's TanStack Query integration.
+ * Contains only the route path segments since mutations don't need
+ * request-based differentiation
+ */
+type TuyauMutationKey = [readonly string[]];
+/**
+ * Options forwarded to the underlying Ky HTTP client, extended
+ * with `abortOnUnmount` to automatically abort requests when
+ * the component using the query unmounts
+ */
+interface TuyauRequestOptions extends BaseRequestOptions {
+    abortOnUnmount?: boolean;
+}
+/**
+ * Base options shared by all Tuyau query/mutation option builders.
+ * Allows passing Ky-specific options via the `tuyau` property
+ */
+interface TuyauQueryBaseOptions {
+    tuyau?: TuyauRequestOptions;
+}
+/**
+ * Methods available on every node of the Tuyau query client proxy tree.
+ * Provides path-level query key and filter generation for cache operations
+ * like invalidation or removal across all query types for a given route
+ */
+interface DecorateRouterKeyable {
+    pathKey: () => TuyauQueryKey;
+    pathFilter: (filters?: QueryFilters<TuyauQueryKey>) => WithRequired<QueryFilters<TuyauQueryKey>, 'queryKey'>;
+}
+/**
+ * Generic function type helper
+ */
+type Fn<Result = void, Args extends unknown[] = unknown[]> = (...args: Args) => Result;
+/**
+ * Like `Omit` but distributes over union types.
+ * Standard `Omit` collapses unions, this preserves each union member
+ */
+type DistributiveOmit<TObj, TKey extends keyof any> = TObj extends any ? Omit<TObj, TKey> : never;
+/**
+ * Makes specific keys of a type required while keeping the rest unchanged
+ */
+type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
+
+/**
+ * Type guard that checks if a value is a plain object
+ * (not null, not an array)
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Immediately invokes a function and returns its result.
+ * Used to create query/mutation functions inline with
+ * proper skip token handling
+ */
+declare function invoke(fn: undefined): undefined;
+declare function invoke<T>(fn: Fn<T>): T;
+/**
+ * Builds a structured TanStack Query key from route segments,
+ * request arguments, and query type.
+ *
+ * For infinite queries, automatically strips `cursor` and `direction`
+ * from query/body params to ensure stable cache keys across pages
+ */
+declare function buildKey(opts: {
+    segments: string[];
+    request?: unknown;
+    type: QueryType;
+}): TuyauQueryKey;
+/**
+ * Extracts Ky-compatible HTTP options from Tuyau request options,
+ * filtering out Tuyau-specific properties like `abortOnUnmount`
+ */
+declare function extractKyOptions(tuyauOpts?: TuyauRequestOptions): Omit<TuyauRequestOptions, 'abortOnUnmount'>;
+
+/**
+ * Converts a camelCase string to snake_case.
+ * Used to transform proxy property names (e.g. `getArticles`)
+ * into AdonisJS route name segments (e.g. `get_articles`)
+ */
+declare function toSnakeCase(str: string): string;
+/**
+ * Joins an array of camelCase segments into a dot-separated
+ * snake_case route name that matches AdonisJS conventions.
+ * e.g. `['users', 'getProfile']` → `'users.get_profile'`
+ */
+declare function segmentsToRouteName(segments: string[]): string;
+
+/**
+ * Internal options for building a query function
+ */
+interface CreateQueryFnOptions {
+    request: RawRequestArgs<any> | SkipToken;
+    opts?: TuyauQueryBaseOptions;
+    routeName: string;
+    client: Tuyau<any>;
+    globalOptions?: TuyauRequestOptions;
+}
+/**
+ * Creates a TanStack Query `queryFn` from Tuyau route information.
+ * Returns `skipToken` when the request is a skip token (conditional queries).
+ * Handles abort-on-unmount and Ky options extraction.
+ * Ky retries are disabled (retry: 0) to let TanStack Query handle retries
+ */
+declare function createQueryFn(options: CreateQueryFnOptions): typeof skipToken | ((queryFnContext: QueryFunctionContext) => Promise<any>);
+
+/**
+ * Internal options for building an infinite query function.
+ * The `opts` parameter accepts any object with optional `tuyau` and
+ * `pageParamKey` properties — this avoids coupling to framework-specific
+ * option types (React vs Vue) while still accessing the needed values
+ */
+interface CreateInfiniteQueryFnOptions {
+    request: RawRequestArgs<any> | SkipToken;
+    opts?: {
+        tuyau?: TuyauRequestOptions;
+        pageParamKey?: string;
+        [key: string]: any;
+    };
+    routeName: string;
+    client: Tuyau<any>;
+    globalOptions?: TuyauRequestOptions;
+}
+/**
+ * Creates a TanStack Query `queryFn` for infinite queries.
+ * Injects the page parameter into the request query using the
+ * configured `pageParamKey` (defaults to `'page'`).
+ * Returns `skipToken` when the request is a skip token.
+ * Ky retries are disabled (retry: 0) to let TanStack Query handle retries
+ */
+declare function createInfiniteQueryFn(options: CreateInfiniteQueryFnOptions): typeof skipToken | ((queryFnContext: QueryFunctionContext) => Promise<any>);
+
+/**
+ * Builds a mutation key from route path segments
+ */
+declare function getMutationKeyInternal(options: {
+    segments: string[];
+}): TuyauMutationKey;
+/**
+ * Internal options for building a mutation function
+ */
+interface CreateMutationFnOptions {
+    opts?: TuyauQueryBaseOptions;
+    routeName: string;
+    client: Tuyau<any>;
+}
+/**
+ * Creates a TanStack Query `mutationFn` from Tuyau route information.
+ * Ky retries are disabled (retry: 0) to let TanStack Query handle retries
+ */
+declare function createMutationFn(options: CreateMutationFnOptions): (request: any) => Promise<any>;
+
+export { type CreateInfiniteQueryFnOptions, type CreateMutationFnOptions, type CreateQueryFnOptions, type DecorateRouterKeyable, type DistributiveOmit, type Fn, type QueryType, type TuyauMutationKey, type TuyauQueryBaseOptions, type TuyauQueryKey, type TuyauRequestOptions, type WithRequired, buildKey, createInfiniteQueryFn, createMutationFn, createQueryFn, extractKyOptions, getMutationKeyInternal, invoke, isObject, segmentsToRouteName, toSnakeCase };

package/build/index.js

@@ -0,0 +1,135 @@
+// src/utils.ts
+import { skipToken } from "@tanstack/query-core";
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invoke(fn) {
+  return fn?.();
+}
+function buildKey(opts) {
+  const { segments, request, type } = opts;
+  const splitPath = segments.flatMap((part) => part.split("."));
+  if (!request && type === "any") {
+    return splitPath.length ? [splitPath] : [];
+  }
+  if (type === "infinite" && isObject(request)) {
+    const query = request.query;
+    const body = request.body;
+    const hasCursorInQuery = isObject(query) && ("direction" in query || "cursor" in query);
+    const hasCursorInBody = isObject(body) && ("direction" in body || "cursor" in body);
+    if (hasCursorInQuery || hasCursorInBody) {
+      const cleanedRequest = { ...request };
+      if (hasCursorInQuery && isObject(query)) {
+        const { cursor: _, direction: __, ...cleanQuery } = query;
+        cleanedRequest.query = cleanQuery;
+      }
+      if (hasCursorInBody && isObject(body)) {
+        const { cursor: _, direction: __, ...cleanBody } = body;
+        cleanedRequest.body = cleanBody;
+      }
+      return [splitPath, { request: cleanedRequest, type: "infinite" }];
+    }
+  }
+  return [
+    splitPath,
+    {
+      ...typeof request !== "undefined" && request !== skipToken && { request },
+      ...type && type !== "any" && { type }
+    }
+  ];
+}
+function extractKyOptions(tuyauOpts) {
+  if (!tuyauOpts) return {};
+  const { abortOnUnmount, ...kyOptions } = tuyauOpts;
+  return kyOptions;
+}
+
+// src/helpers.ts
+function toSnakeCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+function segmentsToRouteName(segments) {
+  return segments.map(toSnakeCase).join(".");
+}
+
+// src/query_fn.ts
+import { skipToken as skipToken2 } from "@tanstack/query-core";
+function createQueryFn(options) {
+  const { request, routeName, opts, client, globalOptions } = options;
+  return invoke(() => {
+    if (request === skipToken2) return skipToken2;
+    return async (queryFnContext) => {
+      const effectiveAbortOnUnmount = opts?.tuyau?.abortOnUnmount ?? globalOptions?.abortOnUnmount ?? false;
+      const kyOptions = extractKyOptions(opts?.tuyau);
+      return await client.request(routeName, {
+        ...request,
+        ...kyOptions,
+        retry: 0,
+        ...effectiveAbortOnUnmount ? { signal: queryFnContext.signal } : {}
+      });
+    };
+  });
+}
+
+// src/infinite_query_fn.ts
+import { skipToken as skipToken3 } from "@tanstack/query-core";
+function createInfiniteQueryFn(options) {
+  const { request, routeName, opts, client, globalOptions } = options;
+  return invoke(() => {
+    if (request === skipToken3) return skipToken3;
+    return async (queryFnContext) => {
+      const { pageParam } = queryFnContext;
+      const effectiveAbortOnUnmount = opts?.tuyau?.abortOnUnmount ?? globalOptions?.abortOnUnmount ?? false;
+      const kyOptions = extractKyOptions(opts?.tuyau);
+      const pageParamKey = opts?.pageParamKey || "page";
+      let requestArgs;
+      if (isObject(request)) {
+        if (pageParam !== void 0) {
+          requestArgs = {
+            ...request,
+            query: { ...request.query, [pageParamKey]: pageParam }
+          };
+        } else {
+          requestArgs = request;
+        }
+      } else {
+        requestArgs = { query: pageParam !== void 0 ? { [pageParamKey]: pageParam } : {} };
+      }
+      return await client.request(routeName, {
+        ...requestArgs,
+        ...kyOptions,
+        retry: 0,
+        ...effectiveAbortOnUnmount ? { signal: queryFnContext.signal } : {}
+      });
+    };
+  });
+}
+
+// src/mutation_fn.ts
+function getMutationKeyInternal(options) {
+  const key = [options.segments.flatMap((part) => part.split("."))];
+  return key;
+}
+function createMutationFn(options) {
+  return async (request) => {
+    const kyOptions = extractKyOptions(options.opts?.tuyau);
+    const requestArgs = request || {};
+    return await options.client.request(options.routeName, {
+      ...requestArgs,
+      ...kyOptions,
+      retry: 0
+    });
+  };
+}
+export {
+  buildKey,
+  createInfiniteQueryFn,
+  createMutationFn,
+  createQueryFn,
+  extractKyOptions,
+  getMutationKeyInternal,
+  invoke,
+  isObject,
+  segmentsToRouteName,
+  toSnakeCase
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tuyau/query-core",
+  "type": "module",
+  "version": "1.1.0",
+  "description": "Shared utilities for Tuyau Tanstack Query integrations",
+  "author": "Julien Ripouteau <julien@ripouteau.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/Julien-R44/tuyau#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Julien-R44/tuyau.git",
+    "directory": "packages/query-core"
+  },
+  "bugs": {
+    "url": "https://github.com/Julien-R44/tuyau/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "typescript",
+    "typesafe",
+    "tanstack-query",
+    "tuyau"
+  ],
+  "exports": {
+    ".": "./build/index.js"
+  },
+  "main": "build/index.js",
+  "files": [
+    "build"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/query-core": "^5.74.7",
+    "@tuyau/core": "^1.0.0-beta.9"
+  },
+  "devDependencies": {
+    "@tanstack/query-core": "^5.74.7",
+    "@tuyau/core": "1.2.1"
+  },
+  "tsup": {
+    "entry": [
+      "./src/index.ts"
+    ],
+    "outDir": "./build",
+    "clean": true,
+    "format": "esm",
+    "dts": true,
+    "target": "esnext"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "lint": "oxlint .",
+    "typecheck": "tsc --noEmit",
+    "build": "tsup-node",
+    "test": "pnpm quick:test",
+    "quick:test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts --force-exit",
+    "checks": "pnpm lint && pnpm typecheck"
+  }
+}