@systemfsoftware/effect-atom 0.5.3

package/dist/Result-DwtHFH70.mjs

@@ -0,0 +1,663 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { constTrue, dual, identity } from "effect/Function";
+import * as Option from "effect/Option";
+import * as Schema_ from "effect/Schema";
+import { pipeArguments } from "effect/Pipeable";
+import { hasProperty, isIterable } from "effect/Predicate";
+import * as Either from "effect/Result";
+import * as Equal$1 from "effect/Equal";
+import * as Hash from "effect/Hash";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaParser from "effect/SchemaParser";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+//#region src/internal/result-values.ts
+/**
+* Value-side declarations backing the `Result` module.
+*
+* These declarations were lifted out of `Result.ts` to break the import cycle
+* between `Result.ts` and `internal/result-schema.ts`. Both modules now import
+* from this leaf, so the dependency graph becomes:
+*
+*   result-values.ts (this file)  <--  Result.ts
+*                                  <--  internal/result-schema.ts
+*
+* The public surface is unchanged: every public name declared here is
+* re-exported from `Result.ts`. `ResultProto` stays leaf-internal and is
+* reached directly by `Result.ts` and by the constructors in this file.
+*/
+/**
+* Runtime identifier attached to `Result` values and used by `isResult`.
+*
+* @category type IDs
+* @since 4.0.0
+*/
+const TypeId = "~effect-atom/atom/Result";
+/**
+* Shared prototype every `Result` variant inherits from. The three
+* constructors (`initial`, `success`, `failure`) use it; `waiting` in
+* `Result.ts` also reaches it directly.
+*
+* The schema codec (`internal/result-schema.ts`) serializes only the tagged
+* variant fields (`value`, `waiting`, `timestamp`, `cause`,
+* `previousSuccess`) — nothing added to this prototype is wire-carried, so
+* any future proto-private state must be mirrored in that encode/decode pair.
+*
+* @since 4.0.0
+*/
+const ResultProto = {
+	[TypeId]: {
+		E: identity,
+		A: identity
+	},
+	pipe() {
+		return pipeArguments(this, arguments);
+	},
+	[Equal$1.symbol](that) {
+		if (this._tag !== that._tag || this.waiting !== that.waiting) return false;
+		switch (this._tag) {
+			case "Initial": return true;
+			case "Success": return Equal$1.equals(this.value, that.value);
+			case "Failure": return Equal$1.equals(this.cause, that.cause);
+		}
+	},
+	[Hash.symbol]() {
+		const tagHash = Hash.string(`${this._tag}:${this.waiting}`);
+		if (this._tag === "Initial") return tagHash;
+		return Hash.combine(tagHash)(this._tag === "Success" ? Hash.hash(this.value) : Hash.hash(this.cause));
+	}
+};
+/**
+* Returns `true` when a value is an `Result`.
+*
+* @category guards
+* @since 4.0.0
+*/
+const isResult = (u) => hasProperty(u, TypeId);
+/**
+* Creates an `Initial` result, optionally marking it as waiting.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const initial = (waiting = false) => {
+	const result = Object.create(ResultProto);
+	result._tag = "Initial";
+	result.waiting = waiting;
+	return result;
+};
+/**
+* Creates a `Success` result with a value and optional `waiting` flag or
+* timestamp override.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const success = (value, options) => {
+	const result = Object.create(ResultProto);
+	result._tag = "Success";
+	result.value = value;
+	result.waiting = options?.waiting ?? false;
+	result.timestamp = options?.timestamp ?? Date.now();
+	return result;
+};
+/**
+* Creates a `Failure` result from a `Cause`, optionally preserving a previous
+* success and marking the result as waiting.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const failure = (cause, options) => {
+	const result = Object.create(ResultProto);
+	result._tag = "Failure";
+	result.cause = cause;
+	result.previousSuccess = options?.previousSuccess ?? Option.none();
+	result.waiting = options?.waiting ?? false;
+	return result;
+};
+//#endregion
+//#region src/internal/result-schema.ts
+/**
+* Creates a schema for `Result` values using optional schemas for success values and failure errors.
+*
+* @category schemas
+* @since 4.0.0
+*/
+const Schema = (options) => {
+	const success_ = options.success ?? Schema_.Never;
+	const error = options.error ?? Schema_.Never;
+	const schema = Schema_.declareConstructor()([success_, Schema_.Cause(error, Schema_.Defect())], ([value, cause]) => (input, ast, options) => {
+		if (!isResult(input)) return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
+		switch (input._tag) {
+			case "Initial": return Effect.succeed(input);
+			case "Success": return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(value)(input.value, options), {
+				onSuccess: (value) => success(value, input),
+				onFailure: (issue) => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], issue)], input, options)
+			});
+			case "Failure": {
+				const prevSuccessEffect = input.previousSuccess.pipe(Option.map((ps) => Effect.mapBothEager(SchemaParser.decodeUnknownEffect(value)(ps.value, options), {
+					onSuccess: (value) => Option.some(success(value, ps)),
+					onFailure: (issue) => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["previousSuccess", "value"], issue)], input, options)
+				})), Option.getOrElse(() => Effect.succeedNone));
+				const causeEffect = Effect.mapErrorEager(SchemaParser.decodeUnknownEffect(cause)(input.cause, options), (issue) => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["cause"], issue)], input, options));
+				return Effect.flatMapEager(prevSuccessEffect, (previousSuccess) => Effect.mapEager(causeEffect, (cause) => failure(cause, {
+					previousSuccess,
+					waiting: input.waiting
+				})));
+			}
+		}
+	}, {
+		expected: "Result",
+		toCodec([value, cause]) {
+			const Success = Schema_.TaggedStruct("Success", {
+				value,
+				waiting: Schema_.Boolean,
+				timestamp: Schema_.Number
+			});
+			return Schema_.link()(Schema_.Union([
+				Schema_.TaggedStruct("Initial", { waiting: Schema_.Boolean }),
+				Success,
+				Schema_.TaggedStruct("Failure", {
+					cause,
+					previousSuccess: Schema_.Option(Success),
+					waiting: Schema_.Boolean
+				})
+			]), SchemaTransformation.transform({
+				decode: (encoded) => {
+					switch (encoded._tag) {
+						case "Initial": return initial(encoded.waiting);
+						case "Success": return success(encoded.value, {
+							waiting: encoded.waiting,
+							timestamp: encoded.timestamp
+						});
+						case "Failure": return failure(encoded.cause, {
+							previousSuccess: Option.map(encoded.previousSuccess, (ps) => success(ps.value, ps)),
+							waiting: encoded.waiting
+						});
+					}
+				},
+				encode(result) {
+					switch (result._tag) {
+						case "Initial": return {
+							_tag: "Initial",
+							waiting: result.waiting
+						};
+						case "Success": return {
+							_tag: "Success",
+							value: result.value,
+							waiting: result.waiting,
+							timestamp: result.timestamp
+						};
+						case "Failure": return {
+							_tag: "Failure",
+							cause: result.cause,
+							previousSuccess: result.previousSuccess,
+							waiting: result.waiting
+						};
+					}
+				}
+			}));
+		},
+		toEquivalence: Equal$1.asEquivalence,
+		toArbitrary: ([value]) => (fc) => fc.oneof(fc.record({
+			value: value.arbitrary,
+			waiting: fc.boolean(),
+			timestamp: fc.nat()
+		}).map((r) => success(r.value, {
+			waiting: r.waiting,
+			timestamp: r.timestamp
+		})), fc.record({
+			cause: fc.oneof(Schema_.toArbitrary(error)(fc).map((e) => Cause.fail(e)), fc.jsonValue().map((d) => Cause.die(d))),
+			waiting: fc.boolean(),
+			previous: fc.option(value.arbitrary, { nil: void 0 })
+		}).map((r) => failure(r.cause, {
+			previousSuccess: r.previous === void 0 ? Option.none() : Option.some(success(r.previous)),
+			waiting: r.waiting
+		})), fc.boolean().map((waiting) => initial(waiting))),
+		toFormatter: ([value, cause]) => (t) => {
+			switch (t._tag) {
+				case "Success": return `Result.Success(${value(t.value)}, ${t.waiting}, ${t.timestamp})`;
+				case "Failure": return `Result.Failure(${cause(t.cause)}, ${t.waiting})`;
+				case "Initial": return `Result.Initial(${t.waiting})`;
+			}
+		}
+	});
+	return Object.assign(schema, {
+		success: success_,
+		error
+	});
+};
+/**
+* A `Schema.ConstraintCodec` for `Result<unknown, unknown>` built from the
+* given success and error schemas.
+*
+* @internal
+*/
+const schemaCodec = (success, error) => Schema({
+	success,
+	error
+});
+//#endregion
+//#region src/Result.ts
+/**
+* Represents observable state for asynchronous values.
+*
+* `Result<A, E>` records whether asynchronous work has no value yet,
+* succeeded with an `A`, or failed with an `E`. Every state also carries a
+* `waiting` flag, so callers can keep showing the current value while newer
+* work is loading, refreshing, retrying, or recovering. This module includes
+* constructors, checks, accessors, mapping and matching helpers, ways to combine
+* several results, and schemas for encoding or decoding results.
+*
+* @since 4.0.0
+*/
+var Result_exports = /* @__PURE__ */ __exportAll({
+	Schema: () => Schema,
+	TypeId: () => TypeId,
+	all: () => all,
+	builder: () => builder,
+	cause: () => cause,
+	error: () => error,
+	fail: () => fail,
+	failWithPrevious: () => failWithPrevious,
+	failure: () => failure,
+	failureWithPrevious: () => failureWithPrevious,
+	flatMap: () => flatMap,
+	fromExit: () => fromExit,
+	fromExitWithPrevious: () => fromExitWithPrevious,
+	getOrElse: () => getOrElse,
+	getOrThrow: () => getOrThrow,
+	initial: () => initial,
+	isAsyncResult: () => isResult,
+	isFailure: () => isFailure,
+	isInitial: () => isInitial,
+	isInterrupted: () => isInterrupted,
+	isNotInitial: () => isNotInitial,
+	isResult: () => isResult,
+	isSuccess: () => isSuccess,
+	isWaiting: () => isWaiting,
+	map: () => map,
+	match: () => match,
+	matchWithError: () => matchWithError,
+	matchWithWaiting: () => matchWithWaiting,
+	replacePrevious: () => replacePrevious,
+	success: () => success,
+	toExit: () => toExit,
+	touch: () => touch,
+	value: () => value,
+	waiting: () => waiting,
+	waitingFrom: () => waitingFrom
+});
+/**
+* Returns whether an `Result` is currently waiting for an asynchronous computation or refresh to finish.
+*
+* @category predicates
+* @since 4.0.0
+*/
+const isWaiting = (result) => result.waiting;
+/**
+* Converts an `Exit` into a `Success` when it succeeds or a `Failure` carrying the exit cause when it fails.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const fromExit = (exit) => exit._tag === "Success" ? success(exit.value) : failure(exit.cause);
+/**
+* Converts an `Exit` to a result, preserving the latest previous success when the exit is a failure.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const fromExitWithPrevious = (exit, previous) => exit._tag === "Success" ? success(exit.value) : failureWithPrevious(exit.cause, { previous });
+/**
+* Creates a waiting result from an optional previous result, using `Initial(true)` when no previous result exists.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const waitingFrom = (previous) => {
+	if (previous._tag === "None") return initial(true);
+	return waiting(previous.value);
+};
+/**
+* Returns `true` when an `Result` is in the `Initial` state.
+*
+* @category guards
+* @since 4.0.0
+*/
+const isInitial = (result) => result._tag === "Initial";
+/**
+* Returns `true` when an `Result` is either `Success` or `Failure`.
+*
+* @category guards
+* @since 4.0.0
+*/
+const isNotInitial = (result) => result._tag !== "Initial";
+/**
+* Returns `true` when an `Result` is a `Success`.
+*
+* @category guards
+* @since 4.0.0
+*/
+const isSuccess = (result) => result._tag === "Success";
+/**
+* Returns `true` when an `Result` is a `Failure`.
+*
+* @category guards
+* @since 4.0.0
+*/
+const isFailure = (result) => result._tag === "Failure";
+/**
+* Returns `true` when an `Result` is a `Failure` whose cause contains only interruptions.
+*
+* @category guards
+* @since 4.0.0
+*/
+const isInterrupted = (result) => result._tag === "Failure" && Cause.hasInterruptsOnly(result.cause);
+/**
+* Creates a `Failure` result from a `Cause`, carrying forward the latest success stored in a previous result.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const failureWithPrevious = (cause, options) => failure(cause, {
+	previousSuccess: Option.flatMap(options.previous, (result) => isSuccess(result) ? Option.some(result) : isFailure(result) ? result.previousSuccess : Option.none()),
+	waiting: options.waiting
+});
+/**
+* Creates a `Failure` result from a typed error, wrapping it in `Cause.fail`.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const fail = (error, options) => failure(Cause.fail(error), options);
+/**
+* Creates a `Failure` result from a typed error while carrying forward the latest success stored in a previous result.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const failWithPrevious = (error, options) => failureWithPrevious(Cause.fail(error), options);
+/**
+* Marks an `Result` as waiting, optionally touching the timestamp when the result is a `Success`.
+*
+* @category constructors
+* @since 4.0.0
+*/
+const waiting = (self, options) => {
+	if (self.waiting) return options?.touch ? touch(self) : self;
+	const result = Object.assign(Object.create(ResultProto), self, { waiting: true });
+	return options?.touch ? touch(result) : result;
+};
+/**
+* Refreshes the timestamp of a `Success` result while preserving its value and waiting flag; non-success results are returned unchanged.
+*
+* @category combinators
+* @since 4.0.0
+*/
+const touch = (result) => {
+	if (isSuccess(result)) return success(result.value, { waiting: result.waiting });
+	return result;
+};
+/**
+* Replaces a `Failure` value's stored previous success with the latest success
+* found in another result.
+*
+* @category combinators
+* @since 4.0.0
+*/
+const replacePrevious = (self, previous) => replacePreviousImpl(self, previous);
+const replacePreviousImpl = (self, previous) => self._tag === "Failure" ? failureWithPrevious(self.cause, {
+	previous,
+	waiting: self.waiting
+}) : self;
+/**
+* Returns the current success value, or the previous success value stored in a failure, as an `Option`.
+*
+* @category accessors
+* @since 4.0.0
+*/
+const value = (self) => {
+	if (self._tag === "Success") return Option.some(self.value);
+	else if (self._tag === "Failure") return Option.map(self.previousSuccess, (s) => s.value);
+	return Option.none();
+};
+/**
+* Returns the available value from `value`, or evaluates the fallback when no current or previous success exists.
+*
+* @category accessors
+* @since 4.0.0
+*/
+const getOrElse = dual(2, (self, orElse) => Option.getOrElse(value(self), orElse));
+/**
+* Returns the available value from `value`, or throws `NoSuchElementError` when no current or previous success exists.
+*
+* @category accessors
+* @since 4.0.0
+*/
+const getOrThrow = (self) => Option.getOrThrowWith(value(self), () => new Cause.NoSuchElementError("Result.getOrThrow: no value found"));
+/**
+* Returns the failure cause when the result is a `Failure`, otherwise `None`.
+*
+* @category accessors
+* @since 4.0.0
+*/
+const cause = (self) => self._tag === "Failure" ? Option.some(self.cause) : Option.none();
+/**
+* Returns the first typed error from a failure cause, or `None` for successes, initial results, defects, and interrupt-only causes.
+*
+* @category accessors
+* @since 4.0.0
+*/
+const error = (self) => self._tag === "Failure" ? Cause.findErrorOption(self.cause) : Option.none();
+/**
+* Converts a result to an `Exit`, succeeding with a success value, failing with a failure cause, or failing with `NoSuchElementError` for `Initial`.
+*
+* @category combinators
+* @since 4.0.0
+*/
+const toExit = (self) => {
+	switch (self._tag) {
+		case "Success": return Exit.succeed(self.value);
+		case "Failure": return Exit.failCause(self.cause);
+		default: return Exit.fail(new Cause.NoSuchElementError());
+	}
+};
+/**
+* Maps the success value of an `Result`, also mapping any previous success stored in a failure while leaving initial results unchanged.
+*
+* @category combinators
+* @since 4.0.0
+*/
+const map = dual(2, (self, f) => {
+	switch (self._tag) {
+		case "Initial": return initial(self.waiting);
+		case "Failure": return failure(self.cause, {
+			previousSuccess: Option.map(self.previousSuccess, (s) => success(f(s.value), s)),
+			waiting: self.waiting
+		});
+		case "Success": return success(f(self.value), self);
+	}
+});
+/**
+* Maps the success value of an `Result` and flattens the result.
+*
+* **When to use**
+*
+* Use to sequence computations that may return another `Result` while
+* preserving initial and failure states.
+*
+* **Details**
+*
+* Initial results are left unchanged. Failures preserve their cause and remap
+* the stored previous success when the mapping function returns a success.
+*
+* @category combinators
+* @since 4.0.0
+*/
+const flatMap = dual(2, (self, f) => {
+	switch (self._tag) {
+		case "Initial": return initial(self.waiting);
+		case "Failure": return failure(self.cause, {
+			previousSuccess: Option.flatMap(self.previousSuccess, (s) => {
+				const next = f(s.value, s);
+				return isSuccess(next) ? Option.some(next) : Option.none();
+			}),
+			waiting: self.waiting
+		});
+		case "Success": return f(self.value, self);
+	}
+});
+/**
+* Pattern matches an `Result` by calling the handler for `Initial`, `Failure`, or `Success`.
+*
+* @category combinators
+* @since 4.0.0
+*/
+const match = dual(2, (self, options) => {
+	switch (self._tag) {
+		case "Initial": return options.onInitial(self);
+		case "Failure": return options.onFailure(self);
+		case "Success": return options.onSuccess(self);
+	}
+});
+/**
+* Pattern matches a result, handling successes and initials directly while splitting failures into typed errors or squashed non-error causes passed to `onDefect`.
+*
+* @category combinators
+* @since 4.0.0
+*/
+const matchWithError = dual(2, (self, options) => {
+	switch (self._tag) {
+		case "Initial": return options.onInitial(self);
+		case "Failure": {
+			const result = Cause.findError(self.cause);
+			if (Either.isFailure(result)) return options.onDefect(Cause.squash(result.failure), self);
+			return options.onError(result.success, self);
+		}
+		case "Success": return options.onSuccess(self);
+	}
+});
+/**
+* Pattern matches a result by calling `onWaiting` for waiting or initial states, otherwise handling successes and splitting failures into typed errors or squashed non-error causes.
+*
+* @category combinators
+* @since 4.0.0
+*/
+const matchWithWaiting = dual(2, (self, options) => {
+	if (self.waiting) return options.onWaiting(self);
+	switch (self._tag) {
+		case "Initial": return options.onWaiting(self);
+		case "Failure": {
+			const e = Cause.findError(self.cause);
+			if (Either.isFailure(e)) return options.onDefect(Cause.squash(e.failure), self);
+			return options.onError(e.success, self);
+		}
+		case "Success": return options.onSuccess(self);
+	}
+});
+const all = (results) => allImpl(results);
+const allImpl = (results) => {
+	let waiting = false;
+	if (isIterable(results)) {
+		const list = Array.from(results);
+		const successes = [];
+		for (let i = 0; i < list.length; i++) {
+			const result = list[i];
+			if (!isResult(result)) {
+				successes[i] = result;
+				continue;
+			}
+			if (!isSuccess(result)) return result;
+			successes[i] = result.value;
+			if (result.waiting) waiting = true;
+		}
+		return success(successes, { waiting });
+	}
+	const successes = {};
+	for (const [key, result] of Object.entries(results)) {
+		if (!isResult(result)) {
+			successes[key] = result;
+			continue;
+		}
+		if (!isSuccess(result)) return result;
+		successes[key] = result.value;
+		if (result.waiting) waiting = true;
+	}
+	return success(successes, { waiting });
+};
+const builder = (self) => {
+	return new BuilderImpl(self);
+};
+var BuilderImpl = class {
+	constructor(result) {
+		this.result = result;
+	}
+	result;
+	output = Option.none();
+	when(refinement, f) {
+		if (Option.isNone(this.output) && refinement(this.result)) {
+			const b = f(this.result);
+			if (Option.isSome(b)) this.output = b;
+		}
+		return this;
+	}
+	pipe() {
+		return pipeArguments(this, arguments);
+	}
+	onWaiting(f) {
+		return this.when((r) => r.waiting, (r) => Option.some(f(r)));
+	}
+	onInitialOrWaiting(f) {
+		return this.when((r) => isInitial(r) || r.waiting, (r) => Option.some(f(r)));
+	}
+	onInitial(f) {
+		return this.when(isInitial, (r) => Option.some(f(r)));
+	}
+	onSuccess(f) {
+		return this.when(isSuccess, (r) => Option.some(f(r.value, r)));
+	}
+	onFailure(f) {
+		return this.when(isFailure, (r) => Option.some(f(r.cause, r)));
+	}
+	onError(f) {
+		return this.onErrorIf(constTrue, f);
+	}
+	onErrorIf(refinement, f) {
+		return this.when(isFailure, (result) => Cause.findErrorOption(result.cause).pipe(Option.filter(refinement), Option.map((error) => f(error, result))));
+	}
+	onErrorTag(tag, f) {
+		return this.onErrorIf((e) => hasProperty(e, "_tag") && (Array.isArray(tag) ? tag.includes(e._tag) : e._tag === tag), f);
+	}
+	onDefect(f) {
+		return this.when(isFailure, (result) => {
+			const defect = Cause.findDefect(result.cause);
+			return Either.isFailure(defect) ? Option.none() : Option.some(f(defect.success, result));
+		});
+	}
+	onInterrupt(f) {
+		return this.when(isFailure, (result) => {
+			const interruptors = Cause.filterInterruptors(result.cause);
+			return Either.isFailure(interruptors) ? Option.none() : Option.some(f(interruptors.success, result));
+		});
+	}
+	orElse(orElse) {
+		return Option.getOrElse(this.output, orElse);
+	}
+	orNull() {
+		return Option.getOrNull(this.output);
+	}
+	render() {
+		if (Option.isSome(this.output)) return this.output.value;
+		else if (isFailure(this.result)) throw Cause.squash(this.result.cause);
+		return null;
+	}
+	exhaustive() {
+		return this.render();
+	}
+};
+//#endregion
+export { Schema as A, matchWithWaiting as C, value as D, touch as E, isResult as F, success as I, TypeId as M, failure as N, waiting as O, initial as P, matchWithError as S, toExit as T, isNotInitial as _, error as a, map as b, failureWithPrevious as c, fromExitWithPrevious as d, getOrElse as f, isInterrupted as g, isInitial as h, cause as i, schemaCodec as j, waitingFrom as k, flatMap as l, isFailure as m, all as n, fail as o, getOrThrow as p, builder as r, failWithPrevious as s, Result_exports as t, fromExit as u, isSuccess as v, replacePrevious as w, match as x, isWaiting as y };