@vinicunca/perkakas 1.7.1 → 1.8.0

package/dist/from-keys-BYHfvCLR.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-keys-BYHfvCLR.d.ts","names":[],"sources":["../src/from-keys.ts"],"sourcesContent":[],"mappings":";;;;;KAUK,sBAAsB,UAAU,sBAAsB,IAAI,GANc,GAMxE,KAAA;KAEA,QAFa,CAAA,UAEM,iBAFN,EAAA,CAAA,CAAA,GAE8B,CAF9B,SAAA,SAAA,EAAA,GAAA,CAAA,CAAA,GAKd,CALc,SAAA,SAAA,CAAA,KAAA,KAAA,EAAA,GAAA,KAAA,KAAA,CAAA,GAMZ,aANY,CAME,IANF,EAMQ,CANR,CAAA,GAMa,QANb,CAMsB,IANtB,EAM4B,CAN5B,CAAA,GAOZ,CAPY,CAAA,MAAA,CAAA,SAOM,WAPN,GAQV,cARU,CAQK,MARL,CAQY,CARZ,CAAA,MAAA,CAAA,EAQuB,CARvB,CAAA,CAAA,GAAA,KAAA;;;;;;AAA8C;;;;;;;;;;;;;;;;;;AAoChE;;AAAqD,iBAArC,QAAqC,CAAA,UAAlB,iBAAkB,CAAA,WAAA,CAAA,EAAA,CAAA,CAAA,CAAA,IAAA,EAC7C,CAD6C,EAAA,MAAA,EAAA,CAAA,IAAA,EAEpC,CAFoC,CAAA,MAAA,CAAA,EAAA,KAAA,EAAA,MAAA,EAAA,IAAA,EAEJ,CAFI,EAAA,GAEE,CAFF,CAAA,EAGlD,QAHkD,CAGzC,QAHyC,CAGhC,CAHgC,EAG7B,CAH6B,CAAA,CAAA;;;;;;;;;;;AA4BrD;;;;;;;;;;;;;iBAAgB,mBAAmB,kBAAkB,gCACpC,gCAAgC,MAAM,WAC7C,MAAM,SAAS,SAAS,GAAG"}

package/dist/from-keys-CI2PJlIM.cjs

@@ -0,0 +1 @@
+const e=require(`./curry-BPVIsvo3.cjs`);function t(...t){return e.curry(n,t)}function n(e,t){let n={};for(let[r,i]of e.entries())n[i]=t(i,r,e);return n}Object.defineProperty(exports,`fromKeys`,{enumerable:!0,get:function(){return t}});

package/dist/from-keys-DJe8xU7b.js

@@ -0,0 +1,2 @@
+import{curry as e}from"./curry-CzZjDrpv.js";function t(...t){return e(n,t)}function n(e,t){let n={};for(let[r,i]of e.entries())n[i]=t(i,r,e);return n}export{t as fromKeys};
+//# sourceMappingURL=from-keys-DJe8xU7b.js.map

package/dist/from-keys-DJe8xU7b.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-keys-DJe8xU7b.js","names":["result: Partial<FromKeys<T, V>>"],"sources":["../src/from-keys.ts"],"sourcesContent":["import type { Simplify } from 'type-fest';\n\nimport type { BoundedPartial } from './internal/types/bounded-partial';\n\nimport type { IterableContainer } from './internal/types/iterable-container';\nimport { curry } from './curry';\n\n// Takes a union of literals and creates a union of records with the value V for\n// each key **separately**\n// @example ExactlyOneKey<\"cat\" | \"dog\", boolean> // { cat: boolean } | { dog: boolean }\ntype ExactlyOneKey<T, V> = T extends PropertyKey ? { [P in T]: V } : never;\n\ntype FromKeys<T extends IterableContainer, V> = T extends readonly []\n  // eslint-disable-next-line ts/no-empty-object-type -- We want to return an empty object type here, but it's not trivial to build that in Typescript, other fixer suggestions like Record<PropertyKey, never> or Record<PropertyKey, unknown> both break our type tests so they don't do what we need here. Because the result is mutable this might be the correct type after all...\n  ? {}\n  : T extends readonly [infer Head, ...infer Rest]\n    ? ExactlyOneKey<Head, V> & FromKeys<Rest, V>\n    : T[number] extends PropertyKey\n      ? BoundedPartial<Record<T[number], V>>\n      : never;\n\n/**\n * Creates an object that maps each key in `data` to the result of `mapper` for\n * that key. Duplicate keys are overwritten, guaranteeing that `mapper` is run\n * for each item in `data`.\n *\n * There are several other functions that could be used to build an object from\n * an array:\n * `indexBy` - Builds an object from an array of *values* and a mapper for keys.\n * `pullObject` - Builds an object from an array of items with mappers for *both* keys and values.\n * `fromEntries` - Builds an object from an array of key-value pairs.\n * `mapToObj` - Builds an object from an array of items and a single mapper for key-value pairs.\n * Refer to the docs for more details.\n *\n * @param data - An array of keys of the output object. All items in the array\n * would be keys in the output array.\n * @param mapper - Takes a key and returns the value that would be associated\n * with that key.\n * @signature\n *   P.fromKeys(data, mapper);\n * @example\n *   P.fromKeys([\"cat\", \"dog\"], P.length()); // { cat: 3, dog: 3 } (typed as Partial<Record<\"cat\" | \"dog\", number>>)\n *   P.fromKeys([1, 2], P.add(1)); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)\n * @dataFirst\n * @category Object\n */\nexport function fromKeys<T extends IterableContainer<PropertyKey>, V>(\n  data: T,\n  mapper: (item: T[number], index: number, data: T) => V,\n): Simplify<FromKeys<T, V>>;\n\n/**\n * Creates an object that maps each key in `data` to the result of `mapper` for\n * that key. Duplicate keys are overwritten, guaranteeing that `mapper` is run\n * for each item in `data`.\n *\n * There are several other functions that could be used to build an object from\n * an array:\n * `indexBy` - Builds an object from an array of *values* and a mapper for keys.\n * `pullObject` - Builds an object from an array of items with mappers for *both* keys and values.\n * `fromEntries` - Builds an object from an array of key-value pairs.\n * `mapToObj` - Builds an object from an array of items and a single mapper for key-value pairs.\n * Refer to the docs for more details.\n *\n * @param mapper - Takes a key and returns the value that would be associated\n * with that key.\n * @signature\n *   P.fromKeys(mapper)(data);\n * @example\n *   P.pipe([\"cat\", \"dog\"], P.fromKeys(P.length())); // { cat: 3, dog: 3 } (typed as Partial<Record<\"cat\" | \"dog\", number>>)\n *   P.pipe([1, 2], P.fromKeys(P.add(1))); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)\n * @dataLast\n * @category Object\n */\nexport function fromKeys<T extends IterableContainer<PropertyKey>, V>(\n  mapper: (item: T[number], index: number, data: T) => V,\n): (data: T) => Simplify<FromKeys<T, V>>;\n\nexport function fromKeys(...args: ReadonlyArray<unknown>): unknown {\n  return curry(fromKeysImplementation, args);\n}\n\nfunction fromKeysImplementation<T extends IterableContainer<PropertyKey>, V>(\n  data: T,\n  mapper: (item: T[number], index: number, data: T) => V,\n): FromKeys<T, V> {\n  const result: Partial<FromKeys<T, V>> = {};\n\n  for (const [index, key] of data.entries()) {\n    // @ts-expect-error [ts7053] - There's no easy way to make Typescript aware that the items in T would be keys in the output object because it's type is built recursively and the \"being an item of an array\" property of a type is not \"carried over\" in the recursive type definition.\n    result[key] = mapper(key, index, data);\n  }\n\n  return result as FromKeys<T, V>;\n}\n"],"mappings":"4CA8EA,SAAgB,EAAS,GAAG,EAAuC,CACjE,OAAO,EAAM,EAAwB,EAAK,CAG5C,SAAS,EACP,EACA,EACgB,CAChB,IAAMA,EAAkC,EAAE,CAE1C,IAAK,GAAM,CAAC,EAAO,KAAQ,EAAK,SAAS,CAEvC,EAAO,GAAO,EAAO,EAAK,EAAO,EAAK,CAGxC,OAAO"}

