@terrygonguet/utils 0.10.1 → 0.12.0

package/dist/result.mjs

@@ -0,0 +1,129 @@
+//#region src/result.ts
+var Result = class Result {
+	value;
+	error;
+	constructor(value, error) {
+		this.value = value;
+		this.error = error;
+	}
+	asTuple() {
+		return [this.error, this.value];
+	}
+	asObject() {
+		return {
+			value: this.value,
+			error: this.error
+		};
+	}
+	andThen(f) {
+		if (this.error) return this;
+		try {
+			const newValue = f(this.value);
+			if (newValue instanceof Promise) return new AsyncResult(newValue);
+			else return new Result(newValue, null);
+		} catch (error) {
+			return new Result(null, RawError.wrap(error));
+		}
+	}
+	match(onValue, onError) {
+		if (this.error) return onError?.(this.error);
+		else return onError ? onValue(this.value) : void onValue(this.value);
+	}
+	recover(f) {
+		if (!this.error) return this;
+		try {
+			const newValue = f(this.error);
+			if (newValue instanceof Promise) return new AsyncResult(newValue);
+			else return new Result(newValue, null);
+		} catch (error) {
+			return new Result(null, RawError.wrap(error));
+		}
+	}
+	unwrap() {
+		if (!this.error) return this.value;
+		else throw new Error("Tried to unwrap a failed Result");
+	}
+	unwrapErr() {
+		if (this.error) return this.error;
+		else throw new Error("Tried to unwrapErr a successful Result");
+	}
+};
+var AsyncResult = class AsyncResult {
+	promise;
+	constructor(promise) {
+		this.promise = promise;
+	}
+	asTuple() {
+		return this.then((result) => result.asTuple());
+	}
+	asObject() {
+		return this.then((result) => result.asObject());
+	}
+	then(cb) {
+		return this.promise.then((value) => cb(new Result(value, null)), (error) => cb(new Result(null, RawError.wrap(error))));
+	}
+	andThen(f) {
+		return new AsyncResult(this.promise.then((value) => f(value)));
+	}
+	match(onValue, onError) {
+		return this.promise.then((value) => onError ? onValue(value) : void onValue(value), (error) => onError?.(error));
+	}
+	recover(f) {
+		return new AsyncResult(this.promise.then((value) => value, (error) => f(error)));
+	}
+	unwrap() {
+		return this.then((result) => result.unwrap());
+	}
+	unwrapErr() {
+		return this.then((result) => result.unwrapErr());
+	}
+};
+var RawError = class RawError extends Error {
+	name = "RawError";
+	value;
+	constructor(value) {
+		super();
+		this.value = value;
+	}
+	static wrap(error) {
+		if (error instanceof Error) return error;
+		else return new RawError(error);
+	}
+};
+function safe(promiseOrFunction, ...args) {
+	if (promiseOrFunction instanceof Promise) return new AsyncResult(promiseOrFunction);
+	try {
+		const value = promiseOrFunction(...args);
+		if (value instanceof Promise) return new AsyncResult(value);
+		else return new Result(value, null);
+	} catch (error) {
+		return new Result(null, RawError.wrap(error));
+	}
+}
+var SafeFunctionValidationError = class extends Error {
+	name = "SafeFunctionValidationError";
+	issues;
+	constructor(message, issues, options) {
+		super(message, options);
+		this.issues = issues;
+	}
+};
+function makeSafeFn(f, options) {
+	return function(...args) {
+		if (options?.paramsSchema) {
+			const parsed = options.paramsSchema["~standard"].validate(args);
+			if ("then" in parsed) return new Result(null, /* @__PURE__ */ new TypeError("[makeSafeFn] Parameters check failed: Async schemas are not supported"));
+			else if (parsed.issues) return new Result(null, new SafeFunctionValidationError("[makeSafeFn] Parameters check failed", parsed.issues));
+			else args = parsed.value;
+		}
+		if (options?.returnSchema) return safe(f, ...args).andThen((returned) => {
+			const parsed = options.returnSchema["~standard"].validate(returned);
+			if ("then" in parsed) throw new TypeError("[makeSafeFn] Return check failed: Async schemas are not supported");
+			else if (parsed.issues) throw new SafeFunctionValidationError("[makeSafeFn] Return check failed", parsed.issues);
+			else return parsed.value;
+		});
+		else return safe(f, ...args);
+	};
+}
+//#endregion
+export { AsyncResult, Result, SafeFunctionValidationError, makeSafeFn, safe };

