@nmnmcc/ability 2.0.5 → 2.0.7

package/src/internal/nodes.ts

@@ -21,12 +21,31 @@ import * as Arr from "effect/Array"
 import * as Data from "effect/Data"
 import type * as Effect from "effect/Effect"
 import { hasProperty } from "effect/Predicate"
+import * as Schema from "effect/Schema"
 import * as Limits from "./limits.ts"
 
 /** A value that a condition can compare. */
 export type Scalar = string | number | boolean | null
 
-export type CompareOperator = "eq" | "ne" | "lt" | "lte" | "gt" | "gte"
+/** The operators of a `Compare` test. The decoders read this list too. */
+export const CompareOperator = Schema.Literals([
+	"eq",
+	"ne",
+	"lt",
+	"lte",
+	"gt",
+	"gte",
+])
+
+export type CompareOperator = typeof CompareOperator.Type
+
+/**
+ * Tests if a value is an operator. It reads the list of the Schema with
+ * `includes`: for a short list, this is about twice as fast as
+ * `Schema.is`, and a decoder tests each node of a large input.
+ */
+export const isCompareOperator = (u: unknown): u is CompareOperator =>
+	(CompareOperator.literals as ReadonlyArray<unknown>).includes(u)
 
 /** A fixed value. */
 export interface Literal {
@@ -49,15 +68,6 @@ export const literal = (value: Scalar): Literal => operands.Literal({ value })
 export const principalRef = (path: string): PrincipalRef =>
 	operands.Principal({ path })
 
-const compareOperators: ReadonlyArray<string> = [
-	"eq",
-	"ne",
-	"lt",
-	"lte",
-	"gt",
-	"gte",
-]
-
 /** Tests if a value is a scalar. Any number is one, also `NaN`. */
 export const isScalar = (value: unknown): value is Scalar =>
 	value === null ||
@@ -114,24 +124,39 @@ const checkOperands = (values: unknown): ReadonlyArray<Operand> => {
 
 interface Facts {
 	readonly size: number
+	readonly weight: number
 	readonly depth: number
 	readonly opaque: boolean
 }
 
-const leaf: Facts = { size: 1, depth: 1, opaque: false }
+const leaf: Facts = { size: 1, weight: 1, depth: 1, opaque: false }
 
-/** The facts of a node with children. It stops a node past the limits. */
-const factsOf = (children: ReadonlyArray<Node>): Facts => {
-	const size = Arr.reduce(children, 1, (total, child) => total + child.size)
-	if (size > Limits.conditionNodes) {
+/**
+ * The facts of a test with values, as `In` and `Under`. Each value counts in
+ * the weight, since a walk that reads the test reads its values too. It stops
+ * a test past the limits.
+ */
+const valuesFacts = (values: ReadonlyArray<Operand>): Facts =>
+	checkWeight({ ...leaf, weight: 1 + values.length })
+
+const checkWeight = (facts: Facts): Facts => {
+	if (facts.weight > Limits.conditionNodes) {
 		throw Limits.exceeded(
 			"A condition",
 			"conditionNodes",
-			"nodes",
-			size,
+			"nodes and values",
+			facts.weight,
 			Limits.conditionNodes,
 		)
 	}
+	return facts
+}
+
+/** The facts of a node with children. It stops a node past the limits. */
+const factsOf = (children: ReadonlyArray<Node>): Facts => {
+	const size = Arr.reduce(children, 1, (total, child) => total + child.size)
+	const weight = Arr.reduce(children, 1, (total, child) => total + child.weight)
+	checkWeight({ ...leaf, weight })
 	const depth =
 		1 + Arr.reduce(children, 0, (top, child) => Math.max(top, child.depth))
 	if (depth > Limits.conditionDepth) {
@@ -145,6 +170,7 @@ const factsOf = (children: ReadonlyArray<Node>): Facts => {
 	}
 	return {
 		size,
+		weight,
 		depth,
 		opaque: Arr.some(children, (child) => child.opaque),
 	}
@@ -173,6 +199,15 @@ abstract class Base extends Data.Class {
 		return this.#facts.size
 	}
 
+	/**
+	 * The number of nodes and of the values of their `In` and `Under` tests,
+	 * with a shared child counted for each place. A walk that reads the tests
+	 * does this much work, so the limits of the nodes count it.
+	 */
+	get weight(): number {
+		return this.#facts.weight
+	}
+
 	/** The number of levels. */
 	get depth(): number {
 		return this.#facts.depth
@@ -211,7 +246,7 @@ export class Compare extends Base {
 		readonly field: string
 		readonly value: Operand
 	}) {
-		if (!compareOperators.includes(props.op)) {
+		if (!isCompareOperator(props.op)) {
 			throw new Error(`"${String(props.op)}" is not a compare operator`)
 		}
 		super(
@@ -234,10 +269,8 @@ export class In extends Base {
 		readonly field: string
 		readonly values: ReadonlyArray<Operand>
 	}) {
-		super(
-			{ field: checkPath(props.field), values: checkOperands(props.values) },
-			leaf,
-		)
+		const values = checkOperands(props.values)
+		super({ field: checkPath(props.field), values }, valuesFacts(values))
 	}
 }
 
@@ -255,7 +288,8 @@ export class Under extends Base {
 	readonly _tag = "Under"
 	declare readonly prefix: ReadonlyArray<Operand>
 	constructor(props: { readonly prefix: ReadonlyArray<Operand> }) {
-		super({ prefix: checkOperands(props.prefix) }, leaf)
+		const prefix = checkOperands(props.prefix)
+		super({ prefix }, valuesFacts(prefix))
 	}
 }
 
@@ -323,7 +357,7 @@ export class Predicate extends Base {
 		}
 		super(
 			{ name: props.name, run: props.run },
-			{ size: 1, depth: 1, opaque: true },
+			{ size: 1, weight: 1, depth: 1, opaque: true },
 		)
 	}
 }

package/src/internal/patterns.ts

@@ -117,9 +117,13 @@ type States = ReadonlyArray<number>
 
 /** Adds the place after each `**`, since a `**` may match no names. */
 const close = (pattern: Pattern, states: States): States =>
-	Arr.dedupe(
-		Arr.flatMap(states, (state) =>
-			pattern[state]?._tag === "Globstar" ? [state, state + 1] : [state],
+	// A native `Set` keeps the first copy of each place, in order. It is
+	// faster than `Arr.dedupe`, and this is on the path of each match.
+	Array.from(
+		new Set(
+			Arr.flatMap(states, (state) =>
+				pattern[state]?._tag === "Globstar" ? [state, state + 1] : [state],
+			),
 		),
 	)
 

package/src/internal/policy-json.ts

@@ -136,13 +136,6 @@ export const encode = (
 		return toJson(node, (rule) => forms.get(rule))
 	})
 
-const algorithms: ReadonlyArray<string> = [
-	"denyOverrides",
-	"permitOverrides",
-	"firstApplicable",
-	"lastApplicable",
-]
-
 /** Reads a list of strings. */
 const readStrings = (
 	input: object,
@@ -374,7 +367,7 @@ const readTree = (
 	switch (tag) {
 		case "Rules": {
 			const algorithm = Json.readString(input, "algorithm", path)
-			if (!algorithms.includes(algorithm)) {
+			if (!PolicyNodes.isAlgorithm(algorithm)) {
 				throw Json.problem(
 					[...path, "algorithm"],
 					`"${algorithm}" is not a combining algorithm`,
@@ -392,7 +385,7 @@ const readTree = (
 				_tag: "Rules",
 				place,
 				size: 1 + found.length,
-				algorithm: algorithm as PolicyNodes.Algorithm,
+				algorithm,
 				rules: found,
 			})
 		}

package/src/internal/policy-nodes.ts

@@ -11,19 +11,27 @@
  */
 import * as Arr from "effect/Array"
 import * as Data from "effect/Data"
+import * as Schema from "effect/Schema"
 import * as Rule from "./rule.ts"
 import * as Limits from "./limits.ts"
 import * as Nodes from "./nodes.ts"
 
-export type Algorithm =
-	"denyOverrides" | "permitOverrides" | "firstApplicable" | "lastApplicable"
-
-const algorithms: ReadonlyArray<string> = [
+/** The combining algorithms of a list of rules. The decoder reads this list too. */
+export const Algorithm = Schema.Literals([
 	"denyOverrides",
 	"permitOverrides",
 	"firstApplicable",
 	"lastApplicable",
-]
+])
+
+export type Algorithm = typeof Algorithm.Type
+
+/**
+ * Tests if a value is a combining algorithm. It reads the list of the Schema
+ * with `includes`, as `Nodes.isCompareOperator` does.
+ */
+export const isAlgorithm = (u: unknown): u is Algorithm =>
+	(Algorithm.literals as ReadonlyArray<unknown>).includes(u)
 
 interface Facts {
 	readonly size: number
@@ -103,7 +111,7 @@ export class Rules extends Base {
 		readonly algorithm: Algorithm
 		readonly rules: ReadonlyArray<Rule.Rule>
 	}) {
-		if (!algorithms.includes(props.algorithm)) {
+		if (!isAlgorithm(props.algorithm)) {
 			throw new Error(
 				`"${String(props.algorithm)}" is not a combining algorithm`,
 			)
@@ -122,7 +130,8 @@ export class Rules extends Base {
 				size: Arr.reduce(
 					conditions,
 					1,
-					(total, when) => total + 1 + (when?.size ?? 0),
+					// A condition counts its nodes and the values of its tests.
+					(total, when) => total + 1 + (when?.weight ?? 0),
 				),
 				depth: 1,
 				opaque: Arr.some(conditions, (when) => when?.opaque ?? false),

package/src/internal/search.ts

@@ -196,12 +196,13 @@ interface Search {
 	 */
 	readonly members: Map<Nodes.In, Set<string>>
 	/**
-	 * The texts of the structure of the conditions that the search found to be
-	 * unsatisfiable. A condition with the same structure has the same free
-	 * fields, so its answer is the same. The set only grows, so the steps of a
-	 * search may share it. It is a native `Set`, as in {@link dedupeCells}.
+	 * The keys of the conditions that the search found to be unsatisfiable:
+	 * see `Algebra.keyOf`. A condition with the same structure has the same
+	 * free fields, so its answer is the same. The set only grows, so the steps
+	 * of a search may share it. It is a native `Set`, as in
+	 * {@link dedupeCells}.
 	 */
-	readonly failed: Set<string>
+	readonly failed: Set<string | Node>
 	readonly budget: number
 }
 
@@ -364,10 +365,12 @@ const searchNode = (
 	if (node._tag === "False") {
 		return { assignment: Option.none(), state }
 	}
-	// The text reads all of the node. The step before counted the size of a
-	// larger node, so the budget counts this work too.
-	const text = Algebra.structureText(node)
-	if (search.failed.has(text)) {
+	// The key reads at most a small part of the node: a node with very many
+	// nodes, or with very many values in its `In` tests, is its own key. A
+	// step reads the nodes but not the values, which `membersOf` keeps, so the
+	// budget counts the size.
+	const key = Algebra.keyOf(node)
+	if (search.failed.has(key)) {
 		return { assignment: Option.none(), state }
 	}
 	if (state.steps + node.size > search.budget) {
@@ -400,7 +403,7 @@ const searchNode = (
 		},
 	)
 	if (Option.isNone(result.assignment)) {
-		search.failed.add(text)
+		search.failed.add(key)
 	}
 	return result
 }

package/src/internal/trampoline.ts

@@ -0,0 +1,147 @@
+/**
+ * Walks that do not fill the stack.
+ *
+ * A walk is written one time, with the steps of a {@link Runner}, and a
+ * runner runs it:
+ * - {@link direct} runs each step at once, as a plain call does. It is fast,
+ *   and it is for an input with few levels.
+ * - {@link loop} puts each step into the run loop of an Effect. A step gives
+ *   the next step in place of calling it, and the loop runs one step after
+ *   the other, so the stack does not grow with the levels of the input. This
+ *   is a trampoline.
+ *
+ * {@link run} takes `direct` for an input with at most `directDepth` levels,
+ * and `loop` for a deeper one. A walk makes each call for a child through
+ * `suspend`, so the loop makes the step of the child only when it runs it.
+ */
+import * as Arr from "effect/Array"
+import * as Cause from "effect/Cause"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Option from "effect/Option"
+
+/**
+ * A step of a walk that gives an `A`. A runner of steps knows what a step
+ * is: the value itself for `direct`, and an Effect for `loop`. The type is
+ * only in the types.
+ */
+export interface Step<A> {
+	readonly "~Step": (_: never) => A
+}
+
+/** The steps that a walk may take. */
+export interface Runner {
+	readonly succeed: <A>(value: A) => Step<A>
+	/** The step that `step` makes, when the runner runs it. */
+	readonly suspend: <A>(step: () => Step<A>) => Step<A>
+	readonly map: <A, B>(step: Step<A>, f: (value: A) => B) => Step<B>
+	readonly flatMap: <A, B>(step: Step<A>, f: (value: A) => Step<B>) => Step<B>
+	/** Runs a step for each item, in order, and gives their values. */
+	readonly forEach: <A, B>(
+		items: ReadonlyArray<A>,
+		f: (item: A, index: number) => Step<B>,
+	) => Step<ReadonlyArray<B>>
+	/** Runs a step for each item, in order, up to the first `true`. */
+	readonly some: <A>(
+		items: ReadonlyArray<A>,
+		f: (item: A) => Step<boolean>,
+	) => Step<boolean>
+	/** Runs a step for each item, in order, up to the first `false`. */
+	readonly every: <A>(
+		items: ReadonlyArray<A>,
+		f: (item: A) => Step<boolean>,
+	) => Step<boolean>
+}
+
+// A step of `direct` is its value. The casts below only change the type.
+const value = <A>(step: Step<A>): A => step as unknown as A
+const step = <A>(value: A): Step<A> => value as unknown as Step<A>
+
+/** Runs each step at once, on the stack. */
+export const direct: Runner = {
+	succeed: step,
+	suspend: (make) => make(),
+	map: (from, f) => step(f(value(from))),
+	flatMap: (from, f) => f(value(from)),
+	forEach: (items, f) =>
+		step(Arr.map(items, (item, index) => value(f(item, index)))),
+	some: (items, f) => step(Arr.some(items, (item) => value(f(item)))),
+	every: (items, f) => step(Arr.every(items, (item) => value(f(item)))),
+}
+
+// A step of `loop` is an Effect with no error and no services. A failure of a
+// walk is a thrown error, which `run` gives back as it was.
+type Loop<A> = Effect.Effect<A>
+const effect = <A>(step: Step<A>): Loop<A> => step as unknown as Loop<A>
+const fromEffect = <A>(effect: Loop<A>): Step<A> => effect as unknown as Step<A>
+
+/** Runs each step in the run loop of an Effect, so a deep walk does not fill the stack. */
+export const loop: Runner = {
+	succeed: (value) => fromEffect(Effect.succeed(value)),
+	suspend: (make) => fromEffect(Effect.suspend(() => effect(make()))),
+	map: (from, f) => fromEffect(Effect.map(effect(from), f)),
+	flatMap: (from, f) =>
+		fromEffect(Effect.flatMap(effect(from), (value) => effect(f(value)))),
+	forEach: (items, f) =>
+		fromEffect(Effect.forEach(items, (item, index) => effect(f(item, index)))),
+	some: (items, f) =>
+		fromEffect(
+			Effect.map(
+				Effect.findFirst(items, (item) => effect(f(item))),
+				Option.isSome,
+			),
+		),
+	every: (items, f) =>
+		fromEffect(
+			Effect.map(
+				Effect.findFirst(items, (item) =>
+					Effect.map(effect(f(item)), (value) => !value),
+				),
+				Option.isNone,
+			),
+		),
+}
+
+/**
+ * The most levels of an input that `run` walks with `direct`. A level takes
+ * a few calls of the walk and of the runner on the stack, so this keeps the
+ * stack far from full, and most inputs take the fast way.
+ */
+export const directDepth = 200
+
+/**
+ * Gives the runner for an input with `depth` levels. The walks of a condition
+ * or a policy tree know the depth of the input from its node. A walk of an
+ * input with an unknown depth, as a decoder, takes `loop`.
+ */
+export const runnerFor = (depth: number): Runner =>
+	depth <= directDepth ? direct : loop
+
+/**
+ * Runs a walk at once, with the runner for `depth` levels, and gives its
+ * value. An error that a step throws comes out as it was, also from `loop`.
+ */
+export const run = <A>(depth: number, walk: (runner: Runner) => Step<A>): A =>
+	runWith(runnerFor(depth), walk)
+
+/** Runs a walk at once with a runner, as {@link run} does. */
+export const runWith = <A>(
+	runner: Runner,
+	walk: (runner: Runner) => Step<A>,
+): A => {
+	if (runner === direct) {
+		return value(walk(direct))
+	}
+	return Exit.match(Effect.runSyncExit(effect(walk(loop))), {
+		onSuccess: (result) => result,
+		onFailure: (cause) => {
+			throw Cause.squash(cause)
+		},
+	})
+}
+
+/**
+ * Gives the Effect of a step of `loop`, so a walk can go on in an Effect
+ * that runs a predicate.
+ */
+export const toEffect = <A>(step: Step<A>): Effect.Effect<A> => effect(step)