1 line
14 KiB
Text
1 line
14 KiB
Text
|
{"version":3,"file":"funnel.cjs","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// 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.\nconst VOID_REDUCER_SYMBOL = Symbol(\"funnel/voidReducer\");\n// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- Intentional, so that it could be used as a default value above.\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// 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.\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 @typescript-eslint/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 = any[];\n\ntype 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` m
|