@nmnmcc/ability 0.1.0

package/dist/AbilityRef.js

@@ -0,0 +1,160 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { fromRawRules, isAbility } from "./Ability.js";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as Formatter from "effect/Formatter";
+import { dual } from "effect/Function";
+import * as Hash from "effect/Hash";
+import * as Inspectable from "effect/Inspectable";
+import * as Pipeable from "effect/Pipeable";
+import * as Predicate from "effect/Predicate";
+//#region src/AbilityRef.ts
+/**
+* Mutable ability references for applications that need to swap immutable
+* abilities at runtime.
+*
+* Mental model:
+* - `AbilityRef` is the explicit mutable boundary for this package.
+* - The current ability can be replaced while subscribers observe update events.
+* - All policy evaluation still happens against immutable `Ability` values.
+*
+* Common tasks:
+* - Create a reference with {@link make}.
+* - Read the current ability with {@link get}.
+* - Replace the current ability with {@link set} or {@link update}.
+* - Subscribe to update events with {@link on}.
+*
+* Gotchas:
+* - Event handlers run in registration order.
+* - `update` accepts raw rules and reuses the current ability options.
+* - `AbilityRef` equality is referential because the current value is mutable.
+*
+* @since 0.1.0
+* @module
+*/
+var AbilityRef_exports = /* @__PURE__ */ __exportAll({
+	TypeId: () => TypeId,
+	get: () => get,
+	isAbilityRef: () => isAbilityRef,
+	make: () => make,
+	on: () => on,
+	set: () => set,
+	update: () => update
+});
+/**
+* @since 0.1.0
+* @category Type Ids
+*/
+const TypeId = Symbol.for("@nmnmcc/ability/AbilityRef");
+const RefIdentityTypeId = Symbol.for("@nmnmcc/ability/AbilityRef/identity");
+let refIdentity = 0;
+const inspectableToString = function() {
+	return Formatter.format(this.toJSON(), {
+		ignoreToString: true,
+		space: 2
+	});
+};
+const inspectableNode = function() {
+	return this.toJSON();
+};
+const AbilityRefProto = {
+	...Pipeable.Prototype,
+	[TypeId]: TypeId,
+	[Equal.symbol](that) {
+		return isAbilityRef(that) && this[RefIdentityTypeId] === that[RefIdentityTypeId];
+	},
+	[Hash.symbol]() {
+		return Hash.number(this[RefIdentityTypeId]);
+	},
+	toString: inspectableToString,
+	toJSON() {
+		return {
+			_id: "AbilityRef",
+			current: this.current
+		};
+	},
+	[Inspectable.NodeInspectSymbol]: inspectableNode
+};
+/**
+* @since 0.1.0
+* @category Constructors
+*/
+const make = (ability) => {
+	const ref = Object.create(AbilityRefProto);
+	ref.current = ability;
+	ref[RefIdentityTypeId] = refIdentity;
+	refIdentity = refIdentity + 1;
+	ref.handlers = {
+		update: [],
+		updated: []
+	};
+	return ref;
+};
+/**
+* @since 0.1.0
+* @category Guards
+*/
+const isAbilityRef = (value) => Predicate.hasProperty(value, TypeId);
+/**
+* @since 0.1.0
+* @category Accessors
+*/
+const get = (self) => self.current;
+const toEffect = (evaluate) => Effect.flatMap(Effect.sync(evaluate), (result) => Effect.isEffect(result) ? result : Effect.void);
+const emit = Effect.fnUntraced(function* (self, name, event) {
+	const handlers = Array.from(self.handlers[name]);
+	for (const handler of handlers) yield* toEffect(() => handler(event));
+});
+/**
+* @since 0.1.0
+* @category Combinators
+*/
+const setEffect = Effect.fnUntraced(function* (self, ability) {
+	const previous = self.current;
+	const next = ability;
+	const mutable = self;
+	yield* emit(self, "update", {
+		previous,
+		next
+	});
+	mutable.current = next;
+	yield* emit(self, "updated", {
+		previous,
+		current: next
+	});
+});
+/**
+* @since 0.1.0
+* @category Combinators
+*/
+const set = dual(2, setEffect);
+/**
+* @since 0.1.0
+* @category Combinators
+*/
+const update = dual(2, Effect.fnUntraced(function* (self, next) {
+	if (Symbol.iterator in Object(next) && !isAbility(next)) return yield* setEffect(self, yield* fromRawRules(next, self.current.options));
+	return yield* setEffect(self, next);
+}));
+/**
+* @since 0.1.0
+* @category Combinators
+*/
+const onEffect = (self, name, handler) => Effect.sync(() => {
+	const handlers = self.handlers[name];
+	handlers.push(handler);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		const index = handlers.indexOf(handler);
+		if (index >= 0) handlers.splice(index, 1);
+	};
+});
+/**
+* @since 0.1.0
+* @category Combinators
+*/
+const on = dual(3, onEffect);
+//#endregion
+export { AbilityRef_exports, TypeId, get, isAbilityRef, make, on, set, update };

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { Ability_d_exports } from "./Ability.js";
+import { AbilityExtra_d_exports } from "./AbilityExtra.js";
+import { AbilityRef_d_exports } from "./AbilityRef.js";
+export { Ability_d_exports as Ability, AbilityExtra_d_exports as AbilityExtra, AbilityRef_d_exports as AbilityRef };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { Ability_exports } from "./Ability.js";
+import { AbilityExtra_exports } from "./AbilityExtra.js";
+import { AbilityRef_exports } from "./AbilityRef.js";
+export { Ability_exports as Ability, AbilityExtra_exports as AbilityExtra, AbilityRef_exports as AbilityRef };

package/dist/internal/ability.d.ts

@@ -0,0 +1,114 @@
+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 PredicateEvaluationError_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: "PredicateEvaluationError";
+} & Readonly<A>;
+/**
+ * @since 0.1.0
+ * @category Errors
+ */
+declare class PredicateEvaluationError extends PredicateEvaluationError_base<{
+  readonly action: string;
+  readonly subject: string;
+  readonly field?: string;
+  readonly cause: unknown;
+}> {}
+declare const SerializationError_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: "SerializationError";
+} & Readonly<A>;
+/**
+ * @since 0.1.0
+ * @category Errors
+ */
+declare class SerializationError extends SerializationError_base<{
+  readonly reason: string;
+  readonly ruleIndex?: number;
+}> {}
+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, PredicateEvaluationError, QueryGenerationError, RawRuleError, RuleTypeId, SerializationError, SubjectDetectionError, SubjectTypeId, TypeId };