package/dist/from-keys-Ds1mndVk.d.cts

@@ -0,0 +1,60 @@
+import { IterableContainer } from "./iterable-container-V5sa0V_H.cjs";
+import { BoundedPartial } from "./bounded-partial-A89bt7Kj.cjs";
+import { Simplify } from "type-fest";
+
+//#region src/from-keys.d.ts
+type ExactlyOneKey<T, V> = T extends PropertyKey ? { [P in T]: V } : never;
+type FromKeys<T extends IterableContainer, V> = T extends readonly [] ? {} : T extends readonly [infer Head, ...infer Rest] ? ExactlyOneKey<Head, V> & FromKeys<Rest, V> : T[number] extends PropertyKey ? BoundedPartial<Record<T[number], V>> : never;
+/**
+ * Creates an object that maps each key in `data` to the result of `mapper` for
+ * that key. Duplicate keys are overwritten, guaranteeing that `mapper` is run
+ * for each item in `data`.
+ *
+ * There are several other functions that could be used to build an object from
+ * an array:
+ * `indexBy` - Builds an object from an array of *values* and a mapper for keys.
+ * `pullObject` - Builds an object from an array of items with mappers for *both* keys and values.
+ * `fromEntries` - Builds an object from an array of key-value pairs.
+ * `mapToObj` - Builds an object from an array of items and a single mapper for key-value pairs.
+ * Refer to the docs for more details.
+ *
+ * @param data - An array of keys of the output object. All items in the array
+ * would be keys in the output array.
+ * @param mapper - Takes a key and returns the value that would be associated
+ * with that key.
+ * @signature
+ *   P.fromKeys(data, mapper);
+ * @example
+ *   P.fromKeys(["cat", "dog"], P.length()); // { cat: 3, dog: 3 } (typed as Partial<Record<"cat" | "dog", number>>)
+ *   P.fromKeys([1, 2], P.add(1)); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)
+ * @dataFirst
+ * @category Object
+ */
+declare function fromKeys<T extends IterableContainer<PropertyKey>, V>(data: T, mapper: (item: T[number], index: number, data: T) => V): Simplify<FromKeys<T, V>>;
+/**
+ * Creates an object that maps each key in `data` to the result of `mapper` for
+ * that key. Duplicate keys are overwritten, guaranteeing that `mapper` is run
+ * for each item in `data`.
+ *
+ * There are several other functions that could be used to build an object from
+ * an array:
+ * `indexBy` - Builds an object from an array of *values* and a mapper for keys.
+ * `pullObject` - Builds an object from an array of items with mappers for *both* keys and values.
+ * `fromEntries` - Builds an object from an array of key-value pairs.
+ * `mapToObj` - Builds an object from an array of items and a single mapper for key-value pairs.
+ * Refer to the docs for more details.
+ *
+ * @param mapper - Takes a key and returns the value that would be associated
+ * with that key.
+ * @signature
+ *   P.fromKeys(mapper)(data);
+ * @example
+ *   P.pipe(["cat", "dog"], P.fromKeys(P.length())); // { cat: 3, dog: 3 } (typed as Partial<Record<"cat" | "dog", number>>)
+ *   P.pipe([1, 2], P.fromKeys(P.add(1))); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)
+ * @dataLast
+ * @category Object
+ */
+declare function fromKeys<T extends IterableContainer<PropertyKey>, V>(mapper: (item: T[number], index: number, data: T) => V): (data: T) => Simplify<FromKeys<T, V>>;
+//#endregion
+export { fromKeys };
+//# sourceMappingURL=from-keys-Ds1mndVk.d.cts.map

package/dist/from-keys-Ds1mndVk.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-keys-Ds1mndVk.d.cts","names":[],"sources":["../src/from-keys.ts"],"sourcesContent":[],"mappings":";;;;;KAUK,sBAAsB,UAAU,sBAAsB,IAAI,GANc,GAMxE,KAAA;KAEA,QAFa,CAAA,UAEM,iBAFN,EAAA,CAAA,CAAA,GAE8B,CAF9B,SAAA,SAAA,EAAA,GAAA,CAAA,CAAA,GAKd,CALc,SAAA,SAAA,CAAA,KAAA,KAAA,EAAA,GAAA,KAAA,KAAA,CAAA,GAMZ,aANY,CAME,IANF,EAMQ,CANR,CAAA,GAMa,QANb,CAMsB,IANtB,EAM4B,CAN5B,CAAA,GAOZ,CAPY,CAAA,MAAA,CAAA,SAOM,WAPN,GAQV,cARU,CAQK,MARL,CAQY,CARZ,CAAA,MAAA,CAAA,EAQuB,CARvB,CAAA,CAAA,GAAA,KAAA;;;;;;AAA8C;;;;;;;;;;;;;;;;;;AAoChE;;AAAqD,iBAArC,QAAqC,CAAA,UAAlB,iBAAkB,CAAA,WAAA,CAAA,EAAA,CAAA,CAAA,CAAA,IAAA,EAC7C,CAD6C,EAAA,MAAA,EAAA,CAAA,IAAA,EAEpC,CAFoC,CAAA,MAAA,CAAA,EAAA,KAAA,EAAA,MAAA,EAAA,IAAA,EAEJ,CAFI,EAAA,GAEE,CAFF,CAAA,EAGlD,QAHkD,CAGzC,QAHyC,CAGhC,CAHgC,EAG7B,CAH6B,CAAA,CAAA;;;;;;;;;;;AA4BrD;;;;;;;;;;;;;iBAAgB,mBAAmB,kBAAkB,gCACpC,gCAAgC,MAAM,WAC7C,MAAM,SAAS,SAAS,GAAG"}

package/dist/from-keys.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkBEMQAYI5cjs = require('./chunk-BEMQAYI5.cjs');require('./chunk-XR72I63W.cjs');require('./chunk-GZJMERDJ.cjs');require('./chunk-MBGSSEZN.cjs');exports.fromKeys = _chunkBEMQAYI5cjs.a;
+require(`./lazy-data-last-impl-3PAFkslW.cjs`),require(`./curry-BPVIsvo3.cjs`);const e=require(`./from-keys-CI2PJlIM.cjs`);exports.fromKeys=e.fromKeys;

package/dist/from-keys.d.cts

