@nmnmcc/ability 0.2.0 → 1.0.0

package/dist/Ability.js

@@ -1,207 +0,0 @@
-import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import { AliasError as AliasError$1, AuthorizationError as AuthorizationError$1, ConditionError as ConditionError$1, QueryGenerationError as QueryGenerationError$1, RawRuleError as RawRuleError$1, RuleTypeId as RuleTypeId$1, SubjectDetectionError as SubjectDetectionError$1, SubjectTypeId as SubjectTypeId$1, TypeId as TypeId$1, actionsFor as actionsFor$1, check as check$1, createAliasResolver as createAliasResolver$1, define as define$1, detectSubjectType as detectSubjectType$1, fromRawRules as fromRawRules$1, isAbility as isAbility$1, isRule as isRule$1, isSubject as isSubject$1, make as make$1, permittedFields as permittedFields$1, possibleRulesFor as possibleRulesFor$1, relevantRuleFor as relevantRuleFor$1, rulesFor as rulesFor$1, subject as subject$1, toRawRules as toRawRules$1, unwrapSubject as unwrapSubject$1, update as update$1 } from "./internal/ability.js";
-//#region src/Ability.ts
-var Ability_exports = /* @__PURE__ */ __exportAll({
-	AliasError: () => AliasError,
-	AuthorizationError: () => AuthorizationError,
-	ConditionError: () => ConditionError,
-	QueryGenerationError: () => QueryGenerationError,
-	RawRuleError: () => RawRuleError,
-	RuleTypeId: () => RuleTypeId,
-	SubjectDetectionError: () => SubjectDetectionError,
-	SubjectTypeId: () => SubjectTypeId,
-	TypeId: () => TypeId,
-	actionsFor: () => actionsFor,
-	check: () => check,
-	createAliasResolver: () => createAliasResolver,
-	define: () => define,
-	detectSubjectType: () => detectSubjectType,
-	fromRawRules: () => fromRawRules,
-	isAbility: () => isAbility,
-	isRule: () => isRule,
-	isSubject: () => isSubject,
-	make: () => make,
-	permittedFields: () => permittedFields,
-	possibleRulesFor: () => possibleRulesFor,
-	relevantRuleFor: () => relevantRuleFor,
-	rulesFor: () => rulesFor,
-	subject: () => subject,
-	toRawRules: () => toRawRules,
-	unwrapSubject: () => unwrapSubject,
-	update: () => update
-});
-/**
-* @since 0.1.0
-* @category Type Ids
-*/
-const TypeId = TypeId$1;
-/**
-* @since 0.1.0
-* @category Type Ids
-*/
-const SubjectTypeId = SubjectTypeId$1;
-/**
-* Unique identifier for `Rule` values.
-*
-* @since 0.1.0
-* @category Type Ids
-*/
-const RuleTypeId = RuleTypeId$1;
-/**
-* @since 0.1.0
-* @category Errors
-*/
-const AuthorizationError = AuthorizationError$1;
-/**
-* @since 0.1.0
-* @category Errors
-*/
-const ConditionError = ConditionError$1;
-/**
-* @since 0.1.0
-* @category Errors
-*/
-const RawRuleError = RawRuleError$1;
-/**
-* @since 0.1.0
-* @category Errors
-*/
-const SubjectDetectionError = SubjectDetectionError$1;
-/**
-* @since 0.1.0
-* @category Errors
-*/
-const AliasError = AliasError$1;
-/**
-* @since 0.1.0
-* @category Errors
-*/
-const QueryGenerationError = QueryGenerationError$1;
-/**
-* Creates an action resolver for an alias map.
-*
-* @since 0.1.0
-* @category Constructors
-*/
-const createAliasResolver = createAliasResolver$1;
-/**
-* Defines an immutable Ability from a generator-based rule program.
-*
-* @since 0.1.0
-* @category Constructors
-*/
-const define = define$1;
-/**
-* Constructs an Ability directly from rules.
-*
-* @since 0.1.0
-* @category Constructors
-*/
-const make = make$1;
-/**
-* Constructs an Ability from JSON-safe rules.
-*
-* @since 0.1.0
-* @category Constructors
-*/
-const fromRawRules = fromRawRules$1;
-/**
-* Returns a new Ability from raw rules using an existing Ability's options.
-*
-* @since 0.1.0
-* @category Constructors
-*/
-const update = update$1;
-/**
-* Creates a pure typed subject wrapper without mutating the wrapped value.
-*
-* @since 0.1.0
-* @category Constructors
-*/
-const subject = subject$1;
-/**
-* Returns whether a value is an Ability.
-*
-* @since 0.1.0
-* @category Guards
-*/
-const isAbility = isAbility$1;
-/**
-* Returns whether a value is a rule.
-*
-* @since 0.1.0
-* @category Guards
-*/
-const isRule = isRule$1;
-/**
-* Returns whether a value is a typed subject wrapper.
-*
-* @since 0.1.0
-* @category Guards
-*/
-const isSubject = isSubject$1;
-/**
-* Unwraps a typed subject wrapper.
-*
-* @since 0.1.0
-* @category Accessors
-*/
-const unwrapSubject = unwrapSubject$1;
-/**
-* Detects a subject name for a value using an Ability's detection strategy.
-*
-* @since 0.1.0
-* @category Accessors
-*/
-const detectSubjectType = detectSubjectType$1;
-/**
-* Converts an Ability to JSON-safe raw rules.
-*
-* @since 0.1.0
-* @category Conversions
-*/
-const toRawRules = toRawRules$1;
-/**
-* Returns rules that may apply for a request before field and condition checks.
-*
-* @since 0.1.0
-* @category Accessors
-*/
-const possibleRulesFor = possibleRulesFor$1;
-/**
-* Returns rules that may apply for a request after field checks.
-*
-* @since 0.1.0
-* @category Accessors
-*/
-const rulesFor = rulesFor$1;
-/**
-* Returns the first matching rule for a request, if any.
-*
-* @since 0.1.0
-* @category Accessors
-*/
-const relevantRuleFor = relevantRuleFor$1;
-/**
-* Returns actions that have rules for a subject.
-*
-* @since 0.1.0
-* @category Accessors
-*/
-const actionsFor = actionsFor$1;
-/**
-* Checks a request and fails with `AuthorizationError` when the request is not authorized.
-*
-* @since 0.1.0
-* @category Combinators
-*/
-const check = check$1;
-/**
-* Computes fields permitted for a request.
-*
-* @since 0.1.0
-* @category Combinators
-*/
-const permittedFields = permittedFields$1;
-//#endregion
-export { Ability_exports, AliasError, AuthorizationError, ConditionError, QueryGenerationError, RawRuleError, RuleTypeId, SubjectDetectionError, SubjectTypeId, TypeId, actionsFor, check, createAliasResolver, define, detectSubjectType, fromRawRules, isAbility, isRule, isSubject, make, permittedFields, possibleRulesFor, relevantRuleFor, rulesFor, subject, toRawRules, unwrapSubject, update };

