quetch 0.1.0

package/lib/errors/RequestError.ts

@@ -0,0 +1,16 @@
+import type { AnyQuery } 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.
+ */
+export class RequestError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public query?: AnyQuery,
+    public request?: Request,
+    public response?: Response,
+  ) {
+    super(message);
+  }
+}

package/lib/errors.ts

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

package/lib/main.ts

@@ -0,0 +1,4 @@
+export type * from "./types";
+
+export * from "./tools";
+export * from "./middlewares";

package/lib/middlewares/aggregate.ts

@@ -0,0 +1,113 @@
+import { sleep } from "futurise";
+
+import { RequestError } from "../errors";
+import type { AnyQuery, Handler } from "../types";
+
+/**
+ * Aggregates multiple incoming query calls into one query.
+ * Queries are grouped according to the string key returned by `queryGroupId(query)`. Inside a group, each query is identified with `queryId(query)`.
+ * The aggregated query is built from the object returned by `queryForGroup(queryList, groupId)`, after at least `delay` milliseconds after the first non-aggregated aggregatable query call.
+ * When the aggregated query resolves, the result is dispatched back to each aggregatable query call of the category by dispatching the result for each query returned by `resultForQuery(result, query)`.
+ * If a query occurs twice, `mergeQuery(query, currentQuery)` is called and the output replaces the previous query.
+ *
+ * @param options
+ * @returns
+ */
+export function aggregate<I extends AnyQuery, O, In extends AnyQuery, On>({
+  queryGroupId = ({ type, method = "get" }) => {
+    if (method !== "get") {
+      return undefined;
+    }
+    if (typeof type !== "string") {
+      return undefined;
+    }
+    return type;
+  },
+  queryId = ({ context = {} }) => {
+    if (context.id === undefined) {
+      return undefined;
+    }
+    return `${context.id}`;
+  },
+  mergeQuery = (query, _currentQuery) => query,
+  delay = 200,
+  queryForGroup = (queryList, _): AnyQuery => ({
+    type: queryList[0].type,
+    method: "get",
+    multiple: true,
+    filter: {
+      operator: "include",
+      field: "id",
+      value: queryList.map((query) => query.context!.id),
+    },
+  }),
+  resultForQuery = (resultList, query) => {
+    const result = resultList.find(
+      (result) => (result as any).id === query.context!.id,
+    );
+    if (result === undefined) {
+      throw new RequestError("Not found", 404, query);
+    }
+    return result;
+  },
+}: {
+  queryGroupId?: (query: I) => string | undefined;
+  queryId?: (query: I) => string | undefined;
+  mergeQuery?: (query: I, currentQuery: I) => I;
+  delay?: number;
+  queryForGroup: (queryList: I[], group: string) => AnyQuery;
+  resultForQuery: (resultList: O[], query: I) => O | never;
+}): Handler<I, O, In, On> {
+  const queryGroupMap = new Map<
+    string,
+    {
+      groupRequest: Promise<On>;
+      requestMap: Map<string, Promise<O>>;
+      queryMap: Map<string, I>;
+    }
+  >();
+  return ((query, next) => {
+    const groupId = queryGroupId(query);
+    if (!groupId) {
+      return next(query as unknown as In);
+    }
+    const id = queryId(query);
+    if (!id) {
+      return next(query as unknown as In);
+    }
+    if (!queryGroupMap.has(groupId)) {
+      const queryMap = new Map<string, I>();
+      queryGroupMap.set(groupId, {
+        groupRequest: (async () => {
+          await sleep(delay);
+          queryGroupMap.delete(groupId);
+          return queryMap.size === 1
+            ? next(queryMap.values().next().value as unknown as In)
+            : next(
+                queryForGroup([...queryMap.values()], groupId) as unknown as In,
+              );
+        })(),
+        requestMap: new Map(),
+        queryMap,
+      });
+    }
+    const { groupRequest, requestMap, queryMap } = queryGroupMap.get(groupId)!;
+    if (requestMap.has(id)) {
+      const currentQuery = queryMap.get(id)!;
+      const mergedQuery = mergeQuery(query, currentQuery);
+      if (mergedQuery !== currentQuery) {
+        queryMap.set(id, mergedQuery);
+      }
+      return requestMap.get(id);
+    }
+    queryMap.set(id, query);
+    const request = (async () => {
+      const result = await groupRequest;
+      return queryMap.size === 1
+        ? (result as O)
+        : resultForQuery(result as O[], query);
+    })();
+    requestMap.set(id, request);
+    return request;
+  }) as Handler<I, O, In, On>;
+}

