async-lube 2.0.0 → 2.1.0

package/src/flow/compile.js

@@ -15,7 +15,9 @@ const programs = new WeakMap()
  */
 export function compile(definition) {
 	const cached = programs.get(definition)
-	if (cached) return cached
+	if (cached) {
+		return cached
+	}
 	const source_nodes = definition.list.slice(0, definition.count)
 	/** @type {Map<unknown, string>} */
 	const by_ref = new Map(
@@ -24,45 +26,6 @@ export function compile(definition) {
 		)
 	)
 	const by_name = new Set(by_ref.values())
-	/**
-	 * @param {unknown} target
-	 * @returns {string | undefined}
-	 */
-	function name_of(target) {
-		return typeof target == "string"
-			? by_name.has(target)
-				? target
-				: void 0
-			: by_ref.get(target)
-	}
-	/**
-	 * @param {unknown} target
-	 * @param {string} message
-	 * @returns {string}
-	 */
-	function resolve(target, message) {
-		const name = name_of(target)
-		if (name == null) throw Error(
-			message.replace("%s", describe(target))
-		)
-		return name
-	}
-	/**
-	 * @param {DefinitionNode} node
-	 * @returns {Record<string, "keep" | "queue" | "restart"> | undefined}
-	 */
-	function to_arrive(node) {
-		/** @type {Record<string, "keep" | "queue" | "restart"> | undefined} */
-		let arrive
-		for (const dep of node.deps) {
-			if (!/** @type {RefProbe} */(dep)/**/?.[ARRIVE]) continue
-			(arrive ??= Object.create(null))[resolve(
-				to_ref(dep),
-				`Flow node "${node.name}" depends on %s, which is not added`
-			)] = /** @type {{ policy: "keep" | "queue" | "restart" }} */(/** @type {unknown} */(dep))/**/.policy
-		}
-		return arrive
-	}
 	/** @type {ProgramNode[]} */
 	const nodes = source_nodes.map(
 		node => ({
@@ -100,7 +63,9 @@ export function compile(definition) {
 		for (const dep of node.deps) {
 			const source = /** @type {ProgramNode} */(nodes_by_name.get(dep))/**/
 			source.dependents.push(node.name)
-			if (node.arrive?.[dep] == "queue") source.queuers.push(node.name)
+			if (node.arrive?.[dep] == "queue") {
+				source.queuers.push(node.name)
+			}
 		}
 	}
 	/** @type {Map<string, number>} */
@@ -108,7 +73,9 @@ export function compile(definition) {
 	/** @type {string[]} */
 	const sorted = []
 	for (const root of nodes) {
-		if (marks.has(root.name)) continue
+		if (marks.has(root.name)) {
+			continue
+		}
 		marks.set(root.name, 1)
 		const path = [ root.name ]
 		const cursors = [ 0 ]
@@ -127,10 +94,14 @@ export function compile(definition) {
 			cursors[top] = cursor + 1
 			const dep = /** @type {string} */(node.deps[cursor])/**/
 			const mark = marks.get(dep)
-			if (mark == 2) continue
-			if (mark == 1) throw Error(
-				`Circular dependency: ${[ ...path.slice(path.indexOf(dep)), dep ].join(" -> ")}`
-			)
+			if (mark == 2) {
+				continue
+			}
+			if (mark == 1) {
+				throw Error(
+					`Circular dependency: ${[ ...path.slice(path.indexOf(dep)), dep ].join(" -> ")}`
+				)
+			}
 			marks.set(dep, 1)
 			path.push(dep)
 			cursors.push(0)
@@ -138,26 +109,6 @@ export function compile(definition) {
 	}
 	/** @type {Map<string, Set<string>>} */
 	const downstream = new Map()
-	/**
-	 * @param {string} name
-	 * @returns {Set<string>}
-	 */
-	function downstream_of(name) {
-		let found = downstream.get(name)
-		if (found) return found
-		found = new Set()
-		const stack = [ name ]
-		while (stack.length) {
-			const current = /** @type {string} */(stack.pop())/**/
-			for (const dependent of /** @type {ProgramNode} */(nodes_by_name.get(current))/**/.dependents) {
-				if (found.has(dependent)) continue
-				found.add(dependent)
-				stack.push(dependent)
-			}
-		}
-		downstream.set(name, found)
-		return found
-	}
 	/** @type {Map<string, ProgramEdge>} */
 	const edges = new Map()
 	for (const edge of definition.edges) {
@@ -249,4 +200,73 @@ export function compile(definition) {
 	}
 	programs.set(definition, program)
 	return program
+	/**
+	 * @param {string} name
+	 * @returns {Set<string>}
+	 */
+	function downstream_of(name) {
+		let found = downstream.get(name)
+		if (found) {
+			return found
+		}
+		found = new Set()
+		const stack = [ name ]
+		while (stack.length) {
+			const current = /** @type {string} */(stack.pop())/**/
+			for (const dependent of /** @type {ProgramNode} */(nodes_by_name.get(current))/**/.dependents) {
+				if (found.has(dependent)) {
+					continue
+				}
+				found.add(dependent)
+				stack.push(dependent)
+			}
+		}
+		downstream.set(name, found)
+		return found
+	}
+	/**
+	 * @param {unknown} target
+	 * @returns {string | undefined}
+	 */
+	function name_of(target) {
+		return typeof target == "string"
+			? by_name.has(target)
+				? target
+				: void 0
+			: by_ref.get(target)
+	}
+	/**
+	 * @param {unknown} target
+	 * @param {string} message
+	 * @returns {string}
+	 */
+	function resolve(target, message) {
+		const name = name_of(target)
+		if (name == null) {
+			throw Error(
+				message.replace("%s", describe(target))
+			)
+		}
+		return name
+	}
+	/**
+	 * @param {DefinitionNode} node
+	 * @returns {Record<string, "keep" | "queue" | "restart"> | undefined}
+	 */
+	function to_arrive(node) {
+		/** @type {Record<string, "keep" | "queue" | "restart"> | undefined} */
+		let arrive
+		for (const dep of node.deps) {
+			if (!/** @type {RefProbe} */(dep)/**/?.[ARRIVE]) {
+				continue
+			}
+			/** @type {Record<string, "keep" | "queue" | "restart">} */
+			const target = arrive ??= Object.create(null)
+			target[resolve(
+				to_ref(dep),
+				`Flow node "${node.name}" depends on %s, which is not added`
+			)] = /** @type {{ policy: "keep" | "queue" | "restart" }} */(/** @type {unknown} */(dep))/**/.policy
+		}
+		return arrive
+	}
 }

package/src/flow/graph.js

@@ -31,14 +31,18 @@ export function abandon(c, deps, race) {
 	)
 	while (stack.length) {
 		const name = /** @type {string} */(stack.pop())/**/
-		if (name == race || region.has(name)) continue
+		if (name == race || region.has(name)) {
+			continue
+		}
 		region.add(name)
 		stack.push(
 			...get_record(c, name).node.deps,
 			...c.program.sources.get(name) ?? []
 		)
 	}
-	if (!region.size) return
+	if (!region.size) {
+		return
+	}
 	const dead = new Set(region).add(race)
 	/** @type {string[]} */
 	const needed = []
@@ -51,25 +55,33 @@ export function abandon(c, deps, race) {
 			)
 			: [
 				...dependents,
-				...c.program.transitions.get(name) ?? []
+				.../** @type {string[]} */(c.program.transitions.get(name))/**/
 			]
 		if (targets.some(
 			target => !dead.has(target) && may_run(c, target, dead)
-		)) needed.push(name)
+		)) {
+			needed.push(name)
+		}
+	}
+	for (const name of needed) {
+		region.delete(name)
 	}
-	for (const name of needed) region.delete(name)
 	while (needed.length) {
 		const name = /** @type {string} */(needed.pop())/**/
 		for (const source of [
 			...get_record(c, name).node.deps,
 			...c.program.sources.get(name) ?? []
 		]) {
-			if (region.delete(source)) needed.push(source)
+			if (region.delete(source)) {
+				needed.push(source)
+			}
 		}
 	}
 	for (const name of region) {
 		const record = get_record(c, name)
-		if (settled_statuses.has(record.status)) continue
+		if (settled_statuses.has(record.status)) {
+			continue
+		}
 		record.backlog = []
 		record.backlog_head = 0
 		record.retrigger = false
@@ -89,7 +101,9 @@ export function abandon(c, deps, race) {
 		settle(c, name, "skipped", void 0, is_running)
 		record.abandoned = true
 	}
-	for (const name of region) release_unused(c, name, void 0)
+	for (const name of region) {
+		release_unused(c, name, void 0)
+	}
 }
 /**
  * @param {RunContext} c
@@ -99,19 +113,27 @@ export function abandon(c, deps, race) {
  * @returns {void}
  */
 export function enter(c, targets, source, force) {
-	if (c.run_status != "running" || !targets.length) return
+	if (c.run_status != "running" || !targets.length) {
+		return
+	}
 	/** @type {Set<string>} */
 	const touched = new Set()
 	for (const target of targets) {
-		for (const name of reset(c, target, true, force)) touched.add(name)
+		for (const name of reset(c, target, true, force)) {
+			touched.add(name)
+		}
 	}
 	for (const target of targets) {
 		const record = get_record(c, target)
 		record.activators.add(source)
 		record.activated = true
 	}
-	for (const target of targets) try_start(c, target)
-	for (const name of touched) try_start(c, name)
+	for (const target of targets) {
+		try_start(c, target)
+	}
+	for (const name of touched) {
+		try_start(c, name)
+	}
 }
 /**
  * @param {RunContext} c
@@ -189,14 +211,26 @@ function is_live(c, name, target, visited) {
 	const stack = [ name ]
 	while (stack.length) {
 		const current = /** @type {string} */(stack.pop())/**/
-		if (visited.has(current)) continue
+		if (visited.has(current)) {
+			continue
+		}
 		visited.add(current)
-		if (c.program.is_downstream(target, current)) continue
+		if (c.program.is_downstream(target, current)) {
+			continue
+		}
 		const record = get_record(c, current)
-		if (active_statuses.has(record.status)) return true
-		if (record.status != "idle") continue
-		if (record.activated) return true
-		for (const source of c.program.sources.get(current) ?? []) stack.push(source)
+		if (active_statuses.has(record.status)) {
+			return true
+		}
+		if (record.status != "idle") {
+			continue
+		}
+		if (record.activated) {
+			return true
+		}
+		for (const source of c.program.sources.get(current) ?? []) {
+			stack.push(source)
+		}
 	}
 	return false
 }
@@ -211,10 +245,14 @@ function kill(c, name, source) {
 		c,
 		() => {
 			const record = get_record(c, name)
-			if (c.run_status != "running" || record.status != "idle" || record.activated) return
+			if (c.run_status != "running" || record.status != "idle" || record.activated) {
+				return
+			}
 			const visited = new Set([ name, source ])
-			for (const other of c.program.sources.get(name) ?? []) {
-				if (other != source && is_live(c, other, name, visited)) return
+			for (const other of /** @type {string[]} */(c.program.sources.get(name))/**/) {
+				if (other != source && is_live(c, other, name, visited)) {
+					return
+				}
 			}
 			settle(c, name, "skipped", void 0)
 		}
@@ -226,7 +264,9 @@ function kill(c, name, source) {
  * @returns {void}
  */
 export function kill_transitions(c, name) {
-	for (const target of c.program.transitions.get(name) ?? []) kill(c, target, name)
+	for (const target of /** @type {string[]} */(c.program.transitions.get(name))/**/) {
+		kill(c, target, name)
+	}
 }
 /**
  * @param {RunContext} c
@@ -236,8 +276,12 @@ export function kill_transitions(c, name) {
  */
 function may_run(c, name, dead) {
 	const record = get_record(c, name)
-	if (settled_statuses.has(record.status)) return false
-	if (record.status != "idle" || record.activated) return true
+	if (settled_statuses.has(record.status)) {
+		return false
+	}
+	if (record.status != "idle" || record.activated) {
+		return true
+	}
 	return (c.program.sources.get(name) ?? []).some(
 		source => is_live(
 			c,
@@ -257,27 +301,37 @@ function may_run(c, name, dead) {
 export function reset(c, name, is_root, force) {
 	/** @type {Set<string>} */
 	const names = new Set()
-	/** @type {{ from: string | undefined, name: string }[]} */
-	const stack = [ { from: void 0, name } ]
+	/** @type {{ forward: boolean, from: string | undefined, name: string }[]} */
+	const stack = [
+		{ forward: false, from: void 0, name }
+	]
 	while (stack.length) {
-		const entry = /** @type {{ from: string | undefined, name: string }} */(stack.pop())/**/
+		const entry = /** @type {{ forward: boolean, from: string | undefined, name: string }} */(stack.pop())/**/
 		const node_name = entry.name
-		if (names.has(node_name)) continue
+		if (names.has(node_name)) {
+			continue
+		}
 		const node_record = get_record(c, node_name)
 		const arrive = entry.from == null ? void 0 : node_record.node.arrive?.[entry.from]
-		if (arrive == "keep" || arrive == "queue") continue
+		if (arrive == "keep" || arrive == "queue") {
+			continue
+		}
 		if (entry.from != null && node_record.status == "done") {
 			const from = get_record(c, entry.from)
 			if (node_record.node.options.join == "race"
 				? from.status != "done"
-				: from.fatal && from.node.options.release) continue
+				: from.fatal && from.node.options.release) {
+				continue
+			}
 		}
 		const overlap = arrive == "restart" ? "restart" : node_record.node.options.overlap ?? "restart"
 		const keeps = overlap == "restart"
 			? node_record.status == "running"
 			: active_statuses.has(node_record.status) || holds_backlog(node_record)
 		if (keeps && !(force && node_name == name)) {
-			if (overlap != "ignore") node_record.retrigger = true
+			if (overlap != "ignore" && !entry.forward) {
+				node_record.retrigger = true
+			}
 			continue
 		}
 		names.add(node_name)
@@ -285,26 +339,38 @@ export function reset(c, name, is_root, force) {
 		const next = [
 			...get_record(c, node_name).node.dependents
 		]
-		for (const target of c.program.forward.get(node_name) ?? []) {
+		const dependent_count = next.length
+		for (const target of /** @type {string[]} */(c.program.forward.get(node_name))/**/) {
 			const target_record = get_record(c, target)
 			const is_owned = target_record.activators.has(node_name) || target_record.activators.has("*")
-			if (is_owned || !target_record.activated && settled_statuses.has(target_record.status)) next.push(target)
-		}
-		for (let i = next.length; i--;) stack.push(
-			{
-				from: node_name,
-				name: /** @type {string} */(next[i])/**/
+			if (is_owned || !target_record.activated && settled_statuses.has(target_record.status)) {
+				next.push(target)
 			}
-		)
+		}
+		for (let i = next.length; i--;) {
+			stack.push(
+				{
+					forward: i >= dependent_count,
+					from: node_name,
+					name: /** @type {string} */(next[i])/**/
+				}
+			)
+		}
 	}
 	for (const node_name of names) {
 		const record = get_record(c, node_name)
 		clear_record(c, record)
-		if (node_name == name && is_root) continue
+		if (node_name == name && is_root) {
+			continue
+		}
 		for (const source of record.activators) {
-			if (names.has(source)) record.activators.delete(source)
+			if (names.has(source)) {
+				record.activators.delete(source)
+			}
+		}
+		if ((c.program.sources.get(node_name) ?? []).some(source => names.has(source))) {
+			record.activators.delete("*")
 		}
-		if ((c.program.sources.get(node_name) ?? []).some(source => names.has(source))) record.activators.delete("*")
 		record.activated = !c.incoming.has(node_name) || record.activators.size > 0
 	}
 	return names

package/src/flow/index.js

@@ -9,14 +9,20 @@ export default /** @type {import("../../public.js").FlowFunction} */(/** @type {
 	 */
 	function(options = {}) {
 		for (const key of Object.keys(options)) {
-			if (key != "concurrency" && key != "maxSteps") throw TypeError(`Unknown flow option "${key}"`)
+			if (key != "concurrency" && key != "maxSteps") {
+				throw TypeError(`Unknown flow option "${key}"`)
+			}
+		}
+		if (options.concurrency != null && !is_count(options.concurrency)) {
+			throw TypeError(
+				"The concurrency of a flow must be a positive integer or Infinity"
+			)
+		}
+		if (options.maxSteps != null && !is_count(options.maxSteps)) {
+			throw TypeError(
+				"The maxSteps of a flow must be a positive integer or Infinity"
+			)
 		}
-		if (options.concurrency != null && !is_count(options.concurrency)) throw TypeError(
-			"The concurrency of a flow must be a positive integer or Infinity"
-		)
-		if (options.maxSteps != null && !is_count(options.maxSteps)) throw TypeError(
-			"The maxSteps of a flow must be a positive integer or Infinity"
-		)
 		return create_builder(
 			{
 				count: 0,

package/src/flow/items.js

@@ -17,12 +17,16 @@ async function collect_items(iterator, signal) {
 		for (;;) {
 			const step = iterator.next()
 			const { done, value } = signal ? await race_signal(step, signal) : await step
-			if (done) return items
+			if (done) {
+				return items
+			}
 			items.push(value)
 		}
 	} finally {
-		if (signal?.aborted) await iterator.return?.()
-			.catch(noop)
+		if (signal?.aborted) {
+			await iterator.return?.()
+				.catch(noop)
+		}
 	}
 }
 /**
@@ -31,9 +35,11 @@ async function collect_items(iterator, signal) {
  */
 export function each(target) {
 	const is_flow = !!target?.[DEFINITION]
-	if (!is_flow && typeof target != "function") throw TypeError(
-		"flow.each() needs a function or a flow"
-	)
+	if (!is_flow && typeof target != "function") {
+		throw TypeError(
+			"flow.each() needs a function or a flow"
+		)
+	}
 	/** @type {TaskRef} */
 	const run_all = is_flow
 		? async (/** @type {unknown} */ items) => Promise.all(
@@ -68,7 +74,7 @@ export function each(target) {
 export async function run_each(c, record, token) {
 	const { node } = record
 	const { name, options } = node
-	const [ source, ...rest ] = node.deps.length ? args_of(c, record) : [ c.state ]
+	const [ source, ...rest ] = node.deps.length ? args_of(record) : [ c.state ]
 	const parent = /** @type {AbortController} */(record.controller)/**/.signal
 	/** @type {unknown[]} */
 	let items
@@ -79,10 +85,14 @@ export async function run_each(c, record, token) {
 			: to_items(source, parent)
 		items = Array.isArray(collected) ? collected : await collected
 	} catch (error) {
-		if (token != record.token || parent.aborted) return { kind: "stale" }
+		if (token != record.token || parent.aborted) {
+			return { kind: "stale" }
+		}
 		return { kind: "error", value: error }
 	}
-	if (token != record.token) return { kind: "stale" }
+	if (token != record.token) {
+		return { kind: "stale" }
+	}
 	record.item_list = items
 	record.item_source = source
 	const controller = new AbortController()
@@ -97,6 +107,35 @@ export async function run_each(c, record, token) {
 	/** @type {{ error: unknown, index: number | undefined } | undefined} */
 	let failure
 	let next = 0
+	const workers = Math.min(
+		options.concurrency ?? Infinity,
+		items.length
+	)
+	try {
+		await Promise.all(
+			Array.from({ length: workers }, worker)
+		)
+	} finally {
+		unlink()
+	}
+	if (token != record.token) {
+		return { kind: "stale" }
+	}
+	if (failure) {
+		return {
+			index: failure.index,
+			items: true,
+			kind: "error",
+			value: failure.error
+		}
+	}
+	const values = items.map(
+		(_, index) => done[index]?.value
+	)
+	if (!done.some(item => item?.failed) && !failed_sub_keys(record).length) {
+		record.items = void 0
+	}
+	return { kind: "done", value: values }
 	/**
 	 * @param {unknown} error
 	 * @param {number | undefined} index
@@ -108,10 +147,13 @@ export async function run_each(c, record, token) {
 			new CancelError("Another item failed")
 		)
 	}
+	/** @returns {Promise<void>} */
 	async function worker() {
 		while (!failure && next < items.length) {
 			const index = next++
-			if (done[index]) continue
+			if (done[index]) {
+				continue
+			}
 			const item = items[index]
 			const key = String(index)
 			const outcome = await run_attempts(
@@ -143,7 +185,9 @@ export async function run_each(c, record, token) {
 						)
 					)
 			)
-			if (token != record.token || outcome.kind == "stale") return
+			if (token != record.token || outcome.kind == "stale") {
+				return
+			}
 			if (outcome.kind == "done") {
 				if (is_sentinel(outcome.value)) {
 					stop(
@@ -172,14 +216,20 @@ export async function run_each(c, record, token) {
 							record.runs.get(key)
 						)
 					)
-					if (token != record.token) return
-					if (is_sentinel(value)) throw TypeError(
-						`The catch of flow node "${name}" cannot return goto() or skip() for an item`
-					)
+					if (token != record.token) {
+						return
+					}
+					if (is_sentinel(value)) {
+						throw TypeError(
+							`The catch of flow node "${name}" cannot return goto() or skip() for an item`
+						)
+					}
 					c.errors[name + "." + key] = outcome.value
 					done[index] = { value }
 				} catch (catch_error) {
-					if (token == record.token) stop(catch_error, index)
+					if (token == record.token) {
+						stop(catch_error, index)
+					}
 					return
 				}
 			} else if (options.optional) {
@@ -191,29 +241,6 @@ export async function run_each(c, record, token) {
 			}
 		}
 	}
-	const workers = Math.min(
-		options.concurrency ?? Infinity,
-		items.length
-	)
-	try {
-		await Promise.all(
-			Array.from({ length: workers }, worker)
-		)
-	} finally {
-		unlink()
-	}
-	if (token != record.token) return { kind: "stale" }
-	if (failure) return {
-		index: failure.index,
-		items: true,
-		kind: "error",
-		value: failure.error
-	}
-	const values = items.map(
-		(_, index) => done[index]?.value
-	)
-	if (!done.some(item => item?.failed) && !failed_sub_keys(record).length) record.items = void 0
-	return { kind: "done", value: values }
 }
 /**
  * @param {unknown} source
@@ -221,13 +248,19 @@ export async function run_each(c, record, token) {
  * @returns {unknown[] | Promise<unknown[]>}
  */
 export function to_items(source, signal) {
-	if (source == null) return []
-	if (typeof /** @type {Partial<Iterable<unknown>>} */(source)/**/[Symbol.iterator] == "function") return Array.from(
-		/** @type {Iterable<unknown>} */(source)/**/
-	)
-	if (typeof /** @type {Partial<AsyncIterable<unknown>>} */(source)/**/[Symbol.asyncIterator] != "function") throw TypeError(
-		"flow.each() needs an iterable or an async iterable as the first dependency"
-	)
+	if (source == null) {
+		return []
+	}
+	if (typeof /** @type {Partial<Iterable<unknown>>} */(source)/**/[Symbol.iterator] == "function") {
+		return Array.from(
+			/** @type {Iterable<unknown>} */(source)/**/
+		)
+	}
+	if (typeof /** @type {Partial<AsyncIterable<unknown>>} */(source)/**/[Symbol.asyncIterator] != "function") {
+		throw TypeError(
+			"flow.each() needs an iterable or an async iterable as the first dependency"
+		)
+	}
 	return collect_items(
 		/** @type {AsyncIterable<unknown>} */(source)/**/[Symbol.asyncIterator](),
 		signal