package/dist/AbilityExtra.d.ts

@@ -1,79 +0,0 @@
-import { Ability, ActionAliases, AnyRule, QueryGenerationError, RawRule, RuleQueryRequest, SubjectDetectionError, SubjectMap } from "./Ability.js";
-import * as Effect from "effect/Effect";
-
-//#region src/AbilityExtra.d.ts
-declare namespace AbilityExtra_d_exports {
-  export { LogicalQuery, PackRule, RulesToConditionHooks, packRules, rulesToCondition, rulesToFields, rulesToQuery, unpackRules };
-}
-/**
- * @since 0.1.0
- * @category Models
- */
-type PackRule<Rule extends RawRule = RawRule> = readonly [action: Rule["action"], subject: Rule["subject"], conditions?: Rule["conditions"] | 0, inverted?: 1 | 0, fields?: Rule["fields"] | 0, reason?: string];
-/**
- * @since 0.1.0
- * @category Models
- */
-interface RulesToConditionHooks<Query> {
-  readonly and: (conditions: ReadonlyArray<Query>) => Query;
-  readonly or: (conditions: ReadonlyArray<Query>) => Query;
-  readonly not: (condition: Query) => Query;
-  readonly empty: () => Query;
-}
-/**
- * @since 0.1.0
- * @category Models
- */
-type LogicalQuery<Query> = Query | {
-  readonly $and: ReadonlyArray<LogicalQuery<Query>>;
-} | {
-  readonly $or: ReadonlyArray<LogicalQuery<Query>>;
-} | {
-  readonly $not: LogicalQuery<Query>;
-};
-/**
- * Packs JSON-safe raw rules into a compact tuple format.
- *
- * @since 0.1.0
- * @category Conversions
- */
-declare const packRules: <Rule extends RawRule>(rules: Iterable<Rule>) => ReadonlyArray<PackRule<Rule>>;
-/**
- * Unpacks compact raw rules produced by `packRules`.
- *
- * @since 0.1.0
- * @category Conversions
- */
-declare const unpackRules: <Rule extends RawRule = RawRule>(rules: Iterable<PackRule<Rule>>) => ReadonlyArray<Rule>;
-/**
- * Extracts scalar condition values as default fields.
- *
- * @since 0.1.0
- * @category Conversions
- */
-declare const rulesToFields: {
-  <const Request>(request: Request): <Subjects extends SubjectMap, Rules extends AnyRule, Aliases extends ActionAliases>(self: Ability<Subjects, Rules, Aliases> & (Request extends RuleQueryRequest<Subjects, Rules, Aliases> ? unknown : never)) => Effect.Effect<Readonly<Record<string, unknown>>, QueryGenerationError | SubjectDetectionError>;
-  <Subjects extends SubjectMap, Rules extends AnyRule, Aliases extends ActionAliases, const Request extends RuleQueryRequest<Subjects, Rules, Aliases>>(self: Ability<Subjects, Rules, Aliases>, request: Request): Effect.Effect<Readonly<Record<string, unknown>>, QueryGenerationError | SubjectDetectionError>;
-};
-/**
- * Converts rules into a caller-defined logical condition.
- *
- * @since 0.1.0
- * @category Conversions
- */
-declare const rulesToCondition: {
-  <const Request, Query, E = never, R = never>(request: Request, convert: (rule: AnyRule) => Query | Effect.Effect<Query, E, R>, hooks: RulesToConditionHooks<Query>): <Subjects extends SubjectMap, Rules extends AnyRule, Aliases extends ActionAliases>(self: Ability<Subjects, Rules, Aliases> & (Request extends RuleQueryRequest<Subjects, Rules, Aliases> ? unknown : never)) => Effect.Effect<Query | null, QueryGenerationError | SubjectDetectionError | E, R>;
-  <Subjects extends SubjectMap, Rules extends AnyRule, Aliases extends ActionAliases, const Request extends RuleQueryRequest<Subjects, Rules, Aliases>, Query, E = never, R = never>(self: Ability<Subjects, Rules, Aliases>, request: Request, convert: (rule: Rules) => Query | Effect.Effect<Query, E, R>, hooks: RulesToConditionHooks<Query>): Effect.Effect<Query | null, QueryGenerationError | SubjectDetectionError | E, R>;
-};
-/**
- * Converts rules into a small generic logical query object.
- *
- * @since 0.1.0
- * @category Conversions
- */
-declare const rulesToQuery: {
-  <const Request, Query, E = never, R = never>(request: Request, convert: (rule: AnyRule) => Query | Effect.Effect<Query, E, R>): <Subjects extends SubjectMap, Rules extends AnyRule, Aliases extends ActionAliases>(self: Ability<Subjects, Rules, Aliases> & (Request extends RuleQueryRequest<Subjects, Rules, Aliases> ? unknown : never)) => Effect.Effect<LogicalQuery<Query> | null, QueryGenerationError | SubjectDetectionError | E, R>;
-  <Subjects extends SubjectMap, Rules extends AnyRule, Aliases extends ActionAliases, const Request extends RuleQueryRequest<Subjects, Rules, Aliases>, Query, E = never, R = never>(self: Ability<Subjects, Rules, Aliases>, request: Request, convert: (rule: Rules) => Query | Effect.Effect<Query, E, R>): Effect.Effect<LogicalQuery<Query> | null, QueryGenerationError | SubjectDetectionError | E, R>;
-};
-//#endregion
-export { AbilityExtra_d_exports, LogicalQuery, PackRule, RulesToConditionHooks, packRules, rulesToCondition, rulesToFields, rulesToQuery, unpackRules };

