quetch 0.2.0 → 0.3.0

package/lib/errors/RequestError.ts

@@ -1,4 +1,4 @@
-import type { AnyQuery } from "../types";
+import type { QueryAny } from "../types";
 
 /**
  * Error to be thrown in case there is an issue with the query call. Only instances of this error will be caught by the `retry()` middleware.
@@ -7,7 +7,7 @@ export class RequestError extends Error {
   constructor(
     message: string,
     public status: number,
-    public query?: AnyQuery,
+    public query?: QueryAny,
     public request?: Request,
     public response?: Response,
   ) {

package/lib/errors.ts

@@ -1,2 +1,2 @@
 // File automatically generated by `vite-plugin-module-list`
-export { RequestError } from "./errors/RequestError";
+export { RequestError } from "./errors/RequestError.js";

package/lib/middlewares/aggregate.ts

@@ -1,7 +1,7 @@
 import { sleep } from "futurise";
 
 import { RequestError } from "../errors";
-import type { AnyQuery, Handler } from "../types";
+import type { Handler, QueryAny } from "../types";
 
 /**
  * Aggregates multiple incoming query calls into one query.
@@ -13,7 +13,7 @@ import type { AnyQuery, Handler } from "../types";
  * @param options
  * @returns
  */
-export function aggregate<I extends AnyQuery, O, In extends AnyQuery, On>({
+export function aggregate<I extends QueryAny, O, In extends QueryAny, On>({
   queryGroupId = ({ type, method = "get" }) => {
     if (method !== "get") {
       return undefined;
@@ -31,9 +31,9 @@ export function aggregate<I extends AnyQuery, O, In extends AnyQuery, On>({
   },
   mergeQuery = (query, _currentQuery) => query,
   delay = 200,
-  queryForGroup = (queryList, _): AnyQuery => ({
+  queryForGroup = (queryList, _): QueryAny => ({
     type: queryList[0].type,
-    method: "get",
+    method: "read",
     multiple: true,
     filter: {
       operator: "include",
@@ -55,7 +55,7 @@ export function aggregate<I extends AnyQuery, O, In extends AnyQuery, On>({
   queryId?: (query: I) => string | undefined;
   mergeQuery?: (query: I, currentQuery: I) => I;
   delay?: number;
-  queryForGroup: (queryList: I[], group: string) => AnyQuery;
+  queryForGroup: (queryList: I[], group: string) => QueryAny;
   resultForQuery: (resultList: O[], query: I) => O | never;
 }): Handler<I, O, In, On> {
   const queryGroupMap = new Map<

package/lib/middlewares/cache.ts

@@ -1,11 +1,11 @@
-import type { AnyQueryExternal, Handler, Store } from "../types";
+import type { Handler, QueryAny, Store } from "../types";
 
-type CachedItem<I extends AnyQueryExternal> = {
+type CachedItem<I extends QueryAny> = {
   query: I;
   value: any;
 };
 
-type CacheOptions<I extends AnyQueryExternal> = {
+type CacheOptions<I extends QueryAny> = {
   /**
    * Unique identifier for the item to cache.
    * Returns `undefined` if the item should not be cached.
@@ -36,15 +36,10 @@ type CacheOptions<I extends AnyQueryExternal> = {
   mergeItem: (value: any, cachedValue: any, query: I, cachedQuery: I) => any;
 };
 
-export function cache<
-  I extends AnyQueryExternal,
-  O,
-  In extends AnyQueryExternal,
-  On,
->({
-  itemId = ({ context = {}, method = "get", type }: I) => {
-    if (method === "get" && context.id) {
-      return `${type}/${context.id}`;
+export function cache<I extends QueryAny, O, In extends QueryAny, On>({
+  itemId = ({ context = {}, method = "read", type }: I) => {
+    if (method === "read" && context.id) {
+      return `${String(type)}/${context.id}`;
     }
     return undefined;
   },

package/lib/middlewares.ts

@@ -1,10 +1,10 @@
 // File automatically generated by `vite-plugin-module-list`
-export { aggregate } from "./middlewares/aggregate";
-export { branch } from "./middlewares/branch";
-export { cache } from "./middlewares/cache";
-export { combine } from "./middlewares/combine";
-export { fetchExternal } from "./middlewares/fetchExternal";
-export { fetchLocal } from "./middlewares/fetchLocal";
-export { identity } from "./middlewares/identity";
-export { log } from "./middlewares/log";
-export { retry } from "./middlewares/retry";
+export { aggregate } from "./middlewares/aggregate.js";
+export { branch } from "./middlewares/branch.js";
+export { cache } from "./middlewares/cache.js";
+export { combine } from "./middlewares/combine.js";
+export { fetchExternal } from "./middlewares/fetchExternal.js";
+export { fetchLocal } from "./middlewares/fetchLocal.js";
+export { identity } from "./middlewares/identity.js";
+export { log } from "./middlewares/log.js";
+export { retry } from "./middlewares/retry.js";

package/lib/tools/cork.ts

@@ -0,0 +1,6 @@
+import type { NextHandler } from "../types";
+
+/**
+ * Uncallable handler used to terminate a sequence of handlers combined with `combine`.
+ */
+export const cork = undefined as unknown as NextHandler<never, never>;

package/lib/tools/defineCheckQuery.ts

@@ -1,23 +1,28 @@
 import type { CustomFieldMap, Query } from "../types";
 
-export function defineCheckQuery<Entities extends Record<string, object>>() {
+/**
+ * Returns a function that checks queries. This is useful to prevent the query to have its type being narrowed if declared outside of a custom fetcher function argument.
+ *
+ * @returns Function that checks queries.
+ */
+export function defineCheckQuery<M extends Record<string, object>>() {
   function checkQuery<
-    E extends object,
-    C extends CustomFieldMap<E>,
-    const Q extends Query<E, C>,
-  >(query: Q & { type: E[]; customFields?: C }): typeof query;
+    T extends object,
+    C extends CustomFieldMap<T>,
+    const Q extends Query<T, C>,
+  >(query: Q & { type: T[]; customFields?: C }): typeof query;
   function checkQuery<
-    T extends keyof Entities,
-    E extends Entities[T],
-    C extends CustomFieldMap<E>,
-    const Q extends Query<E, C>,
-  >(query: Q & { type: T; customFields?: C }): typeof query;
+    K extends keyof M,
+    T extends M[K],
+    C extends CustomFieldMap<T>,
+    const Q extends Query<T, C>,
+  >(query: Q & { type: K; customFields?: C }): typeof query;
   function checkQuery<
-    T extends keyof Entities,
-    E extends Entities[T] | object,
-    C extends CustomFieldMap<E>,
-    const Q extends Query<E, C>,
-  >(query: Q & { type: T | E[]; customFields?: C }): typeof query {
+    K extends keyof M,
+    T extends M[K] | object,
+    C extends CustomFieldMap<T>,
+    const Q extends Query<T, C>,
+  >(query: Q & { type: K | T[]; customFields?: C }): typeof query {
     return query;
   }
   return checkQuery;

package/lib/tools/defineCustomFetch.ts

@@ -1,70 +1,48 @@
-import type {
-  AnyQuery,
-  CustomFieldMap,
-  EntityItem,
-  Handler,
-  Query,
-} from "../types";
+import type { CustomFieldMap, Handler, Key, Query, Result } from "../types";
 
-import { impasse } from "./impasse";
+import { cork } from "./cork";
 
+/**
+ *
+ *
+ * @param handler
+ * @returns
+ */
 export function defineCustomFetch<M extends Record<string, object>>(
-  handler: Handler<AnyQuery, any, never, never>,
+  handler: Handler<
+    Query<any, any> & { type: Key | any[]; customFields?: CustomFieldMap<any> },
+    any,
+    never,
+    never
+  >,
 ) {
-  function customFetch<
-    E extends object,
-    C extends CustomFieldMap<E>,
-    const Q extends Query<E, C>,
-  >(
-    input: Q & { type: E[]; customFields?: C },
-  ): Promise<
-    Q["method"] extends "get"
-      ? Q extends { multiple: true }
-        ? EntityItem<E, C, Q>[]
-        : EntityItem<E, C, Q>
-      : Q["method"] extends "aggregate"
-      ? number
-      : Q extends { multiple: true }
-      ? EntityItem<E, C, Q>[]
-      : EntityItem<E, C, Q>
-  >;
-  function customFetch<
-    T extends keyof M,
-    E extends M[T],
-    C extends CustomFieldMap<E>,
-    const Q extends Query<E, C>,
-  >(
-    input: Q & { type: T; customFields?: C },
-  ): Promise<
-    Q["method"] extends "get"
-      ? Q extends { multiple: true }
-        ? EntityItem<E, C, Q>[]
-        : EntityItem<E, C, Q>
-      : Q["method"] extends "aggregate"
-      ? number
-      : Q extends { multiple: true }
-      ? EntityItem<E, C, Q>[]
-      : EntityItem<E, C, Q>
-  >;
   async function customFetch<
-    T extends keyof M,
-    E extends M[T] | object,
-    C extends CustomFieldMap<E>,
-    const Q extends Query<E, C>,
-  >(
-    input: Q & { type: T | E[]; customFields?: C },
-  ): Promise<
-    Q["method"] extends "get"
-      ? Q extends { multiple: true }
-        ? EntityItem<E, C, Q>[]
-        : EntityItem<E, C, Q>
-      : Q["method"] extends "aggregate"
-      ? number
-      : Q extends { multiple: true }
-      ? EntityItem<E, C, Q>[]
-      : EntityItem<E, C, Q>
-  > {
-    return await handler(input, impasse);
+    K extends keyof M,
+    T extends M[K],
+    const Q extends Query<T, {}>,
+  >(query: Q & { type: K; customFields?: never }): Promise<Result<T, Q, {}>>;
+  async function customFetch<
+    K extends keyof M,
+    T extends M[K],
+    const Q extends Query<T, C>,
+    const C extends CustomFieldMap<T>,
+  >(query: Q & { type: K; customFields: C }): Promise<Result<T, Q, C>>;
+  async function customFetch<T extends object, const Q extends Query<T, {}>>(
+    type: T[],
+    query: Q & { customFields?: never },
+  ): Promise<Result<T, Q, {}>>;
+  async function customFetch<
+    T extends object,
+    const Q extends Query<T, C>,
+    const C extends CustomFieldMap<T>,
+  >(query: Q & { type: T[]; customFields: C }): Promise<Result<T, Q, C>>;
+  async function customFetch<
+    K extends keyof M,
+    T extends M[K] | object,
+    const Q extends Query<T, C>,
+    const C extends CustomFieldMap<T>,
+  >(query: Q & { type: T[] | K; customFields?: C }): Promise<Result<T, Q, C>> {
+    return await handler(query, cork);
   }
   return customFetch;
 }

package/lib/tools/defineGenericFetch.ts

@@ -0,0 +1,33 @@
+import type { CustomFieldMap, Handler, Key, Query, Result } from "../types";
+
+import { cork } from "./cork";
+
+export function defineGenericFetch<K extends string>(
+  handler: Handler<
+    Query<any, any> & { type: Key | any[]; customFields?: CustomFieldMap<any> },
+    any,
+    never,
+    never
+  >,
+) {
+  // FIXME: Until https://github.com/microsoft/TypeScript/issues/26242 gets resolved, the fetcher needs to be curried
+  function genericFetch<T extends object>() {
+    async function customFetch<const Q extends Query<T, {}>>(
+      query: Q & { type: K | T[]; customFields?: never },
+    ): Promise<Result<T, Q, {}>>;
+    async function customFetch<
+      const Q extends Query<T, C>,
+      const C extends CustomFieldMap<T>,
+    >(query: Q & { type: K | T[]; customFields: C }): Promise<Result<T, Q, C>>;
+    async function customFetch<
+      const Q extends Query<T, C>,
+      const C extends CustomFieldMap<T>,
+    >(
+      query: Q & { type: K | T[]; customFields?: C },
+    ): Promise<Result<T, Q, C>> {
+      return await handler(query, cork);
+    }
+    return customFetch;
+  }
+  return genericFetch;
+}

package/lib/tools/queryItemList.test.ts

@@ -63,7 +63,7 @@ test("queries lists of items", () => {
         { a: 2, c: "a" },
         { a: 3, c: "b" },
       ],
-      method: "get",
+      method: "read",
       multiple: true,
       context: {
         c: "a",
@@ -99,7 +99,7 @@ test("sorts items", () => {
         { a: 1, c: "b" },
       ],
       multiple: true,
-      orderBy: ["a", "c"],
+      order: ["a", "c"],
     }),
   ).toEqual([
     { a: 1, c: "a" },
@@ -118,7 +118,7 @@ test("sorts items", () => {
         { a: 1, c: "b" },
       ],
       multiple: true,
-      orderBy: [
+      order: [
         { field: "a", descending: true },
         { field: "c", descending: true },
       ],
@@ -176,7 +176,7 @@ test("slices items", () => {
         { a: 2, c: "a" },
         { a: 3, c: "b" },
       ],
-      method: "get",
+      method: "read",
       multiple: true,
       limit: 1,
     }),
@@ -188,7 +188,7 @@ test("slices items", () => {
         { a: 2, c: "a" },
         { a: 3, c: "b" },
       ],
-      method: "get",
+      method: "read",
       multiple: true,
       context: {
         c: "a",
@@ -204,7 +204,7 @@ test("slices items", () => {
         { a: 3, c: "b" },
         { a: 2, c: "b" },
       ],
-      method: "get",
+      method: "read",
       multiple: true,
       offset: 1,
       limit: 2,

package/lib/tools/queryItemList.ts

@@ -43,11 +43,11 @@ export function queryItemList<T extends object, C extends CustomFieldMap<T>>(
 ) {
   const data = query.type as T[];
   switch (query.method) {
-    case "get":
+    case "read":
     case undefined: {
       const { filter, context } = query;
       if (query.multiple) {
-        const { offset = 0, limit = Infinity, orderBy } = query;
+        const { offset = 0, limit = Infinity, order } = query;
         // Filter
         let result = data;
         if (context !== undefined || filter !== undefined) {
@@ -59,7 +59,7 @@ export function queryItemList<T extends object, C extends CustomFieldMap<T>>(
         }
         // Sort
         result = sortItemList(
-          orderBy as Order<T>[],
+          order as Order<T>[],
           result === data ? [...data] : result,
         );
         // Slice

package/lib/tools/sortItemList.ts

@@ -16,10 +16,10 @@ export function sortItemList<T extends object>(
   if (orderList === undefined || orderList.length === 0) {
     return value;
   }
-  const normalizedOrderBy = orderList.map(normalizeOrder);
+  const normalizedorder = orderList.map(normalizeOrder);
   return value.sort((a, b) => {
-    for (let index = 0; index < normalizedOrderBy.length; index++) {
-      const { field, descending } = normalizedOrderBy[index];
+    for (let index = 0; index < normalizedorder.length; index++) {
+      const { field, descending } = normalizedorder[index];
       if (a[field] === b[field]) {
         continue;
       }

package/lib/tools.ts

@@ -1,9 +1,10 @@
 // File automatically generated by `vite-plugin-module-list`
-export { defineCheckQuery } from "./tools/defineCheckQuery";
-export { defineCustomFetch } from "./tools/defineCustomFetch";
-export { filterFromContext } from "./tools/filterFromContext";
-export { filterItem } from "./tools/filterItem";
-export { impasse } from "./tools/impasse";
-export { normalizeOrder } from "./tools/normalizeOrder";
-export { queryItemList } from "./tools/queryItemList";
-export { sortItemList } from "./tools/sortItemList";
+export { cork } from "./tools/cork.js";
+export { defineCheckQuery } from "./tools/defineCheckQuery.js";
+export { defineCustomFetch } from "./tools/defineCustomFetch.js";
+export { defineGenericFetch } from "./tools/defineGenericFetch.js";
+export { filterFromContext } from "./tools/filterFromContext.js";
+export { filterItem } from "./tools/filterItem.js";
+export { normalizeOrder } from "./tools/normalizeOrder.js";
+export { queryItemList } from "./tools/queryItemList.js";
+export { sortItemList } from "./tools/sortItemList.js";

package/lib/types/AggregateFunction.ts

@@ -0,0 +1,17 @@
+/**
+ * Aggregation function.
+ */
+export type AggregateFunction<T extends object> =
+  | "length"
+  | { operator: "length" }
+  | {
+      operator:
+        | "median"
+        | "standardDeviation"
+        | "mean"
+        | "minimum"
+        | "maximum"
+        | "variance"
+        | "mode";
+      field: keyof T;
+    };

package/lib/types/AggregateFunctionOperator.ts

@@ -0,0 +1,6 @@
+import type { AggregateFunction } from "./AggregateFunction";
+
+export type AggregateFunctionOperator = Exclude<
+  AggregateFunction<{}>,
+  string
+>["operator"];

package/lib/types/Any.ts

@@ -0,0 +1,10 @@
+export type Any =
+  | boolean
+  | string
+  | number
+  | object
+  | symbol
+  | null
+  | undefined
+  | Array<any>
+  | ((...args: any[]) => any);

package/lib/types/Context.ts

@@ -0,0 +1,3 @@
+export type Context<T extends object> = {
+  [K in keyof T]?: T[K];
+};

package/lib/types/CustomFieldAggregateMap.ts

@@ -0,0 +1,6 @@
+import type { AggregateFunction } from "./AggregateFunction";
+
+export type CustomFieldAggregateMap<T extends object> = Record<
+  string,
+  AggregateFunction<T>
+>;

package/lib/types/CustomFieldMap.ts

@@ -0,0 +1,3 @@
+import type { FieldFunction } from "./FieldFunction";
+
+export type CustomFieldMap<T extends object> = Record<string, FieldFunction<T>>;

package/lib/types/CustomRequest.ts

@@ -0,0 +1,21 @@
+import type { CustomFieldMap } from "./CustomFieldMap";
+import type { Query } from "./Query";
+
+export type CustomRequest<
+  T extends object,
+  Q extends Query<T, C>,
+  C extends CustomFieldMap<T>,
+> = {
+  /**
+   * Entity being queried.
+   */
+  data: T;
+  /**
+   * Query.
+   */
+  query: Q;
+  /**
+   * Abort signal to abort the request.
+   */
+  signal?: AbortSignal;
+};

package/lib/types/FieldFunction.ts

@@ -0,0 +1,6 @@
+import type { FieldFunctionCustom } from "./FieldFunctionCustom";
+import type { FieldFunctionFormatDate } from "./FieldFunctionFormatDate";
+
+export type FieldFunction<T extends object> =
+  | FieldFunctionCustom<T>
+  | FieldFunctionFormatDate<T>;

package/lib/types/FieldFunctionCustom.ts

@@ -0,0 +1,7 @@
+/**
+ * Applies a custom field transform function.
+ */
+export type FieldFunctionCustom<T extends object> = {
+  operator: "custom";
+  value: (item: T) => any;
+};

package/lib/types/FieldFunctionFormatDate.ts

@@ -0,0 +1,10 @@
+import type { FilterKeys } from "./FilterKeys";
+
+/**
+ * Formats the date found in a given field, which can be an ISO string date or a timestamp.
+ */
+export type FieldFunctionFormatDate<T extends object> = {
+  operator: "formatDate";
+  field: FilterKeys<T, string | number>;
+  format: string;
+};

package/lib/types/FieldFunctionReturn.ts

@@ -0,0 +1,6 @@
+/**
+ * Return types of custom field functions.
+ */
+export type FieldFunctionReturn = {
+  formatDate: string;
+};

package/lib/types/Filter.ts

@@ -0,0 +1,20 @@
+import type { FilterArray } from "./FilterArray";
+import type { FilterBoolean } from "./FilterBoolean";
+import type { FilterField } from "./FilterField";
+import type { FilterNumber } from "./FilterNumber";
+import type { FilterSequence } from "./FilterSequence";
+import type { FilterString } from "./FilterString";
+import type { FilterStringIntersect } from "./FilterStringIntersect";
+import type { FilterStringMatch } from "./FilterStringMatch";
+/**
+ * Describes a predicate for filtering items.
+ */
+export type Filter<T extends object> =
+  | FilterSequence<T>
+  | FilterField<T>
+  | FilterBoolean<T>
+  | FilterString<T>
+  | FilterStringMatch<T>
+  | FilterStringIntersect<T>
+  | FilterNumber<T>
+  | FilterArray<T>;

package/lib/types/FilterArray.ts

@@ -0,0 +1,11 @@
+import type { Any } from "./Any";
+import type { FilterKeys } from "./FilterKeys";
+
+/**
+ * Checks if a given array field matches a given array value according to a given operator.
+ */
+export type FilterArray<T extends object, P = Any> = {
+  operator: "equal" | "include" | "intersect";
+  field: FilterKeys<T, P[]>;
+  value: P[];
+};

package/lib/types/FilterBoolean.ts

@@ -0,0 +1,10 @@
+import type { FilterKeys } from "./FilterKeys";
+
+/**
+ * Checks if a given boolean field is `true` or `false`.
+ */
+export type FilterBoolean<T extends object> = {
+  operator: "equal" | "notEqual";
+  field: FilterKeys<T, boolean>;
+  value: boolean;
+};

package/lib/types/FilterField.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if a given field exists.
+ */
+export type FilterField<T extends object> = {
+  operator: "exist";
+  field: keyof T;
+};

package/lib/types/FilterKeys.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns object type with field extending the provided `P` type.
+ */
+export type FilterKeys<T extends object, P> = {
+  [K in keyof T]-?: T[K] extends P ? K : never;
+}[keyof T];

package/lib/types/FilterNumber.ts

@@ -0,0 +1,16 @@
+import type { FilterKeys } from "./FilterKeys";
+
+/**
+ * Checks if a given number field matches a given number value according to a given operator.
+ */
+export type FilterNumber<T extends object> = {
+  operator:
+    | "equal"
+    | "notEqual"
+    | "greaterThan"
+    | "greaterThanOrEqual"
+    | "lowerThan"
+    | "lowerThanOrEqual";
+  field: FilterKeys<T, number>;
+  value: number;
+};

package/lib/types/FilterOperator.ts

@@ -0,0 +1,3 @@
+import type { Filter } from "./Filter";
+
+export type FilterOperator = Filter<never>["operator"];

package/lib/types/FilterSequence.ts

@@ -0,0 +1,26 @@
+import type { Filter } from "./Filter";
+
+/**
+ * Joins a list of filters with a specific boolean operator.
+ */
+export type FilterSequence<T extends object> =
+  | {
+      /**
+       * Boolean operator to use for joining the filters.
+       */
+      operator: "all";
+      /**
+       * Filters to join.
+       */
+      value: Filter<T>[];
+    }
+  | {
+      /**
+       * Boolean operator to use for joining the filters.
+       */
+      operator: "any" | "none";
+      /**
+       * Filters to join.
+       */
+      value?: Filter<T>[];
+    };