package/lib/middlewares/branch.ts

@@ -0,0 +1,27 @@
+import type { Handler } from "../types";
+
+import { identity } from "./identity";
+
+/**
+ *  Dispatches an incoming query to `left` if `condition(query)` returns a truthy value, `right` otherwise. This is helpful for sending queries to different resolvers.
+ *
+ * @example
+ * ```typescript
+ * const customFetch = combine(
+ *   branch(query => query.protocol === 'gql', gqlHandlers),
+ *   restHandlers,
+ * )
+ * ```
+ *
+ * @param condition
+ * @param left
+ * @param right
+ * @returns
+ */
+export function branch<I, O, In, On>(
+  condition: (input: I) => boolean,
+  left: Handler<I, O, In, On>,
+  right: Handler<I, O, In, On> = identity as Handler<I, O, In, On>,
+): Handler<I, O, In, On> {
+  return (input, next) => (condition(input) ? left : right)(input, next);
+}

package/lib/middlewares/cache.ts

@@ -0,0 +1,89 @@
+import type { AnyQueryExternal, Handler, Store } from "../types";
+
+type CachedItem<I extends AnyQueryExternal> = {
+  query: I;
+  value: any;
+};
+
+type CacheOptions<I extends AnyQueryExternal> = {
+  /**
+   * Unique identifier for the item to cache.
+   * Returns `undefined` if the item should not be cached.
+   */
+  itemId?: (query: I) => string | undefined;
+  /**
+   * Cache store.
+   */
+  store: Store<CachedItem<I>>;
+  /**
+   * Returns `true` if the cached item must be invalidated.
+   */
+  invalidatesItem: (query: I, cachedQuery: I, cachedValue: any) => boolean;
+  /**
+   * Returns a query that completes the cached value.
+   * Returns `undefined` if the query should not be completed.
+   */
+  extendCachedQuery: (query: I, cachedQuery: I) => I | undefined;
+  /**
+   * Merges the extended query with the cached query.
+   * Only called when `extendCachedQuery` returns a query.
+   */
+  mergeQuery: (extendedQuery: I, cachedQuery: I) => I;
+  /**
+   * Merges the value from the extended query with the cached value.
+   * Only called when `extendCachedQuery` returns a query.
+   */
+  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}`;
+    }
+    return undefined;
+  },
+  store,
+  invalidatesItem,
+  extendCachedQuery,
+  mergeQuery,
+  mergeItem,
+}: CacheOptions<I>): Handler<I, O, In, On> {
+  /*
+  Caches the result of a query if `serialize` returns a non-empty string key. The `engine` should follow the `Map` API. Elements are kept in the cache until the `duration` in milliseconds expires.
+  Note that a `duration` set to `Infinity` indefinitely keeps items in the cache.
+  */
+  return async (query, next) => {
+    const id = itemId(query);
+    if (!id) {
+      return next(query as unknown as In);
+    }
+    if (await store.has(id)) {
+      const { query: cachedQuery, value: cachedValue } = await store.get(id);
+      if (invalidatesItem(query, cachedQuery, cachedValue)) {
+        const value = await next(query as unknown as In);
+        store.set(id, { query, value });
+        return value;
+      }
+      const extendedQuery = extendCachedQuery(query, cachedQuery);
+      if (extendedQuery === undefined) {
+        return cachedValue;
+      }
+      const value = await next(extendedQuery as unknown as In);
+      const extendedValue = mergeItem(value, cachedValue, query, cachedQuery);
+      store.set(id, {
+        query: mergeQuery(extendedQuery, cachedQuery),
+        value: extendedValue,
+      });
+      return extendedValue;
+    }
+    const value = await next(query as unknown as In);
+    store.set(id, { query, value });
+    return value;
+  };
+}