@@ -1,61 +1,5 @@
-import { Simplify } from 'type-fest';
-import { B as BoundedPartial } from './bounded-partial-BhnecV3P.cjs';
-import { I as IterableContainer } from './iterable-container-BTpDVdNc.cjs';
-import './is-bounded-record-C9WAwfA8.cjs';
-
-type ExactlyOneKey<T, V> = T extends PropertyKey ? {
-    [P in T]: V;
-} : never;
-type FromKeys<T extends IterableContainer, V> = T extends readonly [] ? {} : T extends readonly [infer Head, ...infer Rest] ? ExactlyOneKey<Head, V> & FromKeys<Rest, V> : T[number] extends PropertyKey ? BoundedPartial<Record<T[number], V>> : never;
-/**
- * Creates an object that maps each key in `data` to the result of `mapper` for
- * that key. Duplicate keys are overwritten, guaranteeing that `mapper` is run
- * for each item in `data`.
- *
- * There are several other functions that could be used to build an object from
- * an array:
- * `indexBy` - Builds an object from an array of *values* and a mapper for keys.
- * `pullObject` - Builds an object from an array of items with mappers for *both* keys and values.
- * `fromEntries` - Builds an object from an array of key-value pairs.
- * `mapToObj` - Builds an object from an array of items and a single mapper for key-value pairs.
- * Refer to the docs for more details.
- *
- * @param data - An array of keys of the output object. All items in the array
- * would be keys in the output array.
- * @param mapper - Takes a key and returns the value that would be associated
- * with that key.
- * @signature
- *   P.fromKeys(data, mapper);
- * @example
- *   P.fromKeys(["cat", "dog"], P.length()); // { cat: 3, dog: 3 } (typed as Partial<Record<"cat" | "dog", number>>)
- *   P.fromKeys([1, 2], P.add(1)); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)
- * @dataFirst
- * @category Object
- */
-declare function fromKeys<T extends IterableContainer<PropertyKey>, V>(data: T, mapper: (item: T[number], index: number, data: T) => V): Simplify<FromKeys<T, V>>;
-/**
- * Creates an object that maps each key in `data` to the result of `mapper` for
- * that key. Duplicate keys are overwritten, guaranteeing that `mapper` is run
- * for each item in `data`.
- *
- * There are several other functions that could be used to build an object from
- * an array:
- * `indexBy` - Builds an object from an array of *values* and a mapper for keys.
- * `pullObject` - Builds an object from an array of items with mappers for *both* keys and values.
- * `fromEntries` - Builds an object from an array of key-value pairs.
- * `mapToObj` - Builds an object from an array of items and a single mapper for key-value pairs.
- * Refer to the docs for more details.
- *
- * @param mapper - Takes a key and returns the value that would be associated
- * with that key.
- * @signature
- *   P.fromKeys(mapper)(data);
- * @example
- *   P.pipe(["cat", "dog"], P.fromKeys(P.length())); // { cat: 3, dog: 3 } (typed as Partial<Record<"cat" | "dog", number>>)
- *   P.pipe([1, 2], P.fromKeys(P.add(1))); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)
- * @dataLast
- * @category Object
- */
-declare function fromKeys<T extends IterableContainer<PropertyKey>, V>(mapper: (item: T[number], index: number, data: T) => V): (data: T) => Simplify<FromKeys<T, V>>;
-
-export { fromKeys };
+import "./iterable-container-V5sa0V_H.cjs";
+import "./is-bounded-record-kpsb1wQA.cjs";
+import "./bounded-partial-A89bt7Kj.cjs";
+import { fromKeys } from "./from-keys-Ds1mndVk.cjs";
+export { fromKeys };

package/dist/from-keys.d.ts

@@ -1,61 +1,5 @@
-import { Simplify } from 'type-fest';
-import { B as BoundedPartial } from './bounded-partial-B15MLSAS.js';
-import { I as IterableContainer } from './iterable-container-BTpDVdNc.js';
-import './is-bounded-record-C9WAwfA8.js';
-
-type ExactlyOneKey<T, V> = T extends PropertyKey ? {
-    [P in T]: V;
-} : never;
-type FromKeys<T extends IterableContainer, V> = T extends readonly [] ? {} : T extends readonly [infer Head, ...infer Rest] ? ExactlyOneKey<Head, V> & FromKeys<Rest, V> : T[number] extends PropertyKey ? BoundedPartial<Record<T[number], V>> : never;
-/**
- * Creates an object that maps each key in `data` to the result of `mapper` for
- * that key. Duplicate keys are overwritten, guaranteeing that `mapper` is run
- * for each item in `data`.
- *
- * There are several other functions that could be used to build an object from
- * an array:
- * `indexBy` - Builds an object from an array of *values* and a mapper for keys.
- * `pullObject` - Builds an object from an array of items with mappers for *both* keys and values.
- * `fromEntries` - Builds an object from an array of key-value pairs.
- * `mapToObj` - Builds an object from an array of items and a single mapper for key-value pairs.
- * Refer to the docs for more details.
- *
- * @param data - An array of keys of the output object. All items in the array
- * would be keys in the output array.
- * @param mapper - Takes a key and returns the value that would be associated
- * with that key.
- * @signature
- *   P.fromKeys(data, mapper);
- * @example
- *   P.fromKeys(["cat", "dog"], P.length()); // { cat: 3, dog: 3 } (typed as Partial<Record<"cat" | "dog", number>>)
- *   P.fromKeys([1, 2], P.add(1)); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)
- * @dataFirst
- * @category Object
- */
-declare function fromKeys<T extends IterableContainer<PropertyKey>, V>(data: T, mapper: (item: T[number], index: number, data: T) => V): Simplify<FromKeys<T, V>>;
-/**
- * Creates an object that maps each key in `data` to the result of `mapper` for
- * that key. Duplicate keys are overwritten, guaranteeing that `mapper` is run
- * for each item in `data`.
- *
- * There are several other functions that could be used to build an object from
- * an array:
- * `indexBy` - Builds an object from an array of *values* and a mapper for keys.
- * `pullObject` - Builds an object from an array of items with mappers for *both* keys and values.
- * `fromEntries` - Builds an object from an array of key-value pairs.
- * `mapToObj` - Builds an object from an array of items and a single mapper for key-value pairs.
- * Refer to the docs for more details.
- *
- * @param mapper - Takes a key and returns the value that would be associated
- * with that key.
- * @signature
- *   P.fromKeys(mapper)(data);
- * @example
- *   P.pipe(["cat", "dog"], P.fromKeys(P.length())); // { cat: 3, dog: 3 } (typed as Partial<Record<"cat" | "dog", number>>)
- *   P.pipe([1, 2], P.fromKeys(P.add(1))); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)
- * @dataLast
- * @category Object
- */
-declare function fromKeys<T extends IterableContainer<PropertyKey>, V>(mapper: (item: T[number], index: number, data: T) => V): (data: T) => Simplify<FromKeys<T, V>>;
-
-export { fromKeys };
+import "./iterable-container-wtkYslN_.js";
+import "./is-bounded-record-DCEYRY41.js";
+import "./bounded-partial-TshEjJC1.js";
+import { fromKeys } from "./from-keys-BYHfvCLR.js";
+export { fromKeys };

package/dist/from-keys.js

