@nmnmcc/ability 1.0.0 → 2.0.0

package/src/internal/nodes.ts

@@ -0,0 +1,404 @@
+/**
+ * The nodes of a condition. Each node is a class, and only its constructor
+ * makes one, also when a condition comes from JSON. The constructor checks the
+ * data of the node and works out three facts once:
+ * - `size`: the number of nodes, with a shared child counted for each place;
+ * - `depth`: the number of levels;
+ * - `opaque`: the node has a predicate.
+ *
+ * The constructor stops a node that goes past `conditionNodes` or
+ * `conditionDepth`. So a walk over any condition visits at most
+ * `conditionNodes` nodes and goes at most `conditionDepth` levels down, and it
+ * needs no memo.
+ *
+ * The facts are private fields, so `Equal` and `Hash` do not read them: two
+ * nodes with the same data are equal.
+ */
+// A predicate gives an Effect with an error type and a service type that the
+// nodes do not know, so they are `unknown` here.
+// @effect-diagnostics anyUnknownInErrorContext:off
+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 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"
+
+/** A fixed value. */
+export interface Literal {
+	readonly _tag: "Literal"
+	readonly value: Scalar
+}
+
+/** A field of the principal. */
+export interface PrincipalRef {
+	readonly _tag: "Principal"
+	readonly path: string
+}
+
+export type Operand = Literal | PrincipalRef
+
+const operands = Data.taggedEnum<Operand>()
+
+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 ||
+	typeof value === "string" ||
+	typeof value === "number" ||
+	typeof value === "boolean"
+
+/**
+ * Checks a field path: a string with at most `fieldPathParts` parts. A longer
+ * path is never a field of a resource or of the principal.
+ */
+const checkPath = (path: unknown): string => {
+	if (typeof path !== "string") {
+		throw new Error("A field path must be a string")
+	}
+	const parts = path.split(".", Limits.fieldPathParts + 1).length
+	if (parts > Limits.fieldPathParts) {
+		throw Limits.exceeded(
+			"A field path",
+			"fieldPathParts",
+			"parts",
+			parts,
+			Limits.fieldPathParts,
+		)
+	}
+	return path
+}
+
+/** Checks an operand, and gives a new one with only its data. */
+const checkOperand = (operand: unknown): Operand => {
+	if (hasProperty(operand, "_tag")) {
+		if (
+			operand._tag === "Literal" &&
+			hasProperty(operand, "value") &&
+			isScalar(operand.value)
+		) {
+			return literal(operand.value)
+		}
+		if (operand._tag === "Principal" && hasProperty(operand, "path")) {
+			return principalRef(checkPath(operand.path))
+		}
+	}
+	throw new Error(
+		"An operand must be a fixed scalar value or a field of the principal",
+	)
+}
+
+const checkOperands = (values: unknown): ReadonlyArray<Operand> => {
+	if (!Array.isArray(values)) {
+		throw new Error("A list of operands must be an array")
+	}
+	return Object.freeze(Arr.map(Array.from(values), checkOperand))
+}
+
+interface Facts {
+	readonly size: number
+	readonly depth: number
+	readonly opaque: boolean
+}
+
+const leaf: Facts = { size: 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) {
+		throw Limits.exceeded(
+			"A condition",
+			"conditionNodes",
+			"nodes",
+			size,
+			Limits.conditionNodes,
+		)
+	}
+	const depth =
+		1 + Arr.reduce(children, 0, (top, child) => Math.max(top, child.depth))
+	if (depth > Limits.conditionDepth) {
+		throw Limits.exceeded(
+			"A condition",
+			"conditionDepth",
+			"levels",
+			depth,
+			Limits.conditionDepth,
+		)
+	}
+	return {
+		size,
+		depth,
+		opaque: Arr.some(children, (child) => child.opaque),
+	}
+}
+
+/** The base of every node. It keeps the facts. */
+abstract class Base extends Data.Class {
+	/**
+	 * The JSON form of the node, for `JSON.stringify`. A number that JSON can
+	 * not hold, as `Infinity`, becomes an object that no decoder takes, in
+	 * place of `null`, which would change the test.
+	 */
+	toJSON(): unknown {
+		return toJson(this as unknown as Node)
+	}
+
+	readonly #facts: Facts
+
+	constructor(props: object, facts: Facts) {
+		super(props as never)
+		this.#facts = facts
+	}
+
+	/** The number of nodes, with a shared child counted for each place. */
+	get size(): number {
+		return this.#facts.size
+	}
+
+	/** The number of levels. */
+	get depth(): number {
+		return this.#facts.depth
+	}
+
+	/** The node has a predicate. */
+	get opaque(): boolean {
+		return this.#facts.opaque
+	}
+}
+
+/** Always true. */
+export class True extends Base {
+	readonly _tag = "True"
+	constructor() {
+		super({}, leaf)
+	}
+}
+
+/** Always false. */
+export class False extends Base {
+	readonly _tag = "False"
+	constructor() {
+		super({}, leaf)
+	}
+}
+
+/** Compares a field with a value. */
+export class Compare extends Base {
+	readonly _tag = "Compare"
+	declare readonly op: CompareOperator
+	declare readonly field: string
+	declare readonly value: Operand
+	constructor(props: {
+		readonly op: CompareOperator
+		readonly field: string
+		readonly value: Operand
+	}) {
+		if (!compareOperators.includes(props.op)) {
+			throw new Error(`"${String(props.op)}" is not a compare operator`)
+		}
+		super(
+			{
+				op: props.op,
+				field: checkPath(props.field),
+				value: checkOperand(props.value),
+			},
+			leaf,
+		)
+	}
+}
+
+/** True when a field is equal to one of the values. */
+export class In extends Base {
+	readonly _tag = "In"
+	declare readonly field: string
+	declare readonly values: ReadonlyArray<Operand>
+	constructor(props: {
+		readonly field: string
+		readonly values: ReadonlyArray<Operand>
+	}) {
+		super(
+			{ field: checkPath(props.field), values: checkOperands(props.values) },
+			leaf,
+		)
+	}
+}
+
+/** True when a field is not `null` and not missing. */
+export class Exists extends Base {
+	readonly _tag = "Exists"
+	declare readonly field: string
+	constructor(props: { readonly field: string }) {
+		super({ field: checkPath(props.field) }, leaf)
+	}
+}
+
+/** True when the path of the resource starts with the prefix. */
+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 checkChildren = (conditions: unknown): ReadonlyArray<Node> => {
+	if (!Array.isArray(conditions)) {
+		throw new Error("The children of a node must be an array")
+	}
+	const children = Array.from(conditions as ReadonlyArray<unknown>)
+	if (!Arr.every(children, isNode)) {
+		throw notNode()
+	}
+	return Object.freeze(children)
+}
+
+export class And extends Base {
+	readonly _tag = "And"
+	declare readonly conditions: ReadonlyArray<Node>
+	constructor(conditions: ReadonlyArray<Node>) {
+		const children = checkChildren(conditions)
+		super({ conditions: children }, factsOf(children))
+	}
+}
+
+export class Or extends Base {
+	readonly _tag = "Or"
+	declare readonly conditions: ReadonlyArray<Node>
+	constructor(conditions: ReadonlyArray<Node>) {
+		const children = checkChildren(conditions)
+		super({ conditions: children }, factsOf(children))
+	}
+}
+
+export class Not extends Base {
+	readonly _tag = "Not"
+	declare readonly condition: Node
+	constructor(condition: Node) {
+		if (!isNode(condition)) {
+			throw notNode()
+		}
+		super({ condition }, factsOf([condition]))
+	}
+}
+
+/** The test of a predicate, with no types. */
+export type Run = (
+	value: unknown,
+	principal: unknown,
+) => Effect.Effect<boolean, unknown, unknown>
+
+/**
+ * A test that runs an `Effect`. Its test takes inputs of the type `never`, so
+ * no code can call it with a value of the wrong type: `Condition.evaluate`
+ * checks the input. Use {@link runOf} inside the library.
+ */
+export class Predicate extends Base {
+	readonly _tag = "Predicate"
+	declare readonly name: string
+	declare readonly run: (
+		value: never,
+		principal: never,
+	) => Effect.Effect<boolean, unknown, unknown>
+	constructor(props: { readonly name: string; readonly run: Run }) {
+		if (typeof props.name !== "string" || typeof props.run !== "function") {
+			throw new Error("A predicate needs a name and a test")
+		}
+		super(
+			{ name: props.name, run: props.run },
+			{ size: 1, depth: 1, opaque: true },
+		)
+	}
+}
+
+/** Gives the test of a predicate, with no types. */
+export const runOf = (node: Predicate): Run => node.run as Run
+
+/** A node of a condition. */
+export type Node =
+	True | False | Compare | In | Exists | Under | And | Or | Not | Predicate
+
+const operandJson = (operand: Operand): unknown =>
+	operand._tag === "Literal"
+		? {
+				_tag: "Literal",
+				// JSON has no `Infinity`, `-Infinity` or `NaN`. Such a number
+				// becomes an object that the decoder does not take.
+				value:
+					typeof operand.value === "number" && !Number.isFinite(operand.value)
+						? { nonFinite: String(operand.value) }
+						: operand.value,
+			}
+		: { _tag: "Principal", path: operand.path }
+
+/** Gives the JSON form of a condition with no predicate. */
+export const toJson = (node: Node): unknown => {
+	switch (node._tag) {
+		case "True":
+		case "False":
+			return { _tag: node._tag }
+		case "Compare":
+			return {
+				_tag: "Compare",
+				op: node.op,
+				field: node.field,
+				value: operandJson(node.value),
+			}
+		case "In":
+			return {
+				_tag: "In",
+				field: node.field,
+				values: Arr.map(node.values, operandJson),
+			}
+		case "Exists":
+			return { _tag: "Exists", field: node.field }
+		case "Under":
+			return { _tag: "Under", prefix: Arr.map(node.prefix, operandJson) }
+		case "And":
+		case "Or":
+			return { _tag: node._tag, conditions: Arr.map(node.conditions, toJson) }
+		case "Not":
+			return { _tag: "Not", condition: toJson(node.condition) }
+		case "Predicate":
+			throw new Error(
+				`The predicate "${node.name}" can not become JSON. A condition with a predicate has no JSON form.`,
+			)
+	}
+}
+
+/** Tests if a value is a node. Only a constructor of a node makes one. */
+export const isNode = (u: unknown): u is Node => u instanceof Base
+
+const notNode = (): Error =>
+	new Error(
+		"A condition must be made with a builder or a function of Condition. A plain object is not a condition",
+	)
+
+/** Gives a value as a node, or throws when it is not a node. */
+export const toNode = (u: unknown): Node => {
+	if (!isNode(u)) {
+		throw notNode()
+	}
+	return u
+}
+
+export const always: Node = new True()
+
+export const never: Node = new False()

