async-lube 2.0.0 → 2.1.0

package/src/limiter.js

@@ -3,48 +3,49 @@ import { CancelError } from "./errors.js"
 import { check_options } from "./options.js"
 import { clamp_delay, noop, on_abort } from "./signal.js"
 /**
- * @param {{ concurrency?: number | undefined, rate?: { count: number, per: number } | undefined }} options
+ * @param {{ concurrency?: number | undefined, rate?: { count: number, per: number, window?: "fixed" | "sliding" | undefined } | undefined }} options
  * @param {() => void=} on_idle
  * @returns {LimiterState}
  */
 function create_state(options, on_idle) {
 	const { concurrency = Infinity, rate } = options
+	const fixed = rate?.window == "fixed"
 	/** @type {LimiterJob[]} */
 	const queue = []
 	/** @type {number[]} */
 	const starts = []
+	let window_start = 0
+	let used = 0
 	/** @type {LimiterState} */
-	const state = { queue, running: 0, schedule: pump }
+	const state = {
+		queue,
+		running: 0,
+		schedule: pump,
+		take
+	}
 	/** @type {ReturnType<typeof setTimeout> | undefined} */
 	let timer
-	/**
-	 * @returns {void}
-	 */
+	return state
+	/** @returns {void} */
 	function done() {
 		state.running--
 		pump()
 	}
-	/**
-	 * @returns {void}
-	 */
+	/** @returns {void} */
 	function pump() {
 		while (queue.length && state.running < concurrency) {
 			if (rate) {
-				const now = Date.now()
-				while (starts.length && now - /** @type {number} */(starts[0])/**/ >= rate.per) starts.shift()
-				if (starts.length >= rate.count) {
+				const wait = reserve(Date.now())
+				if (wait > 0) {
 					timer ??= setTimeout(
 						() => {
 							timer = void 0
 							pump()
 						},
-						clamp_delay(
-							/** @type {number} */(starts[0])/**/ + rate.per - now
-						)
+						clamp_delay(wait)
 					)
 					return
 				}
-				starts.push(now)
 			}
 			const job = /** @type {LimiterJob} */(queue.shift())/**/
 			job.unlink()
@@ -61,17 +62,27 @@ function create_state(options, on_idle) {
 			job.resolve(
 				{
 					release: () => {
-						if (released) return
+						if (released) {
+							return
+						}
 						released = true
 						done()
 					}
 				}
 			)
 		}
-		if (queue.length || state.running || timer || !on_idle) return
-		const left = rate && starts.length
-			? /** @type {number} */(starts.at(-1))/**/ + rate.per - Date.now()
-			: 0
+		if (queue.length || state.running || timer || !on_idle) {
+			return
+		}
+		const left = !rate
+			? 0
+			: fixed
+				? used
+					? window_start + rate.per - Date.now()
+					: 0
+				: starts.length
+					? /** @type {number} */(starts.at(-1))/**/ + rate.per - Date.now()
+					: 0
 		if (left > 0) {
 			timer = setTimeout(
 				() => {
@@ -84,16 +95,50 @@ function create_state(options, on_idle) {
 		}
 		on_idle()
 	}
-	return state
+	/**
+	 * @param {number} now
+	 * @returns {number}
+	 */
+	function reserve(now) {
+		const { count, per } = /** @type {{ count: number, per: number }} */(rate)/**/
+		if (fixed) {
+			if (used && now - window_start >= per) {
+				used = 0
+			}
+			if (used >= count) {
+				return window_start + per - now
+			}
+			if (!used) {
+				window_start = now
+			}
+			used++
+			return 0
+		}
+		while (starts.length && now - /** @type {number} */(starts[0])/**/ >= per) {
+			starts.shift()
+		}
+		if (starts.length >= count) {
+			return /** @type {number} */(starts[0])/**/ + per - now
+		}
+		starts.push(now)
+		return 0
+	}
+	/** @returns {number} */
+	function take() {
+		return reserve(Date.now())
+	}
 }
 /**
  * Limits the calls that run at the same time, and the calls that start per interval, across everything that shares it:
  * a database pool, a file system, an API quota. Use it inside flow nodes to limit them across runs.
+ * With a `rate`, `take()` answers at once whether a start is free, e.g. for a packet limit per socket.
  * @example
  * const db = limiter({ concurrency: 10 })
  * const openai = limiter({ rate: { count: 60, per: 60000 } })
  * const user = await db(() => pool.query("select ..."))
- * @param {{ concurrency?: number | undefined, rate?: { count: number, per: number } | undefined }} options
+ * const packets = limiter({ rate: { count: 20, per: 1000, window: "fixed" } })
+ * const retry_after = packets.take(socket.id)
+ * @param {{ concurrency?: number | undefined, rate?: { count: number, per: number, window?: "fixed" | "sliding" | undefined } | undefined }} options
  * @returns {import("../public.js").Limiter}
  */
 export function limiter(options) {
@@ -104,46 +149,78 @@ export function limiter(options) {
 	)
 	check_options(
 		options.rate,
-		[ "count", "per" ],
+		[ "count", "per", "window" ],
 		"limiter",
 		"rate."
 	)
 	const { concurrency = Infinity, rate } = options
-	if (!(concurrency === Infinity || Number.isInteger(concurrency) && concurrency >= 1)) throw TypeError(
-		"The concurrency of limiter() must be a positive integer or Infinity"
-	)
-	if (rate && !(Number.isInteger(rate.count) && rate.count >= 1 && typeof rate.per == "number" && rate.per > 0)) throw TypeError(
-		"The rate of limiter() must be { count, per } with a positive integer count and positive milliseconds"
-	)
+	if (!(concurrency === Infinity || Number.isInteger(concurrency) && concurrency >= 1)) {
+		throw TypeError(
+			"The concurrency of limiter() must be a positive integer or Infinity"
+		)
+	}
+	if (rate && !(Number.isInteger(rate.count) && rate.count >= 1 && typeof rate.per == "number" && rate.per > 0)) {
+		throw TypeError(
+			"The rate of limiter() must be { count, per } with a positive integer count and positive milliseconds"
+		)
+	}
+	if (rate?.window !== void 0 && rate.window != "sliding" && rate.window != "fixed") {
+		throw TypeError(
+			"The rate.window of limiter() must be \"sliding\" or \"fixed\""
+		)
+	}
 	/** @type {Map<unknown, LimiterState>} */
 	const keyed = new Map()
 	const root = create_state(options)
+	return to_limiter(
+		() => root,
+		() => root,
+		key,
+		name => take(() => root, name)
+	)
 	/**
 	 * @param {unknown} name
 	 * @returns {import("../public.js").Limiter}
 	 */
 	function key(name) {
-		/**
-		 * @returns {LimiterState}
-		 */
-		function current() {
-			let state = keyed.get(name)
-			if (!state) {
-				state = create_state(
-					options,
-					() => keyed.delete(name)
-				)
-				keyed.set(name, state)
-			}
-			return state
-		}
 		return to_limiter(
-			current,
+			() => state_of(name),
 			() => keyed.get(name),
-			key
+			key,
+			other => take(() => state_of(name), other)
 		)
 	}
-	return to_limiter(() => root, () => root, key)
+	/**
+	 * @param {unknown} name
+	 * @returns {LimiterState}
+	 */
+	function state_of(name) {
+		let state = keyed.get(name)
+		if (!state) {
+			state = create_state(
+				options,
+				() => keyed.delete(name)
+			)
+			keyed.set(name, state)
+		}
+		return state
+	}
+	/**
+	 * @param {() => LimiterState} own
+	 * @param {unknown} name
+	 * @returns {number}
+	 */
+	function take(own, name) {
+		if (!rate) {
+			throw TypeError(
+				"take() of limiter() needs a rate"
+			)
+		}
+		const state = name === void 0 ? own() : state_of(name)
+		const wait = state.take()
+		state.schedule()
+		return wait
+	}
 }
 /**
  * @param {unknown} reason
@@ -156,9 +233,28 @@ function to_cancel_error(reason) {
  * @param {() => LimiterState} current
  * @param {() => LimiterState | undefined} peek
  * @param {(key: unknown) => import("../public.js").Limiter} key
+ * @param {(key: unknown) => number} take
  * @returns {import("../public.js").Limiter}
  */
-function to_limiter(current, peek, key) {
+function to_limiter(current, peek, key, take) {
+	return /** @type {import("../public.js").Limiter} */(Object.defineProperties(
+		limit,
+		{
+			acquire: {
+				value: (
+					/** @type {AbortSignal=} */ signal
+				) => enqueue(void 0, signal)
+			},
+			key: { value: key },
+			pending: {
+				get: () => peek()?.queue.length ?? 0
+			},
+			running: {
+				get: () => peek()?.running ?? 0
+			},
+			take: { value: take }
+		}
+	))/**/
 	/**
 	 * @param {(() => unknown) | undefined} fn
 	 * @param {AbortSignal | undefined} signal
@@ -179,7 +275,9 @@ function to_limiter(current, peek, key) {
 						signal,
 						() => {
 							const index = state.queue.indexOf(job)
-							if (index < 0) return
+							if (index < 0) {
+								return
+							}
 							state.queue.splice(index, 1)
 							reject(to_cancel_error(signal.reason))
 							state.schedule()
@@ -199,21 +297,4 @@ function to_limiter(current, peek, key) {
 	function limit(fn, signal) {
 		return enqueue(fn, signal)
 	}
-	return /** @type {import("../public.js").Limiter} */(Object.defineProperties(
-		limit,
-		{
-			acquire: {
-				value: (
-					/** @type {AbortSignal=} */ signal
-				) => enqueue(void 0, signal)
-			},
-			key: { value: key },
-			pending: {
-				get: () => peek()?.queue.length ?? 0
-			},
-			running: {
-				get: () => peek()?.running ?? 0
-			}
-		}
-	))/**/
 }

package/src/offload.js

@@ -1,31 +1,54 @@
 /** @import { NodeWorker, OffloadJob, OffloadWorker } from "../private.js" */
 import { CancelError } from "./errors.js"
+import { offload_module, to_error } from "./offload_module.js"
 import { check_options } from "./options.js"
 import { noop, on_abort } from "./signal.js"
 /**
- * Runs a function in a Worker, or a worker thread in Node.js 20.16 or later, so that heavy work does not block the page or the server.
- * The function travels as its source, so it may use only its arguments and globals: an arrow function or a function expression,
- * not a method or a closure. Arguments and results are copied as `postMessage` copies them. `concurrency` workers run at once, 1 by default.
- * @example
- * const resize = offload(async (bytes: ArrayBuffer, width: number) => shrink(bytes, width))
- * const thumbnail = await resize(bytes, 200, signal) // the signal terminates the worker
+ * @param {unknown} target
+ * @param {unknown=} options
+ * @returns {never}
+ */
+function create_offload(target, options) {
+	if (typeof target == "function") {
+		return /** @type {never} */(offload_function(
+			/** @type {(...args: never[]) => unknown} */(target)/**/,
+			/** @type {{ concurrency?: number | undefined } | undefined} */(options)/**/
+		))/**/
+	}
+	if (typeof target == "string" || target instanceof URL) {
+		return /** @type {never} */(offload_module(
+			target,
+			/** @type {import("../public.js").OffloadModuleOptions | undefined} */(options)/**/
+		))/**/
+	}
+	throw TypeError(
+		"offload() needs a function, or the URL of a worker module"
+	)
+}
+/** @type {import("../public.js").OffloadFunction} */
+export const offload = create_offload
+/**
  * @template {unknown[]} A
  * @template R
  * @param {(...args: A) => R} fn
  * @param {{ concurrency?: number | undefined }=} options
  * @returns {import("../public.js").Offloaded<A, R>}
  */
-export function offload(fn, options = {}) {
-	if (typeof fn != "function") throw TypeError("offload() needs a function")
+function offload_function(fn, options = {}) {
+	if (typeof fn != "function") {
+		throw TypeError("offload() needs a function")
+	}
 	check_options(
 		options,
 		[ "concurrency" ],
 		"offload"
 	)
 	const concurrency = options.concurrency ?? 1
-	if (!(concurrency === Infinity || Number.isInteger(concurrency) && concurrency >= 1)) throw TypeError(
-		"The concurrency of offload() must be a positive integer or Infinity"
-	)
+	if (!(concurrency === Infinity || Number.isInteger(concurrency) && concurrency >= 1)) {
+		throw TypeError(
+			"The concurrency of offload() must be a positive integer or Infinity"
+		)
+	}
 	const source = String(fn)
 	/** @type {OffloadJob[]} */
 	const queue = []
@@ -34,6 +57,26 @@ export function offload(fn, options = {}) {
 	/** @type {string | undefined} */
 	let url
 	let count = 0
+	const run = /** @type {import("../public.js").Offloaded<never[], unknown>} */(/** @type {unknown} */(call))/**/
+	run.close = () => {
+		for (const job of queue.splice(0)) {
+			job.reject(
+				new CancelError("The offload was closed")
+			)
+		}
+		for (const worker of workers) {
+			worker.job?.reject(
+				new CancelError("The offload was closed")
+			)
+			worker.stop()
+		}
+		workers.clear()
+		if (url) {
+			URL.revokeObjectURL(url)
+		}
+		url = void 0
+	}
+	return /** @type {import("../public.js").Offloaded<A, R>} */(/** @type {unknown} */(run))/**/
 	/**
 	 * @param {...unknown} args
 	 * @returns {import("../public.js").OffloadCall<unknown>}
@@ -41,14 +84,16 @@ export function offload(fn, options = {}) {
 	function call(...args) {
 		const last = args.at(-1)
 		const signal = last instanceof AbortSignal ? last : void 0
-		if (signal) args.pop()
+		if (signal) {
+			args.pop()
+		}
 		let unlink = noop
 		/** @type {OffloadJob} */
 		const job = {
 			args,
 			id: ++count,
-			reject: () => {},
-			resolve: () => {}
+			reject: noop,
+			resolve: noop
 		}
 		const promise = new Promise(
 			(resolve, reject) => {
@@ -62,12 +107,15 @@ export function offload(fn, options = {}) {
 				}
 			}
 		)
-		if (signal?.aborted) job.reject(new CancelError(signal.reason))
-		else {
-			if (signal) unlink = on_abort(
-				signal,
-				() => cancel_job(job, signal.reason)
-			)
+		if (signal?.aborted) {
+			job.reject(new CancelError(signal.reason))
+		} else {
+			if (signal) {
+				unlink = on_abort(
+					signal,
+					() => cancel_job(job, signal.reason)
+				)
+			}
 			queue.push(job)
 			dispatch()
 		}
@@ -86,9 +134,13 @@ export function offload(fn, options = {}) {
 	 */
 	function cancel_job(job, reason) {
 		const index = queue.indexOf(job)
-		if (index >= 0) queue.splice(index, 1)
+		if (index >= 0) {
+			queue.splice(index, 1)
+		}
 		for (const worker of workers) {
-			if (worker.job != job) continue
+			if (worker.job != job) {
+				continue
+			}
 			worker.job = void 0
 			worker.stop()
 			workers.delete(worker)
@@ -98,18 +150,20 @@ export function offload(fn, options = {}) {
 		)
 		dispatch()
 	}
-	/**
-	 * @returns {void}
-	 */
+	/** @returns {void} */
 	function dispatch() {
 		while (queue.length) {
 			let worker = [ ...workers ].find(item => !item.job)
 			if (!worker) {
-				if (workers.size >= concurrency) return
+				if (workers.size >= concurrency) {
+					return
+				}
 				try {
 					worker = spawn()
 				} catch (error) {
-					for (const job of queue.splice(0)) job.reject(error)
+					for (const job of queue.splice(0)) {
+						job.reject(error)
+					}
 					return
 				}
 			}
@@ -132,40 +186,14 @@ export function offload(fn, options = {}) {
 		worker.idle?.()
 		dispatch()
 	}
-	/**
-	 * @returns {OffloadWorker}
-	 */
+	/** @returns {OffloadWorker} */
 	function spawn() {
 		const threads = /** @type {{ process?: { getBuiltinModule?: (name: string) => unknown } }} */(globalThis)/**/.process?.getBuiltinModule?.("node:worker_threads")
 		/** @type {OffloadWorker} */
 		const worker = {
 			job: void 0,
-			send: () => {},
-			stop: () => {}
-		}
-		/**
-		 * @param {unknown} error
-		 * @returns {void}
-		 */
-		function crash(error) {
-			const { job } = worker
-			worker.job = void 0
-			worker.stop()
-			workers.delete(worker)
-			job?.reject(to_error(error))
-			dispatch()
-		}
-		/**
-		 * @param {[number, boolean, unknown]} message
-		 * @returns {void}
-		 */
-		function receive([ id, ok, value ]) {
-			const { job } = worker
-			if (!job || job.id != id) return
-			worker.job = void 0
-			if (ok) job.resolve(value)
-			else job.reject(to_error(value))
-			finish(worker)
+			send: noop,
+			stop: noop
 		}
 		if (threads) {
 			const { Worker } = /** @type {{ Worker: new (code: string, options: { eval: true }) => NodeWorker }} */(threads)/**/
@@ -201,28 +229,43 @@ export function offload(fn, options = {}) {
 			}
 			worker.send = message => thread.postMessage(message)
 			worker.stop = () => thread.terminate()
-		} else throw TypeError(
-			"offload() needs Worker, or worker_threads of Node.js 20.16 or later"
-		)
+		} else {
+			throw TypeError(
+				"offload() needs Worker, or worker_threads of Node.js 20.16 or later"
+			)
+		}
 		workers.add(worker)
 		return worker
-	}
-	const run = /** @type {import("../public.js").Offloaded<never[], unknown>} */(/** @type {unknown} */(call))/**/
-	run.close = () => {
-		for (const job of queue.splice(0)) job.reject(
-			new CancelError("The offload was closed")
-		)
-		for (const worker of workers) {
-			worker.job?.reject(
-				new CancelError("The offload was closed")
-			)
+		/**
+		 * @param {unknown} error
+		 * @returns {void}
+		 */
+		function crash(error) {
+			const { job } = worker
+			worker.job = void 0
 			worker.stop()
+			workers.delete(worker)
+			job?.reject(to_error(error))
+			dispatch()
+		}
+		/**
+		 * @param {[number, boolean, unknown]} message
+		 * @returns {void}
+		 */
+		function receive([ id, ok, value ]) {
+			const { job } = worker
+			if (!job || job.id != id) {
+				return
+			}
+			worker.job = void 0
+			if (ok) {
+				job.resolve(value)
+			} else {
+				job.reject(to_error(value))
+			}
+			finish(worker)
 		}
-		workers.clear()
-		if (url) URL.revokeObjectURL(url)
-		url = void 0
 	}
-	return /** @type {import("../public.js").Offloaded<A, R>} */(/** @type {unknown} */(run))/**/
 }
 /**
  * @param {string} post
@@ -240,16 +283,4 @@ function reply(post) {
 		}
 	}
 }`
-}
-/**
- * @param {unknown} value
- * @returns {unknown}
- */
-function to_error(value) {
-	if (value instanceof Error || value == null || typeof value != "object" || !("message" in value)) return value
-	const error = Error(String(value.message))
-	error.name = String(
-		/** @type {{ name?: unknown }} */(value)/**/.name ?? "Error"
-	)
-	return error
 }