@@ -1 +1 @@
-import{a}from"./chunk-TVMG2NYC.js";import"./chunk-J6WPJH72.js";import"./chunk-KGPDVVVV.js";import"./chunk-EK7ODJWE.js";export{a as fromKeys};
+import"./lazy-data-last-impl-7QfM1xXg.js";import"./curry-CzZjDrpv.js";import{fromKeys as e}from"./from-keys-DJe8xU7b.js";export{e as fromKeys};

package/dist/funnel-1FhwR-u9.d.ts

@@ -0,0 +1,155 @@
+import { RequireAtLeastOne } from "type-fest";
+
+//#region src/funnel.d.ts
+type FunnelOptions<Args extends RestArguments, R> = {
+  readonly reducer?: (accumulator: R | undefined, ...params: Args) => R;
+} & FunnelTimingOptions;
+/**
+ * Not all combinations of timing options are valid, there are dependencies
+ * between them to ensure users can't configure the funnel in a way which would
+ * cause it to never trigger.
+ */
+type FunnelTimingOptions = ({
+  readonly triggerAt?: 'end';
+} & (({
+  readonly minGapMs: number;
+} & RequireAtLeastOne<{
+  readonly minQuietPeriodMs: number;
+  readonly maxBurstDurationMs: number;
+}>) | {
+  readonly minQuietPeriodMs?: number;
+  readonly maxBurstDurationMs?: number;
+  readonly minGapMs?: never;
+})) | {
+  readonly triggerAt: 'start' | 'both';
+  readonly minQuietPeriodMs?: number;
+  readonly maxBurstDurationMs?: number;
+  readonly minGapMs?: number;
+};
+type RestArguments = Array<any>;
+interface Funnel<Args extends RestArguments = []> {
+  /**
+   * Call the function. This might result in the `execute` function being called
+   * now or later, depending on it's configuration and it's current state.
+   *
+   * @param args - The args are defined by the `reducer` function.
+   */
+  readonly call: (...args: Args) => void;
+  /**
+   * Resets the funnel to it's initial state. Any calls made since the last
+   * invocation will be discarded.
+   */
+  readonly cancel: () => void;
+  /**
+   * Triggers an invocation regardless of the current state of the funnel.
+   * Like any other invocation, The funnel will also be reset to it's initial
+   * state afterwards.
+   */
+  readonly flush: () => void;
+  /**
+   * The funnel is in it's initial state (there are no active timeouts).
+   */
+  readonly isIdle: boolean;
+}
+/**
+ * Creates a funnel that controls the timing and execution of `callback`. Its
+ * main purpose is to manage multiple consecutive (usually fast-paced) calls,
+ * reshaping them according to a defined batching strategy and timing policy.
+ * This is useful when handling uncontrolled call rates, such as DOM events or
+ * network traffic. It can implement strategies like debouncing, throttling,
+ * batching, and more.
+ *
+ * An optional `reducer` function can be provided to allow passing data to the
+ * callback via calls to `call` (otherwise the signature of `call` takes no
+ * arguments).
+ *
+ * Typing is inferred from `callback`s param, and from the rest params that
+ * the optional `reducer` function accepts. Use **explicit** types for these
+ * to ensure that everything _else_ is well-typed.
+ *
+ * Notice that this function constructs a funnel **object**, and does **not**
+ * execute anything when called. The returned object should be used to execute
+ * the funnel via the its `call` method.
+ *
+ * - Debouncing: use `minQuietPeriodMs` and any `triggerAt`.
+ * - Throttling: use `minGapMs` and `triggerAt: "start"` or `"both"`.
+ * - Batching: See the reference implementation in [`funnel.reference-batch.test.ts`](https://github.com/vinicunca/perkakas/blob/main/src/funnel.reference-batch.test.ts).
+ *
+ * @param callback - The main function that would be invoked periodically based
+ * on `options`. The function would take the latest result of the `reducer`; if
+ * no calls where made since the last time it was invoked it will not be
+ * invoked. (If a return value is needed, it should be passed via a reference or
+ * via closure to the outer scope of the funnel).
+ * @param options - An object that defines when `execute` should be invoked,
+ * relative to the calls of `call`. An empty/missing options object is
+ * equivalent to setting `minQuietPeriodMs` to `0`.
+ * @param options.reducer - Combines the arguments passed to `call` with the
+ * value computed on the previous call (or `undefined` on the first time). The
+ * goal of the function is to extract and summarize the data needed for
+ * `callback`. It should be fast and simple as it is called often and should
+ * defer heavy operations to the `execute` function. If the final value
+ * is `undefined`, `callback` will not be called.
+ * @param options.triggerAt - At what "edges" of the funnel's burst window
+ * would `execute` invoke:
+ * - `start` - the function will be invoked immediately (within the  **same**
+ * execution frame!), and any subsequent calls would be ignored until the funnel
+ * is idle again. During this period `reducer` will also not be called.
+ * - `end` - the function will **not** be invoked initially but the timer will
+ * be started. Any calls during this time would be passed to the reducer, and
+ * when the timers are done, the reduced result would trigger an invocation.
+ * - `both` - the function will be invoked immediately, and then the funnel
+ * would behave as if it was in the 'end' state. @default 'end'.
+ * @param options.minQuietPeriodMs - The burst timer prevents subsequent calls
+ * in short succession to cause excessive invocations (aka "debounce"). This
+ * duration represents the **minimum** amount of time that needs to pass
+ * between calls (the "quiet" part) in order for the subsequent call to **not**
+ * be considered part of the burst. In other words, as long as calls are faster
+ * than this, they are considered part of the burst and the burst is extended.
+ * @param options.maxBurstDurationMs - Bursts are extended every time a call is
+ * made within the burst period. This means that the burst period could be
+ * extended indefinitely. To prevent such cases, a maximum burst duration could
+ * be defined. When `minQuietPeriodMs` is not defined and this option is, they
+ * will both share the same value.
+ * @param options.minGapMs - A minimum duration between calls of `execute`.
+ * This is maintained regardless of the shape of the burst and is ensured even
+ * if the `maxBurstDurationMs` is reached before it. (aka "throttle").
+ * @returns A funnel with a `call` function that is used to trigger invocations.
+ * In addition to it the funnel also comes with the following functions and
+ * properties:
+ * - `cancel` - Resets the funnel to it's initial state, discarding the current
+ * `reducer` result without calling `execute` on it.
+ * - `flush` - Triggers an invocation even if there are active timeouts, and
+ * then resets the funnel to it's initial state.
+ * - `isIdle` - Checks if there are any active timeouts.
+ * @signature
+ *   P.funnel(callback, options);
+ * @example
+ *   const debouncer = P.funnel(
+ *     () => {
+ *       console.log("Callback executed!");
+ *     },
+ *     { minQuietPeriodMs: 100 },
+ *   );
+ *   debouncer.call();
+ *   debouncer.call();
+ *
+ *   const throttle = P.funnel(
+ *     () => {
+ *       console.log("Callback executed!");
+ *     },
+ *     { minGapMs: 100, triggerAt: "start" },
+ *   );
+ *   throttle.call();
+ *   throttle.call();
+ * @category Function
+ */
+declare function funnel<Args extends RestArguments = [], R = never>(callback: (data: R) => void, {
+  triggerAt,
+  minQuietPeriodMs,
+  maxBurstDurationMs,
+  minGapMs,
+  reducer
+}: FunnelOptions<Args, R>): Funnel<Args>;
+//#endregion
+export { funnel };
+//# sourceMappingURL=funnel-1FhwR-u9.d.ts.map