package/dist/AbilityExtra.js

@@ -1,187 +0,0 @@
-import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import { cloneSerializable, isPlainObject } from "./internal/serializable.js";
-import { QueryGenerationError, rulesFor } from "./Ability.js";
-import * as Effect from "effect/Effect";
-import { dual } from "effect/Function";
-//#region src/AbilityExtra.ts
-/**
-* Extra helpers for serializing and transforming Ability rules.
-*
-* Mental model:
-* - `AbilityExtra` works with already-defined abilities and JSON-safe rules.
-* - Packing preserves rule structure while reducing wire size.
-* - Query helpers transform rule lists into caller-owned condition formats.
-*
-* Common tasks:
-* - Compact raw rules with {@link packRules} and {@link unpackRules}.
-* - Derive default fields from rule conditions with {@link rulesToFields}.
-* - Convert matching rules to logical conditions with {@link rulesToCondition}
-*   or {@link rulesToQuery}.
-*
-* Gotchas:
-* - Conversion callbacks may be synchronous or Effectful; synchronous throws are
-*   converted to `QueryGenerationError`.
-*
-* @since 0.1.0
-* @module
-*/
-var AbilityExtra_exports = /* @__PURE__ */ __exportAll({
-	packRules: () => packRules,
-	rulesToCondition: () => rulesToCondition,
-	rulesToFields: () => rulesToFields,
-	rulesToQuery: () => rulesToQuery,
-	unpackRules: () => unpackRules
-});
-const forbiddenPathKeys = new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
-const setByPath = (object, path, value) => {
-	const keys = path.split(".");
-	let cursor = object;
-	let index = 0;
-	while (index < keys.length - 1) {
-		const key = keys[index];
-		if (key === void 0 || forbiddenPathKeys.has(key)) return;
-		const current = cursor[key];
-		if (!isPlainObject(current)) {
-			const next = {};
-			cursor[key] = next;
-			cursor = next;
-		} else cursor = current;
-		index = index + 1;
-	}
-	const lastKey = keys[keys.length - 1];
-	if (lastKey !== void 0 && !forbiddenPathKeys.has(lastKey)) cursor[lastKey] = value;
-};
-const packRule = (rule) => {
-	const packed = [
-		cloneSerializable(rule.action),
-		cloneSerializable(rule.subject),
-		rule.conditions === void 0 ? 0 : cloneSerializable(rule.conditions),
-		rule.inverted === true ? 1 : 0,
-		rule.fields === void 0 ? 0 : cloneSerializable(rule.fields),
-		rule.reason ?? ""
-	];
-	while (packed.length > 2 && (packed[packed.length - 1] === 0 || packed[packed.length - 1] === "" || packed[packed.length - 1] === void 0)) packed.pop();
-	return Object.freeze(packed);
-};
-/**
-* Packs JSON-safe raw rules into a compact tuple format.
-*
-* @since 0.1.0
-* @category Conversions
-*/
-const packRules = (rules) => Object.freeze(Array.from(rules, packRule));
-const unpackRule = (packed) => {
-	const [action, subject, conditions, inverted, fields, reason] = packed;
-	const rule = {
-		action: cloneSerializable(action),
-		subject: cloneSerializable(subject)
-	};
-	if (conditions !== void 0 && conditions !== 0) rule.conditions = cloneSerializable(conditions);
-	if (inverted === 1) rule.inverted = true;
-	if (fields !== void 0 && fields !== 0) rule.fields = cloneSerializable(fields);
-	if (reason !== void 0 && reason !== "") rule.reason = reason;
-	return Object.freeze(rule);
-};
-/**
-* Unpacks compact raw rules produced by `packRules`.
-*
-* @since 0.1.0
-* @category Conversions
-*/
-const unpackRules = (rules) => Object.freeze(Array.from(rules, unpackRule));
-const queryGenerationError = (reason, ruleIndex, cause) => {
-	const error = { reason };
-	if (ruleIndex !== void 0) error.ruleIndex = ruleIndex;
-	if (cause !== void 0) error.cause = cause;
-	return new QueryGenerationError(error);
-};
-/**
-* Extracts scalar condition values as default fields.
-*
-* @since 0.1.0
-* @category Conversions
-*/
-const rulesToFields = dual(2, Effect.fnUntraced(function* (self, request) {
-	const rules = yield* rulesFor(self, request);
-	const fields = {};
-	let index = 0;
-	for (const rule of rules) {
-		if (rule._tag === "Allow" && rule.conditions !== void 0) for (const key of Object.keys(rule.conditions)) {
-			const value = rule.conditions[key];
-			if (!isPlainObject(value)) setByPath(fields, key, value);
-		}
-		index = index + 1;
-	}
-	return Object.freeze(fields);
-}));
-const convertRule = (rule, convert, ruleIndex) => Effect.flatMap(Effect.try({
-	try: () => convert(rule),
-	catch: (cause) => queryGenerationError("Rule conversion failed", ruleIndex, cause)
-}), (result) => Effect.isEffect(result) ? result : Effect.succeed(result));
-/**
-* Converts rules into a caller-defined logical condition.
-*
-* @since 0.1.0
-* @category Conversions
-*/
-const rulesToConditionEffect = Effect.fnUntraced(function* (self, request, convert, hooks) {
-	const rules = yield* rulesFor(self, request);
-	const higherDenyBounds = [];
-	const orConditions = [];
-	let hasUnconditionalAllow = false;
-	let index = 0;
-	while (index < rules.length) {
-		const rule = rules[index];
-		if (rule._tag === "Deny") {
-			if (rule.conditions === void 0) break;
-			const condition = yield* convertRule(rule, convert, index);
-			higherDenyBounds.push(hooks.not(condition));
-		} else {
-			if (rule.conditions === void 0) {
-				hasUnconditionalAllow = true;
-				break;
-			}
-			const condition = yield* convertRule(rule, convert, index);
-			orConditions.push(higherDenyBounds.length === 0 ? condition : hooks.and([condition, ...higherDenyBounds]));
-		}
-		index = index + 1;
-	}
-	if (hasUnconditionalAllow) {
-		if (higherDenyBounds.length === 0) return hooks.empty();
-		if (orConditions.length === 0) return hooks.and(higherDenyBounds);
-		orConditions.push(hooks.and(higherDenyBounds));
-	}
-	if (orConditions.length === 0) return null;
-	return hooks.or(orConditions);
-});
-/**
-* Converts rules into a caller-defined logical condition.
-*
-* @since 0.1.0
-* @category Conversions
-*/
-const rulesToCondition = dual(4, rulesToConditionEffect);
-/**
-* Converts rules into a small generic logical query object.
-*
-* @since 0.1.0
-* @category Conversions
-*/
-const rulesToQuery = dual(3, Effect.fnUntraced(function* (self, request, convert) {
-	const logicalConvert = (rule) => {
-		const result = convert(rule);
-		return Effect.isEffect(result) ? result : result;
-	};
-	return yield* rulesToConditionEffect(self, request, logicalConvert, {
-		and: (conditions) => ({ $and: conditions }),
-		or: (conditions) => ({ $or: conditions }),
-		not: (condition) => ({ $not: condition }),
-		empty: () => ({})
-	});
-}));
-//#endregion
-export { AbilityExtra_exports, packRules, rulesToCondition, rulesToFields, rulesToQuery, unpackRules };

