@nmnmcc/ability 2.0.2 → 2.0.4

package/src/internal/algebra.ts

@@ -259,8 +259,8 @@ const testUnder = (
 	})
 }
 
-/** Tests a condition with no predicate on a value. */
-export const evaluateSync = (node: Node, input: Input): boolean => {
+/** Tests a simple condition with no predicate on a value. */
+const testSync = (node: Node, input: Input): boolean => {
 	switch (node._tag) {
 		case "True":
 			return true
@@ -283,11 +283,11 @@ export const evaluateSync = (node: Node, input: Input): boolean => {
 		case "Under":
 			return testUnder(node.prefix, input)
 		case "And":
-			return Arr.every(node.conditions, (child) => evaluateSync(child, input))
+			return Arr.every(node.conditions, (child) => testSync(child, input))
 		case "Or":
-			return Arr.some(node.conditions, (child) => evaluateSync(child, input))
+			return Arr.some(node.conditions, (child) => testSync(child, input))
 		case "Not":
-			return !evaluateSync(node.condition, input)
+			return !testSync(node.condition, input)
 		case "Predicate":
 			// The types stop this. A predicate needs `evaluate`.
 			throw new Error(
@@ -297,38 +297,55 @@ export const evaluateSync = (node: Node, input: Input): boolean => {
 }
 
 /**
- * Tests a condition on a value. The children of `And` and `Or` run in order,
- * and they stop at the first child that gives the answer.
+ * Tests a simple condition on a value. The children of `And` and `Or` run in
+ * order, and they stop at the first child that gives the answer.
  */
-export const evaluate = (
+const test = (
 	node: Node,
 	input: Input,
 ): Effect.Effect<boolean, unknown, unknown> => {
 	if (!node.opaque) {
-		return Effect.sync(() => evaluateSync(node, input))
+		return Effect.sync(() => testSync(node, input))
 	}
 	switch (node._tag) {
 		case "Predicate":
 			return Nodes.runOf(node)(input.value, input.principal)
 		case "Not":
-			return Effect.map(evaluate(node.condition, input), (value) => !value)
+			return Effect.map(test(node.condition, input), (value) => !value)
 		case "And":
 			return Effect.map(
 				Effect.findFirst(node.conditions, (child) =>
-					Effect.map(evaluate(child, input), (value) => !value),
+					Effect.map(test(child, input), (value) => !value),
 				),
 				Option.isNone,
 			)
 		case "Or":
 			return Effect.map(
-				Effect.findFirst(node.conditions, (child) => evaluate(child, input)),
+				Effect.findFirst(node.conditions, (child) => test(child, input)),
 				Option.isSome,
 			)
 		default:
-			return Effect.sync(() => evaluateSync(node, input))
+			return Effect.sync(() => testSync(node, input))
 	}
 }
 
+/**
+ * Tests a condition with no predicate on a value. The test runs on the
+ * simple form of the condition with the principal in it, as a residual does.
+ * So a test reads only the fields that the residual reads: a read of a field
+ * that is not plain data is a defect, and a field that the answer does not
+ * need, as in `x AND False`, is not read.
+ */
+export const evaluateSync = (node: Node, input: Input): boolean =>
+	testSync(partial(node, input), input)
+
+/** Tests a condition on a value, as {@link evaluateSync} does. */
+export const evaluate = (
+	node: Node,
+	input: Input,
+): Effect.Effect<boolean, unknown, unknown> =>
+	Effect.suspend(() => test(partial(node, input), input))
+
 // The principal and the path
 
 /**

package/src/internal/analysis.ts

@@ -85,6 +85,8 @@ interface ResidualContext {
 	}
 	/** The resource of the kind, for the fields that a rule may grant. */
 	readonly descriptor: Resource.Descriptor
+	/** The test of `RuleData.fitsOf` for the catalog, for this request. */
+	readonly fits: (pattern: string) => boolean
 	/**
 	 * The condition of each rule, with the principal in it. They are made
 	 * first, from a flat list of the rules, so the walk does not go down the
@@ -241,6 +243,7 @@ interface PredicateContext {
 	readonly kind: string
 	readonly field: string | undefined
 	readonly descriptor: Resource.Descriptor
+	readonly fits: (pattern: string) => boolean
 }
 
 /** Tests if a rule that the request may use has a predicate. */
@@ -345,6 +348,7 @@ const scopedResiduals = (policy: Any, request: ScopedRequest): Scoped => {
 		field: request.field,
 		input,
 		descriptor,
+		fits: RuleData.fitsOf(descriptor.catalog),
 	}
 	const context: ResidualContext = {
 		...target,
@@ -378,6 +382,7 @@ const scopedResiduals = (policy: Any, request: ScopedRequest): Scoped => {
 					path: descriptor.path,
 				},
 				descriptor,
+				fits: RuleData.fitsOf(descriptor.catalog),
 				trace: undefined,
 			},
 			[],

package/src/internal/bind.ts

@@ -16,6 +16,7 @@ import * as Catalog from "./catalog.ts"
 import * as Limits from "./limits.ts"
 import * as Nodes from "./nodes.ts"
 import * as Patterns from "./patterns.ts"
+import * as Place from "./place.ts"
 import { withSuggestion } from "./suggest.ts"
 
 /** One problem of a rule or a policy, with its path. */
@@ -176,6 +177,36 @@ const fieldIssue = (
 			]
 }
 
+/**
+ * The issues of a field that a condition reads: a field that is not a field
+ * of every resource of the rule, or a field that is not plain data in one of
+ * them. A read of a value that is not plain data, as a getter of a class, is
+ * a defect in a decision. A residual may leave the read out, so the residual
+ * would say "yes" where the decision fails. So the binding does not take
+ * such a read: see `Catalog.Field.plain`.
+ */
+const readIssues = (
+	context: Context,
+	field: string,
+	at: ReadonlyArray<PropertyKey>,
+): ReadonlyArray<Issue> => {
+	const exists = fieldIssue(context, field, at)
+	if (exists.length > 0) {
+		return exists
+	}
+	return Arr.some(
+		context.named,
+		(descriptor) => !(Catalog.lookup(descriptor.catalog, field)?.plain ?? true),
+	)
+		? [
+				{
+					path: at,
+					issue: `A condition may not read the field "${field}". A value above it may be an object that does not have it as a data field, as a class with a getter, a date or a list. Use a predicate for it.`,
+				},
+			]
+		: []
+}
+
 /**
  * The issues of a field pattern: a pattern that does not parse, or that
  * matches no field of the resources of the rule, as a pattern with a mistake
@@ -190,24 +221,29 @@ const patternIssues = (
 	Result.match(Patterns.parse(pattern), {
 		onFailure: (issue) => [{ path: at, issue }],
 		onSuccess: (parsed) => {
-			// A rule with no known resource has an issue for that already.
+			// A rule with no known resource has an issue for that already. The
+			// pattern is checked on every kind, not only up to the first that it
+			// fits: a decision on a kind does this check, so the limit of the
+			// work below is a limit of the work of a decision too.
 			const fits =
 				known.length === 0 ||
-				Arr.some(known, (descriptor) => {
+				Arr.reduce(known, false, (before, descriptor) => {
 					const key = `${descriptor.kind}\u0000${pattern}`
-					return Option.getOrElse(MutableHashMap.get(memo.fits, key), () => {
-						// Each check of a pattern reads the fields of a catalog. The
-						// work of one binding has a limit, so very many patterns stop
-						// with one issue, and the policy does not load.
-						memo.work.steps +=
-							descriptor.catalog.fields.length * Math.max(parsed.length, 1)
-						if (memo.work.steps > Limits.searchSteps) {
-							return true
-						}
-						const found = Patterns.fitsCatalog(parsed, descriptor.catalog)
-						MutableHashMap.set(memo.fits, key, found)
-						return found
-					})
+					return (
+						Option.getOrElse(MutableHashMap.get(memo.fits, key), () => {
+							// Each check of a pattern reads the fields of a catalog. The
+							// work of one binding has a limit, so very many patterns stop
+							// with one issue, and the policy does not load.
+							memo.work.steps +=
+								descriptor.catalog.fields.length * Math.max(parsed.length, 1)
+							if (memo.work.steps > Limits.searchSteps) {
+								return true
+							}
+							const found = Patterns.fitsCatalog(parsed, descriptor.catalog)
+							MutableHashMap.set(memo.fits, key, found)
+							return found
+						}) || before
+					)
 				})
 			if (memo.work.steps > Limits.searchSteps && !memo.work.noted) {
 				memo.work.noted = true
@@ -471,7 +507,7 @@ const conditionIssues = (
 	const here = (issues: ReadonlyArray<Issue>) => under(context.memo, at, issues)
 	switch (node._tag) {
 		case "Compare": {
-			const exists = fieldIssue(context, node.field, ["field"])
+			const exists = readIssues(context, node.field, ["field"])
 			return here(
 				exists.length > 0
 					? exists
@@ -485,7 +521,7 @@ const conditionIssues = (
 			)
 		}
 		case "In": {
-			const exists = fieldIssue(context, node.field, ["field"])
+			const exists = readIssues(context, node.field, ["field"])
 			return here(
 				exists.length > 0
 					? exists
@@ -498,7 +534,7 @@ const conditionIssues = (
 			)
 		}
 		case "Exists":
-			return here(fieldIssue(context, node.field, ["field"]))
+			return here(readIssues(context, node.field, ["field"]))
 		case "Under":
 			return here(underIssues(context, node.prefix, []))
 		case "And":
@@ -630,15 +666,18 @@ export const treeIssues = (
 	// The rules come out of the tree first, and each one is checked after.
 	// A check of a condition goes down its levels, so a check inside the walk
 	// of the tree would go down the levels of both.
+	// The place of each rule shares the path of its parent, and the full path
+	// is made only when its rule is checked. A deep tree with very many rules
+	// would need very much memory for a full copy of the path of each rule.
 	const rulesOf = (
 		node: TreeNode,
-		path: ReadonlyArray<PropertyKey>,
+		place: Place.Place | undefined,
 		level: number,
-	): ReadonlyArray<Issue | readonly [RuleData, ReadonlyArray<PropertyKey>]> => {
+	): ReadonlyArray<Issue | readonly [RuleData, Place.Place]> => {
 		if (level > Limits.policyDepth) {
 			return [
 				{
-					path,
+					path: Place.pathOf(place),
 					issue: `A policy tree has more than ${String(Limits.policyDepth)} levels. The most is ${String(Limits.policyDepth)}.`,
 				},
 			]
@@ -647,25 +686,25 @@ export const treeIssues = (
 			case "Rules":
 				return Arr.map(
 					node.rules,
-					(rule, index) => [rule, [...path, "rules", index]] as const,
+					(rule, index) => [rule, Place.at(place, "rules", index)] as const,
 				)
 			case "All":
 			case "Any":
 			case "FirstOf":
 				return Arr.flatMap(node.policies, (child, index) =>
-					rulesOf(child, [...path, "policies", index], level + 1),
+					rulesOf(child, Place.at(place, "policies", index), level + 1),
 				)
 			case "Ceiling":
 				return [
-					...rulesOf(node.cap, [...path, "cap"], level + 1),
-					...rulesOf(node.policy, [...path, "policy"], level + 1),
+					...rulesOf(node.cap, Place.at(place, "cap"), level + 1),
+					...rulesOf(node.policy, Place.at(place, "policy"), level + 1),
 				]
 		}
 	}
 	const memo = makeMemo()
-	return Arr.flatMap(rulesOf(root, [], 1), (found) =>
+	return Arr.flatMap(rulesOf(root, undefined, 1), (found) =>
 		Array.isArray(found)
-			? ruleIssues(domain, found[0], found[1], memo)
+			? ruleIssues(domain, found[0], Place.pathOf(found[1]), memo)
 			: [found as Issue],
 	)
 }

package/src/internal/catalog.ts

@@ -129,6 +129,15 @@ export interface Field {
 	readonly listed: boolean
 	/** The field may hold parts that the Schema does not name, as a record may. */
 	readonly open: boolean
+	/**
+	 * A read of the field finds only plain data. It is `false` when a value
+	 * above the field may be an object that does not have it as a data field:
+	 * a class without the field, which may have a getter of that name, a
+	 * value such as a date or a list, or any object, as of `Schema.Unknown`.
+	 * A decode or a `make` copies a struct or a record into a plain object,
+	 * so a struct without the field gives `null` for it.
+	 */
+	readonly plain: boolean
 }
 
 /** A place in the tree of a catalog, with the places below it. */
@@ -185,8 +194,8 @@ const classStruct = (
 }
 
 /**
- * Gives the Schemas that a value at one place may fit: it opens unions,
- * `Schema.suspend` and classes. The open suspend nodes are in a native `Set`,
+ * Gives the Schemas that a value at one place may fit: it opens unions and
+ * `Schema.suspend`. A class stays a class: see {@link structOf}. The open suspend nodes are in a native `Set`,
  * because the walk must find a node by the node itself: `Equal` compares
  * Schema nodes by structure, and a recursive Schema has no end. A suspend
  * node that gives itself again, with no step on the path, gives nothing.
@@ -202,15 +211,19 @@ const alternatives = (
 			return open.has(ast)
 				? []
 				: alternatives(ast.thunk(), new Set([...open, ast]))
-		case "Declaration": {
-			const inner = classStruct(ast)
-			return inner === undefined ? [ast] : alternatives(inner, open)
-		}
 		default:
 			return [ast]
 	}
 }
 
+/** The struct of a Schema: a struct, or the struct of a class. */
+const structOf = (ast: SchemaAST.AST): SchemaAST.Objects | undefined =>
+	ast._tag === "Objects"
+		? ast
+		: ast._tag === "Declaration"
+			? classStruct(ast)
+			: undefined
+
 const hasCheck = (
 	checks: ReadonlyArray<SchemaAST.Check<never>>,
 	id: string,
@@ -223,8 +236,10 @@ const hasCheck = (
 	)
 
 /** A struct with named fields, or with the keys of a record. */
-const isStruct = (ast: SchemaAST.AST): ast is SchemaAST.Objects =>
-	ast._tag === "Objects" &&
+const isStruct = (
+	ast: SchemaAST.Objects | undefined,
+): ast is SchemaAST.Objects =>
+	ast !== undefined &&
 	(ast.propertySignatures.length > 0 || ast.indexSignatures.length > 0)
 
 /** The kinds of the values of a Schema that is not a struct. */
@@ -326,6 +341,8 @@ interface Place {
 	readonly missing: boolean
 	/** The value may be anything, as an extra field of a struct may be. */
 	readonly top: boolean
+	/** A read here finds only plain data: see {@link Field.plain}. */
+	readonly plain: boolean
 }
 
 const textOf = (path: ReadonlyArray<Segment>): string =>
@@ -333,16 +350,27 @@ const textOf = (path: ReadonlyArray<Segment>): string =>
 		typeof segment === "string" ? segment : "*",
 	).join(".")
 
-/** Gives the property of a struct with a name, if it has one. */
-const propertyOf = (
+/**
+ * The name of a property as a part of a path. A key of an object is a string,
+ * so a number key, as from `Schema.Record(Schema.Literal(1), ...)`, has the
+ * name `"1"`. A symbol key is not a field.
+ */
+const nameOf = (signature: SchemaAST.PropertySignature): string | undefined =>
+	typeof signature.name === "symbol" ? undefined : String(signature.name)
+
+/**
+ * The properties of a struct by name. A walk makes it one time for each
+ * struct of a place, so a struct with very many fields does not take a
+ * search for each name.
+ */
+const propertiesOf = (
 	struct: SchemaAST.Objects,
-	name: string,
-): SchemaAST.PropertySignature | undefined =>
-	Option.getOrUndefined(
-		Arr.findFirst(
-			struct.propertySignatures,
-			(signature) => signature.name === name,
-		),
+): HashMap.HashMap<string, SchemaAST.PropertySignature> =>
+	HashMap.fromIterable(
+		Arr.flatMap(struct.propertySignatures, (signature) => {
+			const name = nameOf(signature)
+			return name === undefined ? [] : [[name, signature] as const]
+		}),
 	)
 
 /** The names of the fields of the structs, in the order that they first come. */
@@ -352,8 +380,8 @@ const namesOf = (
 	Arr.dedupe(
 		Arr.flatMap(structs, (struct) =>
 			Arr.flatMap(struct.propertySignatures, (signature) => {
-				const name = signature.name
-				if (typeof name !== "string") {
+				const name = nameOf(signature)
+				if (name === undefined) {
 					return []
 				}
 				// A dot in a path is the step into a nested field. A field name with
@@ -377,10 +405,22 @@ const namesOf = (
  * very many fields before the walk is done.
  */
 const branchOf = (place: Place, count: { size: number }): Branch => {
-	const structs = Arr.filter(place.schemas, isStruct)
-	const values = Arr.filter(place.schemas, (schema) => !isStruct(schema))
+	const structs = Arr.filter(Arr.map(place.schemas, structOf), isStruct)
+	// The structs of classes. A value of a class is not copied into a plain
+	// object, so it keeps its getters and methods.
+	const classes = Arr.filter(
+		Arr.map(
+			Arr.filter(place.schemas, (schema) => schema._tag === "Declaration"),
+			structOf,
+		),
+		isStruct,
+	)
+	const values = Arr.filter(
+		place.schemas,
+		(schema) => !isStruct(structOf(schema)),
+	)
 	const valueKinds = Arr.reduce(values, noKinds, (kinds, schema) =>
-		joinKinds(kinds, kindsOf(schema)),
+		joinKinds(kinds, kindsOf(structOf(schema) ?? schema)),
 	)
 	const kinds = place.top
 		? anyKinds
@@ -412,6 +452,7 @@ const branchOf = (place: Place, count: { size: number }): Branch => {
 						structs.length > 0 ||
 						valueKinds.object ||
 						place.top,
+					plain: place.plain,
 				}
 	if (field !== undefined) {
 		count.size += 1
@@ -434,11 +475,12 @@ const branchOf = (place: Place, count: { size: number }): Branch => {
 			keyBranch: undefined,
 		}
 	}
+	const structProperties = Arr.map(structs, propertiesOf)
+	const classProperties = Arr.map(classes, propertiesOf)
 	const children = Arr.map(namesOf(structs), (name) => {
-		const properties = Arr.flatMap(structs, (struct) => {
-			const property = propertyOf(struct, name)
-			return property === undefined ? [] : [property]
-		})
+		const properties = Arr.flatMap(structProperties, (named) =>
+			Option.toArray(HashMap.get(named, name)),
+		)
 		const below: Place = {
 			path: [...place.path, name],
 			schemas: Arr.flatMap(properties, (property) =>
@@ -454,10 +496,11 @@ const branchOf = (place: Place, count: { size: number }): Branch => {
 			// with any value: only a decode takes extra fields away. A value
 			// that may be any object, as one of `Schema.Unknown` may, may have
 			// the name with any value too.
-			top:
-				place.top ||
-				valueKinds.object ||
-				Arr.some(structs, (struct) => propertyOf(struct, name) === undefined),
+			top: place.top || valueKinds.object || properties.length < structs.length,
+			plain:
+				place.plain &&
+				!valueKinds.object &&
+				Arr.every(classProperties, (named) => HashMap.has(named, name)),
 		}
 		return [name, branchOf(below, count)] as const
 	})
@@ -479,6 +522,10 @@ const branchOf = (place: Place, count: { size: number }): Branch => {
 			// A record may not have a given key.
 			missing: true,
 			top: place.top || valueKinds.object || records.length < structs.length,
+			plain:
+				place.plain &&
+				!valueKinds.object &&
+				Arr.every(classes, (struct) => struct.indexSignatures.length > 0),
 		},
 		count,
 	)
@@ -502,6 +549,7 @@ export const catalogOf = (ast: SchemaAST.AST): Catalog => {
 			schemas: alternatives(ast, new Set()),
 			missing: false,
 			top: false,
+			plain: true,
 		},
 		{ size: 0 },
 	)

package/src/internal/decide.ts

@@ -37,6 +37,8 @@ interface DecideContext {
 	readonly input: Condition.Input
 	/** The resource of the kind, for the fields that a rule may grant. */
 	readonly descriptor: Resource.Descriptor
+	/** The test of `RuleData.fitsOf` for the catalog, for this decision. */
+	readonly fits: (pattern: string) => boolean
 	/** The rules that were tested, for {@link explain}. */
 	readonly trace: Ref.Ref<Chunk.Chunk<Step>> | undefined
 }
@@ -282,6 +284,7 @@ const makeContext = (
 			path: descriptor.path,
 		},
 		descriptor,
+		fits: RuleData.fitsOf(descriptor.catalog),
 		trace,
 	}
 }

package/src/internal/place.ts

@@ -0,0 +1,32 @@
+/**
+ * The place of a part of an input, as a path that shares the path of its
+ * parent. A deep tree with very many rules would need very much memory for a
+ * full copy of the path of each rule, so a place keeps only its own parts and
+ * its parent. The full path is made only for a problem, in one walk up.
+ */
+import * as Arr from "effect/Array"
+import * as Option from "effect/Option"
+
+/** A place: its own parts of the path, after the path of its parent. */
+export interface Place {
+	readonly parent: Place | undefined
+	readonly parts: ReadonlyArray<PropertyKey>
+}
+
+/** The place below `parent` with more parts. */
+export const at = (
+	parent: Place | undefined,
+	...parts: ReadonlyArray<PropertyKey>
+): Place => ({ parent, parts })
+
+/** The full path of a place. The root, with no place, has the empty path. */
+export const pathOf = (place: Place | undefined): ReadonlyArray<PropertyKey> =>
+	Arr.flatten(
+		Arr.reverse(
+			Arr.unfold(place, (current) =>
+				current === undefined
+					? Option.none()
+					: Option.some([current.parts, current.parent] as const),
+			),
+		),
+	)