package/dist/funnel-1FhwR-u9.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"funnel-1FhwR-u9.d.ts","names":[],"sources":["../src/funnel.ts"],"sourcesContent":[],"mappings":";;;KAaK,2BAA2B;mCACG,0BAA0B,SAAS;AAdnB,CAAA,GAe/C,mBAFc;;;;;;KASb,mBAAA,GAPD,CAAA;EAAmB,SAAA,SAAA,CAAA,EAAA,KAAA;AAAA,CAAA,GAOlB,CAAA,CAAA;EAoBA,SAAA,QAAa,EAAA,MAAA;AAAQ,CAAA,GAlBe,iBAoBzB,CAAA;EAAA,SAAA,gBAAA,EAAA,MAAA;WAAc,kBAAA,EAAA,MAAA;;EAQC,SAAA,gBAAA,CAAA,EAAA,MAAA;EAiHf,SAAM,kBAAA,CAAA,EAAA,MAAA;EAAA,SAAA,QAAA,CAAA,EAAA,KAAA;;WACH,SAAA,EAAA,OAAA,GAAA,MAAA;WAEf,gBAAA,CAAA,EAAA,MAAA;WACA,kBAAA,CAAA,EAAA,MAAA;WACA,QAAA,CAAA,EAAA,MAAA;;KAhIC,aAAA,GAAgB,KAkIjB,CAAA,GAAA,CAAA;UAhIM,MAiIS,CAAA,aAjIW,aAiIX,GAAA,EAAA,CAAA,CAAA;;;;;;;2BAzHQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiHX,oBAAoB,gDACjB;;;;;;GAOd,cAAc,MAAM,KACtB,OAAO"}

package/dist/funnel-CEbURcmp.js

@@ -0,0 +1,2 @@
+const e=Symbol(`funnel/voidReducer`),t=()=>e;function n(n,{triggerAt:r=`end`,minQuietPeriodMs:i,maxBurstDurationMs:a,minGapMs:o,reducer:s=t}){let c,l,u,d;function f(){let t=u;t!==void 0&&(u=void 0,t===e?n():n(t),o!==void 0&&(l=setTimeout(p,o)))}function p(){clearTimeout(l),l=void 0,c===void 0&&f()}function m(){clearTimeout(c),c=void 0,d=void 0,l===void 0&&f()}return{call:(...e)=>{let t=c===void 0&&l===void 0;if((r!==`start`||t)&&(u=s(u,...e)),!(c===void 0&&!t)){if(i!==void 0||a!==void 0||o===void 0){clearTimeout(c);let e=Date.now();d??=e;let t=a===void 0?i??0:Math.min(i??a,a-(e-d));c=setTimeout(m,t)}r!==`end`&&t&&f()}},cancel:()=>{clearTimeout(c),c=void 0,d=void 0,clearTimeout(l),l=void 0,u=void 0},flush:()=>{m(),p()},get isIdle(){return c===void 0&&l===void 0}}}export{n as funnel};
+//# sourceMappingURL=funnel-CEbURcmp.js.map