package/dist/tableau.d.mts

@@ -0,0 +1,41 @@
+//#region src/tableau.d.ts
+type Predicate<T> = (value: T, index: number, tableau: Tableau<T>) => boolean;
+type AssertPredicate<T, U extends T> = (value: T, index: number, tableau: Tableau<T>) => value is U;
+type Reducer<T, U> = (previousValue: U, currentValue: T, index: number, tableau: Tableau<T>) => U;
+type Mapper<T, U> = (value: T, index: number, tableau: Tableau<T>) => U;
+type Comparer<T> = (a: T, b: T) => number;
+type FlatTableau<Arr, Depth extends number> = {
+  done: Arr;
+  recur: Arr extends Tableau<infer InnerArr> ? FlatTableau<InnerArr, [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20][Depth]> : Arr;
+}[Depth extends -1 ? "done" : "recur"];
+declare class Tableau<T> extends Array<T> {
+  constructor(length?: number);
+  i(idx: number): T | undefined;
+  ientries(): IterableIterator<[number, T]>;
+  ievery<U extends T>(predicate: AssertPredicate<T, U>, thisArg?: any): this is Tableau<U>;
+  ievery(predicate: Predicate<T>, thisArg?: any): boolean;
+  ifilter<U extends T>(predicate: AssertPredicate<T, U>, thisArg?: any): Tableau<U>;
+  ifilter(predicate: Predicate<T>, thisArg?: any): Tableau<T>;
+  ifind<U extends T>(predicate: AssertPredicate<T, U>, thisArg?: any): U | undefined;
+  ifind(predicate: Predicate<T>, thisArg?: any): T | undefined;
+  ifindIndex(predicate: Predicate<T>, thisArg?: any): number | undefined;
+  ifindLast<U extends T>(predicate: AssertPredicate<T, U>, thisArg?: any): U | undefined;
+  ifindLast(predicate: Predicate<T>, thisArg?: any): T | undefined;
+  ifindLastIndex(predicate: Predicate<T>, thisArg?: any): number | undefined;
+  iflat<Depth extends number = 1>(depth?: Depth): FlatTableau<T, Depth>;
+  iflatMap<U>(callback: Mapper<T, U | Tableau<U>>, thisArg?: any): Tableau<U>;
+  iindexOf(searchElement: T, fromIndex?: number): number | undefined;
+  ikeys(): IterableIterator<number>;
+  ilastIndexOf(searchElement: T, fromIndex?: number): number | undefined;
+  imap<U>(callbackFn: Mapper<T, U>, thisArg?: any): Tableau<U>;
+  ireduce<U>(callbackFn: Reducer<T, U>, initialValue: U): U;
+  ireduceRight<U>(callbackFn: Reducer<T, U>, initialValue: U): U;
+  isome(predicate: Predicate<T>, thisArg?: any): boolean;
+  isort(compareFn: Comparer<T>): Tableau<T>;
+  isplice(start: number, deleteCount?: number, ...items: T[]): Tableau<T>;
+  iwith(index: number, value: T): Tableau<T>;
+  static from<T>(source: Iterable<T> | ArrayLike<T>): Tableau<T>;
+  static of<T>(...elements: T[]): Tableau<T>;
+}
+//#endregion
+export { Tableau };

package/dist/tableau.mjs