package/src/internal/patterns.ts

@@ -0,0 +1,211 @@
+/**
+ * Field patterns, as in `settings.*`, `secret*` or `**.secret`. A pattern is
+ * a list of parts with dots between them:
+ * - A name with no star matches that name.
+ * - A part with stars matches a name, and each star matches any text with no
+ *   dot, as `secret*` matches `secretKey`.
+ * - `**` matches any number of names, also none. It must be a whole part.
+ *
+ * A pattern that matches a field matches each field below it too. So `pay`
+ * matches `pay.amount`, as `pay.**` does.
+ *
+ * The match goes one name at a time, and it keeps the set of places in the
+ * pattern that it may be at. It does not go back, so the time is at most the
+ * number of names times the number of parts.
+ */
+import * as Arr from "effect/Array"
+import * as Result from "effect/Result"
+import * as Catalog from "./catalog.ts"
+import * as Limits from "./limits.ts"
+
+/** One part of a pattern. */
+export type Part =
+	| { readonly _tag: "Name"; readonly name: string }
+	/** The texts between the stars of the part. */
+	| { readonly _tag: "Glob"; readonly pieces: ReadonlyArray<string> }
+	| { readonly _tag: "Globstar" }
+
+/** A pattern, as a list of parts. Two `**` parts are never next to each other. */
+export type Pattern = ReadonlyArray<Part>
+
+const globstar: Part = { _tag: "Globstar" }
+
+const partOf = (text: string): Part =>
+	text === "**"
+		? globstar
+		: text.includes("*")
+			? { _tag: "Glob", pieces: text.split("*") }
+			: { _tag: "Name", name: text }
+
+/**
+ * Reads a pattern. It fails with the problem when the pattern has `**`
+ * inside a part, or has more parts than `patternParts`.
+ */
+export const parse = (text: string): Result.Result<Pattern, string> => {
+	const texts = text.split(".", Limits.patternParts + 1)
+	if (texts.length > Limits.patternParts) {
+		return Result.fail(
+			`The field pattern "${text}" has more than ${String(Limits.patternParts)} parts. The most is ${String(Limits.patternParts)}.`,
+		)
+	}
+	if (Arr.some(texts, (part) => part !== "**" && part.includes("**"))) {
+		return Result.fail(
+			`The field pattern "${text}" has "**" inside a part. "**" must be a whole part`,
+		)
+	}
+	// `a.**.**` matches what `a.**` matches.
+	return Result.succeed(
+		Arr.dedupeAdjacentWith(
+			Arr.map(texts, partOf),
+			(left, right) => left._tag === "Globstar" && right._tag === "Globstar",
+		),
+	)
+}
+
+/**
+ * Reads a pattern of a bound rule. The binding of the rule took the pattern,
+ * so a problem here is a defect.
+ */
+export const parseBound = (text: string): Pattern =>
+	Result.getOrThrowWith(parse(text), (problem) => new Error(problem))
+
+/** Tests if a name matches the pieces of a part with stars. */
+const globMatches = (pieces: ReadonlyArray<string>, name: string): boolean => {
+	const first = pieces[0]!
+	const last = pieces[pieces.length - 1]!
+	const middle = pieces.slice(1, -1)
+	if (
+		name.length < first.length + last.length ||
+		!name.startsWith(first) ||
+		!name.endsWith(last)
+	) {
+		return false
+	}
+	// Each piece in the middle is found as early as it can be. An earlier
+	// place never leaves less room for the pieces after it.
+	const end = name.length - last.length
+	const place = Arr.reduce(middle, first.length as number, (at, piece) => {
+		if (at < 0) {
+			return at
+		}
+		const found = name.indexOf(piece, at)
+		return found < 0 || found + piece.length > end ? -1 : found + piece.length
+	})
+	return place >= 0
+}
+
+/**
+ * Tests if a part matches one segment of a path. A part with stars matches
+ * any key of a record. A name matches a key of a record when the Schema of
+ * the keys takes it.
+ */
+const partFits = (part: Part, segment: Catalog.Segment): boolean => {
+	switch (part._tag) {
+		case "Globstar":
+			return true
+		case "Glob":
+			return typeof segment !== "string" || globMatches(part.pieces, segment)
+		case "Name":
+			return typeof segment === "string"
+				? part.name === segment
+				: Catalog.keyFits(segment, part.name)
+	}
+}
+
+/** The places of a match: the parts that it may take next. */
+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],
+		),
+	)
+
+const start = (pattern: Pattern): States => close(pattern, [0])
+
+/** Gives the places after one more segment. A `**` that takes it stays. */
+const step = (
+	pattern: Pattern,
+	states: States,
+	segment: Catalog.Segment,
+): States =>
+	close(
+		pattern,
+		Arr.flatMap(states, (state) => {
+			const part = pattern[state]
+			return part === undefined
+				? []
+				: part._tag === "Globstar"
+					? [state]
+					: partFits(part, segment)
+						? [state + 1]
+						: []
+		}),
+	)
+
+const isDone = (pattern: Pattern, states: States): boolean =>
+	states.includes(pattern.length)
+
+/**
+ * Tests if a pattern matches a field, or a field above it. The field is a
+ * list of names.
+ */
+export const matches = (
+	pattern: Pattern,
+	names: ReadonlyArray<string>,
+): boolean => {
+	const found = Arr.reduce(
+		names,
+		{ states: start(pattern), done: isDone(pattern, start(pattern)) },
+		(before, name) => {
+			if (before.done || before.states.length === 0) {
+				return before
+			}
+			const states = step(pattern, before.states, name)
+			return { states, done: isDone(pattern, states) }
+		},
+	)
+	return found.done
+}
+
+/**
+ * Tests if a pattern may match a field below a field, with more names after
+ * the names of the field.
+ */
+export const matchesBelow = (
+	pattern: Pattern,
+	names: ReadonlyArray<string>,
+): boolean =>
+	Arr.some(
+		Arr.reduce(names, start(pattern), (states, name) =>
+			step(pattern, states, name),
+		),
+		(state) => state < pattern.length,
+	)
+
+/** Tests if a pattern matches some field of a catalog. */
+export const fitsCatalog = (
+	pattern: Pattern,
+	catalog: Catalog.Catalog,
+): boolean => {
+	const below = (branch: Catalog.Branch, states: States): boolean =>
+		states.length > 0 &&
+		(Arr.some(branch.children, ([name, child]) => visit(child, name, states)) ||
+			(branch.key !== undefined &&
+				branch.keyBranch !== undefined &&
+				visit(branch.keyBranch, branch.key, states)))
+	const visit = (
+		branch: Catalog.Branch,
+		segment: Catalog.Segment,
+		before: States,
+	): boolean => {
+		const states = step(pattern, before, segment)
+		return (
+			(branch.field !== undefined && isDone(pattern, states)) ||
+			below(branch, states)
+		)
+	}
+	return below(catalog.root, start(pattern))
+}