package/dist/funnel-CEbURcmp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"funnel-CEbURcmp.js","names":["burstTimeoutId: ReturnType<typeof setTimeout> | undefined","intervalTimeoutId: ReturnType<typeof setTimeout> | undefined","preparedData: R | undefined","burstStartTimestamp: number | undefined"],"sources":["../src/funnel.ts"],"sourcesContent":["import type { RequireAtLeastOne } from 'type-fest';\n\n/**\n * We use the value provided by the reducer to also determine if a call\n * was done during a timeout period. This means that even when no reducer\n * is provided, we still need a dummy reducer that would return something\n * other than `undefined`. It is safe to cast this to R (which might be\n * anything) because the callback would never use it as it would be typed\n * as a zero-args function.\n */\nconst VOID_REDUCER_SYMBOL = Symbol('funnel/voidReducer');\nconst voidReducer = <R>(): R => VOID_REDUCER_SYMBOL as R;\n\ntype FunnelOptions<Args extends RestArguments, R> = {\n  readonly reducer?: (accumulator: R | undefined, ...params: Args) => R;\n} & FunnelTimingOptions;\n\n/**\n * Not all combinations of timing options are valid, there are dependencies\n * between them to ensure users can't configure the funnel in a way which would\n * cause it to never trigger.\n */\ntype FunnelTimingOptions\n  = | ({ readonly triggerAt?: 'end' } & (\n      | ({ readonly minGapMs: number } & RequireAtLeastOne<{\n        readonly minQuietPeriodMs: number;\n        readonly maxBurstDurationMs: number;\n      }>)\n      | {\n        readonly minQuietPeriodMs?: number;\n        readonly maxBurstDurationMs?: number;\n        readonly minGapMs?: never;\n      }\n    ))\n    | {\n      readonly triggerAt: 'start' | 'both';\n      readonly minQuietPeriodMs?: number;\n      readonly maxBurstDurationMs?: number;\n      readonly minGapMs?: number;\n    };\n\n// eslint-disable-next-line ts/no-explicit-any -- TypeScript has some quirks with generic function types, and works best with `any` and not `unknown`. This follows the typing of built-in utilities like `ReturnType` and `Parameters`.\ntype RestArguments = Array<any>;\n\ninterface Funnel<Args extends RestArguments = []> {\n  /**\n   * Call the function. This might result in the `execute` function being called\n   * now or later, depending on it's configuration and it's current state.\n   *\n   * @param args - The args are defined by the `reducer` function.\n   */\n\n  readonly call: (...args: Args) => void;\n\n  /**\n   * Resets the funnel to it's initial state. Any calls made since the last\n   * invocation will be discarded.\n   */\n  readonly cancel: () => void;\n\n  /**\n   * Triggers an invocation regardless of the current state of the funnel.\n   * Like any other invocation, The funnel will also be reset to it's initial\n   * state afterwards.\n   */\n  readonly flush: () => void;\n\n  /**\n   * The funnel is in it's initial state (there are no active timeouts).\n   */\n  readonly isIdle: boolean;\n}\n\n/**\n * Creates a funnel that controls the timing and execution of `callback`. Its\n * main purpose is to manage multiple consecutive (usually fast-paced) calls,\n * reshaping them according to a defined batching strategy and timing policy.\n * This is useful when handling uncontrolled call rates, such as DOM events or\n * network traffic. It can implement strategies like debouncing, throttling,\n * batching, and more.\n *\n * An optional `reducer` function can be provided to allow passing data to the\n * callback via calls to `call` (otherwise the signature of `call` takes no\n * arguments).\n *\n * Typing is inferred from `callback`s param, and from the rest params that\n * the optional `reducer` function accepts. Use **explicit** types for these\n * to ensure that everything _else_ is well-typed.\n *\n * Notice that this function constructs a funnel **object**, and does **not**\n * execute anything when called. The returned object should be used to execute\n * the funnel via the its `call` method.\n *\n * - Debouncing: use `minQuietPeriodMs` and any `triggerAt`.\n * - Throttling: use `minGapMs` and `triggerAt: \"start\"` or `\"both\"`.\n * - Batching: See the reference implementation in [`funnel.reference-batch.test.ts`](https://github.com/vinicunca/perkakas/blob/main/src/funnel.reference-batch.test.ts).\n *\n * @param callback - The main function that would be invoked periodically based\n * on `options`. The function would take the latest result of the `reducer`; if\n * no calls where made since the last time it was invoked it will not be\n * invoked. (If a return value is needed, it should be passed via a reference or\n * via closure to the outer scope of the funnel).\n * @param options - An object that defines when `execute` should be invoked,\n * relative to the calls of `call`. An empty/missing options object is\n * equivalent to setting `minQuietPeriodMs` to `0`.\n * @param options.reducer - Combines the arguments passed to `call` with the\n * value computed on the previous call (or `undefined` on the first time). The\n * goal of the function is to extract and summarize the data needed for\n * `callback`. It should be fast and simple as it is called often and should\n * defer heavy operations to the `execute` function. If the final value\n * is `undefined`, `callback` will not be called.\n * @param options.triggerAt - At what \"edges\" of the funnel's burst window\n * would `execute` invoke:\n * - `start` - the function will be invoked immediately (within the  **same**\n * execution frame!), and any subsequent calls would be ignored until the funnel\n * is idle again. During this period `reducer` will also not be called.\n * - `end` - the function will **not** be invoked initially but the timer will\n * be started. Any calls during this time would be passed to the reducer, and\n * when the timers are done, the reduced result would trigger an invocation.\n * - `both` - the function will be invoked immediately, and then the funnel\n * would behave as if it was in the 'end' state. @default 'end'.\n * @param options.minQuietPeriodMs - The burst timer prevents subsequent calls\n * in short succession to cause excessive invocations (aka \"debounce\"). This\n * duration represents the **minimum** amount of time that needs to pass\n * between calls (the \"quiet\" part) in order for the subsequent call to **not**\n * be considered part of the burst. In other words, as long as calls are faster\n * than this, they are considered part of the burst and the burst is extended.\n * @param options.maxBurstDurationMs - Bursts are extended every time a call is\n * made within the burst period. This means that the burst period could be\n * extended indefinitely. To prevent such cases, a maximum burst duration could\n * be defined. When `minQuietPeriodMs` is not defined and this option is, they\n * will both share the same value.\n * @param options.minGapMs - A minimum duration between calls of `execute`.\n * This is maintained regardless of the shape of the burst and is ensured even\n * if the `maxBurstDurationMs` is reached before it. (aka \"throttle\").\n * @returns A funnel with a `call` function that is used to trigger invocations.\n * In addition to it the funnel also comes with the following functions and\n * properties:\n * - `cancel` - Resets the funnel to it's initial state, discarding the current\n * `reducer` result without calling `execute` on it.\n * - `flush` - Triggers an invocation even if there are active timeouts, and\n * then resets the funnel to it's initial state.\n * - `isIdle` - Checks if there are any active timeouts.\n * @signature\n *   P.funnel(callback, options);\n * @example\n *   const debouncer = P.funnel(\n *     () => {\n *       console.log(\"Callback executed!\");\n *     },\n *     { minQuietPeriodMs: 100 },\n *   );\n *   debouncer.call();\n *   debouncer.call();\n *\n *   const throttle = P.funnel(\n *     () => {\n *       console.log(\"Callback executed!\");\n *     },\n *     { minGapMs: 100, triggerAt: \"start\" },\n *   );\n *   throttle.call();\n *   throttle.call();\n * @category Function\n */\nexport function funnel<Args extends RestArguments = [], R = never>(\n  callback: (data: R) => void,\n  {\n    triggerAt = 'end',\n    minQuietPeriodMs,\n    maxBurstDurationMs,\n    minGapMs,\n    reducer = voidReducer,\n  }: FunnelOptions<Args, R>,\n): Funnel<Args> {\n  /**\n   * We manage execution via 2 timeouts, one to track bursts of calls, and one\n   * to track the interval between invocations. Together we refer to the period\n   * where any of these are active as a \"cool-down period\".\n   */\n  let burstTimeoutId: ReturnType<typeof setTimeout> | undefined;\n  let intervalTimeoutId: ReturnType<typeof setTimeout> | undefined;\n\n  /**\n   * Until invoked, all calls are reduced into a single value that would be sent\n   * to the executor on invocation.\n   */\n  let preparedData: R | undefined;\n\n  /**\n   * In order to be able to limit the total size of the burst (when\n   * `maxBurstDurationMs` is used) we need to track when the burst started.\n   */\n  let burstStartTimestamp: number | undefined;\n\n  function invoke(): void {\n    const param = preparedData;\n    if (param === undefined) {\n      // There were no calls during both cool-down periods.\n      return;\n    }\n\n    // Make sure the args aren't accidentally used again\n    preparedData = undefined;\n\n    // eslint-disable-next-line sonar/different-types-comparison\n    if (param === VOID_REDUCER_SYMBOL) {\n      // @ts-expect-error [ts2554] -- R is typed as `never` because we hide the\n      // symbol that `voidReducer` returns; there's no way to make TypeScript\n      // aware of this.\n      callback();\n    } else {\n      callback(param);\n    }\n\n    if (minGapMs !== undefined) {\n      intervalTimeoutId = setTimeout(handleIntervalEnd, minGapMs);\n    }\n  }\n\n  function handleIntervalEnd(): void {\n    /**\n     * When called via a timeout the timeout is already cleared, but when called\n     * via `flush` we need to manually clear it.\n     */\n    clearTimeout(intervalTimeoutId);\n    intervalTimeoutId = undefined;\n\n    if (burstTimeoutId !== undefined) {\n      /**\n       * As long as one of the timeouts is active we don't invoke the function.\n       * Each timeout's end event handler has a call to invoke, so we are\n       * guaranteed to invoke the function eventually.\n       */\n      return;\n    }\n\n    invoke();\n  };\n\n  function handleBurstEnd(): void {\n    /**\n     * When called via a timeout the timeout is already cleared, but when called\n     * via `flush` we need to manually clear it.\n     */\n    clearTimeout(burstTimeoutId);\n    burstTimeoutId = undefined;\n    burstStartTimestamp = undefined;\n\n    if (intervalTimeoutId !== undefined) {\n      /**\n       * As long as one of the timeouts is active we don't invoke the function.\n       * Each timeout's end event handler has a call to invoke, so we are\n       * guaranteed to invoke the function eventually.\n       */\n      return;\n    }\n\n    invoke();\n  };\n\n  return {\n    call: (...args) => {\n      /**\n       * We act based on the initial state of the timeouts before the call is\n       * handled and causes the timeouts to change.\n       */\n      const wasIdle = burstTimeoutId === undefined && intervalTimeoutId === undefined;\n\n      if (triggerAt !== 'start' || wasIdle) {\n        preparedData = reducer(preparedData, ...args);\n      }\n\n      if (burstTimeoutId === undefined && !wasIdle) {\n        /**\n         * We are not in an active burst period but in an interval period. We\n         * don't start a new burst window until the next invoke.\n         */\n        return;\n      }\n\n      if (\n        minQuietPeriodMs !== undefined\n        || maxBurstDurationMs !== undefined\n        || minGapMs === undefined\n      ) {\n        /**\n         * The timeout tracking the burst period needs to be reset every time\n         * another call is made so that it waits the full cool-down duration\n         * before it is released.\n         */\n        clearTimeout(burstTimeoutId);\n\n        const now = Date.now();\n\n        burstStartTimestamp ??= now;\n\n        const burstRemainingMs\n          = maxBurstDurationMs === undefined\n            ? (minQuietPeriodMs ?? 0)\n            : Math.min(\n                minQuietPeriodMs ?? maxBurstDurationMs,\n                /**\n                 * We need to account for the time already spent so that we\n                 * don't wait longer than the maxDelay.\n                 */\n                maxBurstDurationMs - (now - burstStartTimestamp),\n              );\n\n        burstTimeoutId = setTimeout(handleBurstEnd, burstRemainingMs);\n      }\n\n      if (triggerAt !== 'end' && wasIdle) {\n        invoke();\n      }\n    },\n\n    cancel: () => {\n      clearTimeout(burstTimeoutId);\n      burstTimeoutId = undefined;\n      burstStartTimestamp = undefined;\n\n      clearTimeout(intervalTimeoutId);\n      intervalTimeoutId = undefined;\n\n      preparedData = undefined;\n    },\n\n    flush: () => {\n      handleBurstEnd();\n      handleIntervalEnd();\n    },\n\n    get isIdle() {\n      return burstTimeoutId === undefined && intervalTimeoutId === undefined;\n    },\n  };\n}\n"],"mappings":"AAUA,MAAM,EAAsB,OAAO,qBAAqB,CAClD,MAA0B,EA0JhC,SAAgB,EACd,EACA,CACE,YAAY,MACZ,mBACA,qBACA,WACA,UAAU,GAEE,CAMd,IAAIA,EACAC,EAMAC,EAMAC,EAEJ,SAAS,GAAe,CACtB,IAAM,EAAQ,EACV,IAAU,IAAA,KAMd,EAAe,IAAA,GAGX,IAAU,EAIZ,GAAU,CAEV,EAAS,EAAM,CAGb,IAAa,IAAA,KACf,EAAoB,WAAW,EAAmB,EAAS,GAI/D,SAAS,GAA0B,CAKjC,aAAa,EAAkB,CAC/B,EAAoB,IAAA,GAEhB,IAAmB,IAAA,IASvB,GAAQ,CAGV,SAAS,GAAuB,CAK9B,aAAa,EAAe,CAC5B,EAAiB,IAAA,GACjB,EAAsB,IAAA,GAElB,IAAsB,IAAA,IAS1B,GAAQ,CAGV,MAAO,CACL,MAAO,GAAG,IAAS,CAKjB,IAAM,EAAU,IAAmB,IAAA,IAAa,IAAsB,IAAA,GAEtE,IAAI,IAAc,SAAW,KAC3B,EAAe,EAAQ,EAAc,GAAG,EAAK,EAG3C,MAAmB,IAAA,IAAa,CAAC,GAQrC,IACE,IAAqB,IAAA,IAClB,IAAuB,IAAA,IACvB,IAAa,IAAA,GAChB,CAMA,aAAa,EAAe,CAE5B,IAAM,EAAM,KAAK,KAAK,CAEtB,IAAwB,EAExB,IAAM,EACF,IAAuB,IAAA,GACpB,GAAoB,EACrB,KAAK,IACH,GAAoB,EAKpB,GAAsB,EAAM,GAC7B,CAEP,EAAiB,WAAW,EAAgB,EAAiB,CAG3D,IAAc,OAAS,GACzB,GAAQ,GAIZ,WAAc,CACZ,aAAa,EAAe,CAC5B,EAAiB,IAAA,GACjB,EAAsB,IAAA,GAEtB,aAAa,EAAkB,CAC/B,EAAoB,IAAA,GAEpB,EAAe,IAAA,IAGjB,UAAa,CACX,GAAgB,CAChB,GAAmB,EAGrB,IAAI,QAAS,CACX,OAAO,IAAmB,IAAA,IAAa,IAAsB,IAAA,IAEhE"}