@@ -0,0 +1,91 @@
+//#region src/tableau.ts
+var Tableau = class Tableau extends Array {
+	constructor(length) {
+		length == void 0 ? super() : super(length);
+	}
+	i(idx) {
+		if (idx == 0) throw new RangeError("Cannot access index 0 in a Tableau");
+		return this.at(idx - 1);
+	}
+	*ientries() {
+		for (let i = 0; i < this.length; i++) yield [i + 1, this[i]];
+	}
+	ievery(predicate, thisArg) {
+		return this.every((value, i) => predicate(value, i + 1, this), thisArg);
+	}
+	ifilter(predicate, thisArg) {
+		return this.filter((value, i) => predicate(value, i + 1, this), thisArg);
+	}
+	ifind(predicate, thisArg) {
+		return this.find((value, i) => predicate(value, i + 1, this), thisArg);
+	}
+	ifindIndex(predicate, thisArg) {
+		const idx = this.findIndex((value, i) => predicate(value, i + 1, this), thisArg);
+		return idx == -1 ? void 0 : idx + 1;
+	}
+	ifindLast(predicate, thisArg) {
+		return this.findLast((value, i) => predicate(value, i + 1, this), thisArg);
+	}
+	ifindLastIndex(predicate, thisArg) {
+		const idx = this.findLastIndex((value, i) => predicate(value, i + 1, this), thisArg);
+		return idx == -1 ? void 0 : idx + 1;
+	}
+	iflat(depth) {
+		return this.flat(depth);
+	}
+	iflatMap(callback, thisArg) {
+		return this.flatMap((value, i) => callback(value, i + 1, this), thisArg);
+	}
+	iindexOf(searchElement, fromIndex = 1) {
+		if (fromIndex == 0) throw new RangeError("Cannot access index 0 in a Tableau");
+		const idx = this.indexOf(searchElement, fromIndex - 1);
+		return idx == -1 ? void 0 : idx + 1;
+	}
+	*ikeys() {
+		for (const key of this.keys()) yield key + 1;
+	}
+	ilastIndexOf(searchElement, fromIndex = this.length) {
+		if (fromIndex == 0) throw new RangeError("Cannot access index 0 in a Tableau");
+		const idx = this.lastIndexOf(searchElement, fromIndex - 1);
+		return idx == -1 ? void 0 : idx + 1;
+	}
+	imap(callbackFn, thisArg) {
+		return this.map((value, i) => callbackFn(value, i + 1, this), thisArg);
+	}
+	ireduce(callbackFn, initialValue) {
+		return this.reduce((acc, cur, i) => callbackFn(acc, cur, i + 1, this), initialValue);
+	}
+	ireduceRight(callbackFn, initialValue) {
+		return this.reduceRight((acc, cur, i) => callbackFn(acc, cur, i + 1, this), initialValue);
+	}
+	isome(predicate, thisArg) {
+		return this.some((value, i) => predicate(value, i + 1, this), thisArg);
+	}
+	isort(compareFn) {
+		return this.toSorted(compareFn);
+	}
+	isplice(start, deleteCount, ...items) {
+		if (start == 0) throw new RangeError("Cannot access index 0 in a Tableau");
+		return this.toSpliced(start - 1, deleteCount, ...items);
+	}
+	iwith(index, value) {
+		if (index == 0) throw new RangeError("Cannot access index 0 in a Tableau");
+		return this.with(index - 1, value);
+	}
+	static from(source) {
+		if ("length" in source) {
+			const litanie = new Tableau(source.length);
+			for (let i = 0; i < source.length; i++) litanie[i] = source[i];
+			return litanie;
+		} else {
+			const litanie = new Tableau();
+			for (const element of source) litanie.push(element);
+			return litanie;
+		}
+	}
+	static of(...elements) {
+		return Tableau.from(elements);
+	}
+};
+//#endregion
+export { Tableau };

package/dist/task.d.mts