package/dist/internal/ability.d.ts

@@ -1,90 +0,0 @@
-import * as _$effect_Types0 from "effect/Types";
-import * as _$effect_Cause0 from "effect/Cause";
-
-//#region src/internal/ability.d.ts
-/**
- * @internal
- */
-declare const TypeId: unique symbol;
-/**
- * @internal
- */
-declare const SubjectTypeId: unique symbol;
-/**
- * @internal
- */
-declare const RuleTypeId: unique symbol;
-declare const AuthorizationError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
-  readonly _tag: "AuthorizationError";
-} & Readonly<A>;
-/**
- * @since 0.1.0
- * @category Errors
- */
-declare class AuthorizationError extends AuthorizationError_base<{
-  readonly action: string;
-  readonly subject: string;
-  readonly field?: string;
-  readonly reason?: string;
-}> {}
-declare const ConditionError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
-  readonly _tag: "ConditionError";
-} & Readonly<A>;
-/**
- * @since 0.1.0
- * @category Errors
- */
-declare class ConditionError extends ConditionError_base<{
-  readonly action: string;
-  readonly subject: string;
-  readonly field?: string;
-  readonly cause: unknown;
-}> {}
-declare const RawRuleError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
-  readonly _tag: "RawRuleError";
-} & Readonly<A>;
-/**
- * @since 0.1.0
- * @category Errors
- */
-declare class RawRuleError extends RawRuleError_base<{
-  readonly reason: string;
-  readonly ruleIndex?: number;
-  readonly cause?: unknown;
-}> {}
-declare const SubjectDetectionError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
-  readonly _tag: "SubjectDetectionError";
-} & Readonly<A>;
-/**
- * @since 0.1.0
- * @category Errors
- */
-declare class SubjectDetectionError extends SubjectDetectionError_base<{
-  readonly reason: string;
-  readonly cause?: unknown;
-}> {}
-declare const AliasError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
-  readonly _tag: "AliasError";
-} & Readonly<A>;
-/**
- * @since 0.1.0
- * @category Errors
- */
-declare class AliasError extends AliasError_base<{
-  readonly reason: string;
-  readonly action?: string;
-}> {}
-declare const QueryGenerationError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
-  readonly _tag: "QueryGenerationError";
-} & Readonly<A>;
-/**
- * @since 0.1.0
- * @category Errors
- */
-declare class QueryGenerationError extends QueryGenerationError_base<{
-  readonly reason: string;
-  readonly ruleIndex?: number;
-  readonly cause?: unknown;
-}> {}
-//#endregion
-export { AliasError, AuthorizationError, ConditionError, QueryGenerationError, RawRuleError, RuleTypeId, SubjectDetectionError, SubjectTypeId, TypeId };