package/dist/funnel-CL-QFpGk.cjs

@@ -0,0 +1 @@
+const e=Symbol(`funnel/voidReducer`),t=()=>e;function n(n,{triggerAt:r=`end`,minQuietPeriodMs:i,maxBurstDurationMs:a,minGapMs:o,reducer:s=t}){let c,l,u,d;function f(){let t=u;t!==void 0&&(u=void 0,t===e?n():n(t),o!==void 0&&(l=setTimeout(p,o)))}function p(){clearTimeout(l),l=void 0,c===void 0&&f()}function m(){clearTimeout(c),c=void 0,d=void 0,l===void 0&&f()}return{call:(...e)=>{let t=c===void 0&&l===void 0;if((r!==`start`||t)&&(u=s(u,...e)),!(c===void 0&&!t)){if(i!==void 0||a!==void 0||o===void 0){clearTimeout(c);let e=Date.now();d??=e;let t=a===void 0?i??0:Math.min(i??a,a-(e-d));c=setTimeout(m,t)}r!==`end`&&t&&f()}},cancel:()=>{clearTimeout(c),c=void 0,d=void 0,clearTimeout(l),l=void 0,u=void 0},flush:()=>{m(),p()},get isIdle(){return c===void 0&&l===void 0}}}Object.defineProperty(exports,`funnel`,{enumerable:!0,get:function(){return n}});

package/dist/funnel-DRrT4WPx.d.cts