@@ -0,0 +1,38 @@
+import { Option } from "./option.mjs";
+
+//#region src/task.d.ts
+declare class Task<T, E extends Error = Error> {
+  _state: {
+    type: "pending";
+    promise: Promise<void>;
+  } | {
+    type: "failed";
+    error: E;
+  } | {
+    type: "complete";
+    value: T;
+  };
+  private constructor();
+  [Symbol.iterator](): Iterator<Task<T, E>, T>;
+  static do<T, E extends Error>(f: () => Iterator<Task<any, E> | Promise<any> | E, T, any>): Task<T, E>;
+  static complete<T, E extends Error = Error>(value: T): Task<T, E>;
+  static failed<T, E extends Error = Error>(error: E): Task<T, E>;
+  static fromPromise<T, E extends Error = Error>(promise: Promise<T>): Task<T, E>;
+  static fromOption<T, E extends Error = Error>(option: Option<T>, whenNone: E): Task<T, E>;
+  static from<T, E extends Error = Error>(thing: T | E | Promise<T> | Task<T, E>): Task<T, E>;
+  static wrapFunction<Args extends any[], T, E extends Error = Error>(f: (...args: Args) => T | Promise<T>): (...args: Args) => Task<T, E>;
+  static isTask<T, E extends Error = Error>(maybeTask: unknown): maybeTask is Task<T, E>;
+  [Symbol.toPrimitive](): string;
+  isPending(): boolean;
+  isComplete(): boolean;
+  isFailed(): boolean;
+  then<U>(onResolve: (value: T) => U | Promise<U>, onReject: (error: E) => U | Promise<U>): U | Promise<U>;
+  map<U, E2 extends E>(f: (value: T) => U | Promise<U>): Task<U, E2>;
+  flatMap<U, E2 extends E>(f: (value: T) => Task<U, E2>): Task<U, E2>;
+  flatten(): T extends Task<infer U> ? Task<U> : Task<T>;
+  orDefault(defaultValue: T): Promise<T>;
+  unwrap(): T;
+  toString(): string;
+}
+//#endregion
+export { Task };

package/dist/task.mjs

@@ -0,0 +1,178 @@
+//#region src/task.ts
+var Task = class Task {
+	_state;
+	constructor(state) {
+		if (state.type == "pending") {
+			const promise = state.promise.then((value) => {
+				this._state = {
+					type: "complete",
+					value
+				};
+			}, (error) => {
+				this._state = {
+					type: "failed",
+					error
+				};
+			});
+			this._state = {
+				type: "pending",
+				promise
+			};
+		} else this._state = state;
+	}
+	*[Symbol.iterator]() {
+		yield this;
+		if (this._state.type == "complete") return this._state.value;
+		else if (this._state.type == "pending") throw new Error("Tried to unwrap a pending Task via its iterator");
+		else throw new Error("Tried to unwrap a failed Task via its iterator");
+	}
+	static do(f) {
+		const { promise, resolve, reject } = Promise.withResolvers();
+		const root = Task.fromPromise(promise);
+		const gen = f();
+		let iter;
+		function step(value) {
+			try {
+				iter = gen.next(value);
+			} catch (error) {
+				return stop(error);
+			}
+			if (iter.done) return resolve(iter.value);
+			const yielded = iter.value;
+			if (Error.isError(yielded)) stop(yielded);
+			else if (Task.isTask(yielded)) switch (yielded._state.type) {
+				case "complete":
+					step(yielded._state.value);
+					break;
+				case "failed":
+					stop(yielded._state.error);
+					break;
+				case "pending":
+					yielded.then((value) => step(value), (error) => stop(error));
+					break;
+			}
+			else if ("then" in yielded && typeof yielded.then == "function") yielded.then((value) => step(value), (error) => stop(error));
+			else step(yielded);
+		}
+		function stop(error) {
+			gen.return?.(void 0);
+			reject(error);
+		}
+		step();
+		return root;
+	}
+	static complete(value) {
+		return new Task({
+			type: "complete",
+			value
+		});
+	}
+	static failed(error) {
+		return new Task({
+			type: "failed",
+			error
+		});
+	}
+	static fromPromise(promise) {
+		return new Task({
+			type: "pending",
+			promise
+		});
+	}
+	static fromOption(option, whenNone) {
+		if (option._kind == "Some") return new Task({
+			type: "complete",
+			value: option.value
+		});
+		else return new Task({
+			type: "failed",
+			error: whenNone
+		});
+	}
+	static from(thing) {
+		if (thing instanceof Promise) return Task.fromPromise(thing);
+		else if (thing instanceof Error) return Task.failed(thing);
+		else if (thing instanceof Task) return thing;
+		else return Task.complete(thing);
+	}
+	static wrapFunction(f) {
+		return (...args) => {
+			try {
+				return Task.from(f(...args));
+			} catch (error) {
+				if (error instanceof Error) return Task.failed(error);
+				else return Task.failed(new Error("Wrapped", { cause: error }));
+			}
+		};
+	}
+	static isTask(maybeTask) {
+		return maybeTask instanceof Task;
+	}
+	[Symbol.toPrimitive]() {
+		return this.toString();
+	}
+	isPending() {
+		return this._state.type == "pending";
+	}
+	isComplete() {
+		return this._state.type == "complete";
+	}
+	isFailed() {
+		return this._state.type == "failed";
+	}
+	then(onResolve, onReject) {
+		if (this._state.type == "complete") return onResolve(this._state.value);
+		else if (this._state.type == "pending") return this._state.promise.then(() => {
+			if (this._state.type == "complete") return onResolve(this._state.value);
+			else if (this._state.type == "failed") return onReject(this._state.error);
+			else return onReject(/* @__PURE__ */ new Error("Task is in an invalid state"));
+		});
+		else return onReject(this._state.error);
+	}
+	map(f) {
+		if (this._state.type == "pending") return Task.fromPromise(this._state.promise.then(() => this.map(f)));
+		else if (this._state.type == "complete") try {
+			const result = f(this._state.value);
+			if (result instanceof Promise) return Task.fromPromise(result);
+			else return Task.complete(result);
+		} catch (error) {
+			return Task.failed(error);
+		}
+		else return this;
+	}
+	flatMap(f) {
+		if (this._state.type == "pending") return Task.fromPromise(this._state.promise.then(() => this.flatMap(f)));
+		else if (this._state.type == "complete") return f(this._state.value);
+		else return this;
+	}
+	flatten() {
+		if (this._state.type == "complete") return Task.isTask(this._state.value) ? this._state.value : this;
+		else if (this._state.type == "failed") return this;
+		else return Task.fromPromise(this._state.promise.then(() => this.flatten()));
+	}
+	orDefault(defaultValue) {
+		if (this._state.type == "complete") return Promise.resolve(this._state.value);
+		else if (this._state.type == "failed") return Promise.resolve(defaultValue);
+		else return this._state.promise.then(() => {
+			if (this._state.type == "complete") return this._state.value;
+			else return defaultValue;
+		});
+	}
+	unwrap() {
+		if (this._state.type == "complete") return this._state.value;
+		else if (this._state.type == "failed") throw new Error("Tried to unwrap a failed Task");
+		else throw new Error("Tried to unwrap a pending Task");
+	}
+	toString() {
+		if (this._state.type == "failed") return `Task(Failed: ${this._state.error.message})`;
+		else if (this._state.type == "pending") return "Task(Pending)";
+		switch (typeof this._state.value) {
+			case "string": return `Task(Complete: "${this._state.value}")`;
+			case "function":
+			case "object": return `Task(Complete: ${JSON.stringify(this._state.value)})`;
+			default: return `Task(Complete: ${this._state.value})`;
+		}
+	}
+};
+//#endregion
+export { Task };

package/package.json