@@ -0,0 +1,155 @@
+import { RequireAtLeastOne } from "type-fest";
+
+//#region src/funnel.d.ts
+type FunnelOptions<Args extends RestArguments, R> = {
+  readonly reducer?: (accumulator: R | undefined, ...params: Args) => R;
+} & FunnelTimingOptions;
+/**
+ * Not all combinations of timing options are valid, there are dependencies
+ * between them to ensure users can't configure the funnel in a way which would
+ * cause it to never trigger.
+ */
+type FunnelTimingOptions = ({
+  readonly triggerAt?: 'end';
+} & (({
+  readonly minGapMs: number;
+} & RequireAtLeastOne<{
+  readonly minQuietPeriodMs: number;
+  readonly maxBurstDurationMs: number;
+}>) | {
+  readonly minQuietPeriodMs?: number;
+  readonly maxBurstDurationMs?: number;
+  readonly minGapMs?: never;
+})) | {
+  readonly triggerAt: 'start' | 'both';
+  readonly minQuietPeriodMs?: number;
+  readonly maxBurstDurationMs?: number;
+  readonly minGapMs?: number;
+};
+type RestArguments = Array<any>;
+interface Funnel<Args extends RestArguments = []> {
+  /**
+   * Call the function. This might result in the `execute` function being called
+   * now or later, depending on it's configuration and it's current state.
+   *
+   * @param args - The args are defined by the `reducer` function.
+   */
+  readonly call: (...args: Args) => void;
+  /**
+   * Resets the funnel to it's initial state. Any calls made since the last
+   * invocation will be discarded.
+   */
+  readonly cancel: () => void;
+  /**
+   * Triggers an invocation regardless of the current state of the funnel.
+   * Like any other invocation, The funnel will also be reset to it's initial
+   * state afterwards.
+   */
+  readonly flush: () => void;
+  /**
+   * The funnel is in it's initial state (there are no active timeouts).
+   */
+  readonly isIdle: boolean;
+}
+/**
+ * Creates a funnel that controls the timing and execution of `callback`. Its
+ * main purpose is to manage multiple consecutive (usually fast-paced) calls,
+ * reshaping them according to a defined batching strategy and timing policy.
+ * This is useful when handling uncontrolled call rates, such as DOM events or
+ * network traffic. It can implement strategies like debouncing, throttling,
+ * batching, and more.
+ *
+ * An optional `reducer` function can be provided to allow passing data to the
+ * callback via calls to `call` (otherwise the signature of `call` takes no
+ * arguments).
+ *
+ * Typing is inferred from `callback`s param, and from the rest params that
+ * the optional `reducer` function accepts. Use **explicit** types for these
+ * to ensure that everything _else_ is well-typed.
+ *
+ * Notice that this function constructs a funnel **object**, and does **not**
+ * execute anything when called. The returned object should be used to execute
+ * the funnel via the its `call` method.
+ *
+ * - Debouncing: use `minQuietPeriodMs` and any `triggerAt`.
+ * - Throttling: use `minGapMs` and `triggerAt: "start"` or `"both"`.
+ * - Batching: See the reference implementation in [`funnel.reference-batch.test.ts`](https://github.com/vinicunca/perkakas/blob/main/src/funnel.reference-batch.test.ts).
+ *
+ * @param callback - The main function that would be invoked periodically based
+ * on `options`. The function would take the latest result of the `reducer`; if
+ * no calls where made since the last time it was invoked it will not be
+ * invoked. (If a return value is needed, it should be passed via a reference or
+ * via closure to the outer scope of the funnel).
+ * @param options - An object that defines when `execute` should be invoked,
+ * relative to the calls of `call`. An empty/missing options object is
+ * equivalent to setting `minQuietPeriodMs` to `0`.
+ * @param options.reducer - Combines the arguments passed to `call` with the
+ * value computed on the previous call (or `undefined` on the first time). The
+ * goal of the function is to extract and summarize the data needed for
+ * `callback`. It should be fast and simple as it is called often and should
+ * defer heavy operations to the `execute` function. If the final value
+ * is `undefined`, `callback` will not be called.
+ * @param options.triggerAt - At what "edges" of the funnel's burst window
+ * would `execute` invoke:
+ * - `start` - the function will be invoked immediately (within the  **same**
+ * execution frame!), and any subsequent calls would be ignored until the funnel
+ * is idle again. During this period `reducer` will also not be called.
+ * - `end` - the function will **not** be invoked initially but the timer will
+ * be started. Any calls during this time would be passed to the reducer, and
+ * when the timers are done, the reduced result would trigger an invocation.
+ * - `both` - the function will be invoked immediately, and then the funnel
+ * would behave as if it was in the 'end' state. @default 'end'.
+ * @param options.minQuietPeriodMs - The burst timer prevents subsequent calls
+ * in short succession to cause excessive invocations (aka "debounce"). This
+ * duration represents the **minimum** amount of time that needs to pass
+ * between calls (the "quiet" part) in order for the subsequent call to **not**
+ * be considered part of the burst. In other words, as long as calls are faster
+ * than this, they are considered part of the burst and the burst is extended.
+ * @param options.maxBurstDurationMs - Bursts are extended every time a call is
+ * made within the burst period. This means that the burst period could be
+ * extended indefinitely. To prevent such cases, a maximum burst duration could
+ * be defined. When `minQuietPeriodMs` is not defined and this option is, they
+ * will both share the same value.
+ * @param options.minGapMs - A minimum duration between calls of `execute`.
+ * This is maintained regardless of the shape of the burst and is ensured even
+ * if the `maxBurstDurationMs` is reached before it. (aka "throttle").
+ * @returns A funnel with a `call` function that is used to trigger invocations.
+ * In addition to it the funnel also comes with the following functions and
+ * properties:
+ * - `cancel` - Resets the funnel to it's initial state, discarding the current
+ * `reducer` result without calling `execute` on it.
+ * - `flush` - Triggers an invocation even if there are active timeouts, and
+ * then resets the funnel to it's initial state.
+ * - `isIdle` - Checks if there are any active timeouts.
+ * @signature
+ *   P.funnel(callback, options);
+ * @example
+ *   const debouncer = P.funnel(
+ *     () => {
+ *       console.log("Callback executed!");
+ *     },
+ *     { minQuietPeriodMs: 100 },
+ *   );
+ *   debouncer.call();
+ *   debouncer.call();
+ *
+ *   const throttle = P.funnel(
+ *     () => {
+ *       console.log("Callback executed!");
+ *     },
+ *     { minGapMs: 100, triggerAt: "start" },
+ *   );
+ *   throttle.call();
+ *   throttle.call();
+ * @category Function
+ */
+declare function funnel<Args extends RestArguments = [], R = never>(callback: (data: R) => void, {
+  triggerAt,
+  minQuietPeriodMs,
+  maxBurstDurationMs,
+  minGapMs,
+  reducer
+}: FunnelOptions<Args, R>): Funnel<Args>;
+//#endregion
+export { funnel };
+//# sourceMappingURL=funnel-DRrT4WPx.d.cts.map

package/dist/funnel-DRrT4WPx.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"funnel-DRrT4WPx.d.cts","names":[],"sources":["../src/funnel.ts"],"sourcesContent":[],"mappings":";;;KAaK,2BAA2B;mCACG,0BAA0B,SAAS;AAdnB,CAAA,GAe/C,mBAFc;;;;;;KASb,mBAAA,GAPD,CAAA;EAAmB,SAAA,SAAA,CAAA,EAAA,KAAA;AAAA,CAAA,GAOlB,CAAA,CAAA;EAoBA,SAAA,QAAa,EAAA,MAAA;AAAQ,CAAA,GAlBe,iBAoBzB,CAAA;EAAA,SAAA,gBAAA,EAAA,MAAA;WAAc,kBAAA,EAAA,MAAA;;EAQC,SAAA,gBAAA,CAAA,EAAA,MAAA;EAiHf,SAAM,kBAAA,CAAA,EAAA,MAAA;EAAA,SAAA,QAAA,CAAA,EAAA,KAAA;;WACH,SAAA,EAAA,OAAA,GAAA,MAAA;WAEf,gBAAA,CAAA,EAAA,MAAA;WACA,kBAAA,CAAA,EAAA,MAAA;WACA,QAAA,CAAA,EAAA,MAAA;;KAhIC,aAAA,GAAgB,KAkIjB,CAAA,GAAA,CAAA;UAhIM,MAiIS,CAAA,aAjIW,aAiIX,GAAA,EAAA,CAAA,CAAA;;;;;;;2BAzHQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiHX,oBAAoB,gDACjB;;;;;;GAOd,cAAc,MAAM,KACtB,OAAO"}

package/dist/funnel.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkRMOD5JNBcjs = require('./chunk-RMOD5JNB.cjs');require('./chunk-MBGSSEZN.cjs');exports.funnel = _chunkRMOD5JNBcjs.a;
+const e=require(`./funnel-CL-QFpGk.cjs`);exports.funnel=e.funnel;