@@ -1,75 +1,80 @@
-{
-	"name": "@terrygonguet/utils",
-	"version": "0.10.1",
-	"type": "module",
-	"license": "MIT",
-	"scripts": {
-		"dev": "vitest --watch --typecheck --update",
-		"build": "tsup",
-		"test": "vitest test --typecheck"
-	},
-	"files": [
-		"dist"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"default": "./dist/index.js"
-		},
-		"./async": {
-			"types": "./dist/async.d.ts",
-			"import": "./dist/async.js",
-			"default": "./dist/async.js"
-		},
-		"./json": {
-			"types": "./dist/json.d.ts",
-			"import": "./dist/json.js",
-			"default": "./dist/json.js"
-		},
-		"./option": {
-			"types": "./dist/option.d.ts",
-			"import": "./dist/option.js",
-			"default": "./dist/option.js"
-		},
-		"./random": {
-			"types": "./dist/random.d.ts",
-			"import": "./dist/random.js",
-			"default": "./dist/random.js"
-		},
-		"./result": {
-			"types": "./dist/result.d.ts",
-			"import": "./dist/result.js",
-			"default": "./dist/result.js"
-		},
-		"./tableau": {
-			"types": "./dist/tableau.d.ts",
-			"import": "./dist/tableau.js",
-			"default": "./dist/tableau.js"
-		}
-	},
-	"devDependencies": {
-		"@types/benchmark": "^2.1.5",
-		"benchmark": "^2.1.4",
-		"prettier": "^3.8.1",
-		"tsup": "^8.5.1",
-		"typescript": "^5.9.3",
-		"vite": "^7.3.1",
-		"vitest": "^4.0.18"
-	},
-	"author": {
-		"email": "terry@gonguet.com",
-		"name": "Terry Gonguet",
-		"url": "https://terry.gonguet.com/"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/terrygonguet/utils.git"
-	},
-	"bugs": {
-		"url": "https://github.com/terrygonguet/utils/issues"
-	},
-	"dependencies": {
-		"@standard-schema/spec": "^1.1.0"
-	}
-}
+{
+	"name": "@terrygonguet/utils",
+	"version": "0.12.0",
+	"type": "module",
+	"license": "MIT",
+	"scripts": {
+		"dev": "vitest --watch --typecheck --update",
+		"build": "tsdown",
+		"test": "vitest test --typecheck"
+	},
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./async": {
+			"types": "./dist/async.d.ts",
+			"import": "./dist/async.js",
+			"default": "./dist/async.js"
+		},
+		"./json": {
+			"types": "./dist/json.d.ts",
+			"import": "./dist/json.js",
+			"default": "./dist/json.js"
+		},
+		"./option": {
+			"types": "./dist/option.d.ts",
+			"import": "./dist/option.js",
+			"default": "./dist/option.js"
+		},
+		"./random": {
+			"types": "./dist/random.d.ts",
+			"import": "./dist/random.js",
+			"default": "./dist/random.js"
+		},
+		"./result": {
+			"types": "./dist/result.d.ts",
+			"import": "./dist/result.js",
+			"default": "./dist/result.js"
+		},
+		"./tableau": {
+			"types": "./dist/tableau.d.ts",
+			"import": "./dist/tableau.js",
+			"default": "./dist/tableau.js"
+		},
+		"./task": {
+			"types": "./dist/task.d.ts",
+			"import": "./dist/task.js",
+			"default": "./dist/task.js"
+		}
+	},
+	"devDependencies": {
+		"@types/benchmark": "^2.1.5",
+		"benchmark": "^2.1.4",
+		"prettier": "^3.8.3",
+		"tsdown": "^0.21.10",
+		"typescript": "^6.0.3",
+		"vite": "^8.0.10",
+		"vitest": "^4.1.5"
+	},
+	"author": {
+		"email": "terry@gonguet.com",
+		"name": "Terry Gonguet",
+		"url": "https://terry.gonguet.com/"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/terrygonguet/utils.git"
+	},
+	"bugs": {
+		"url": "https://github.com/terrygonguet/utils/issues"
+	},
+	"dependencies": {
+		"@standard-schema/spec": "^1.1.0"
+	}
+}