@e280/stz 0.2.27 → 0.2.29

package/README.md

@@ -315,6 +315,46 @@ const stop = cycle(async() => {
 stop()
 ```
 
+### 🍏 ok
+> tiny result toolkit for saying "this worked" or "this did not work"
+
+rust-inspired pattern for explicit error handling instead of the usual js yolo vibes
+
+#### result shapes
+- `Ok<Value>` — `{ok: true, value}`
+- `Err<E>` — `{ok: false, error}`
+- `Result<Value, E>` — either of the above
+
+#### constructors
+- `ok(value)` — make a successful result
+  ```ts
+  const result = ok("fusion stable")
+    // {ok: true, value: "fusion stable"}
+  ```
+- `err(error)` — make a failed result
+  ```ts
+  const result = err("containment lost")
+    // {ok: false, error: "containment lost"}
+  ```
+
+#### helpers
+- `grab(result)` — get the value, or `undefined`
+  ```ts
+  grab(ok(123))
+    // 123
+
+  grab(err("nope"))
+    // undefined
+  ```
+- `need(result)` — get the value, or throw
+  ```ts
+  need(ok(123))
+    // 123
+
+  need(err("containment lost"))
+    // throws Error("containment lost")
+  ```
+
 
 
 <br/>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/stz",
-	"version": "0.2.27",
+	"version": "0.2.29",
 	"description": "everyday ts fns for everything",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -22,7 +22,7 @@
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +"
 	},
 	"devDependencies": {
-		"@e280/science": "^0.1.9",
+		"@e280/science": "^0.1.10",
 		"@types/node": "^25.5.0",
 		"typescript": "^6.0.2"
 	},

package/s/assert.ts

@@ -0,0 +1,10 @@
+
+export function assert<Value>(
+		value: Value,
+		message = "assert fail",
+	): asserts value  {
+
+	if (!value)
+		throw new Error(message)
+}
+

package/s/dig/dig.ts

@@ -0,0 +1,25 @@
+
+import {is} from "../is.js"
+import {ok, err} from "../ok/index.js"
+
+/** drill into an object/array tree and return the value at the given path */
+export function dig<Value>(
+		target: any,
+		path: (string | number)[],
+	) {
+
+	let current: any = target
+
+	for (const key of path) {
+		if (!(is.object(current) || is.array(current)))
+			return err("not traversable" as const)
+
+		if (!Object.hasOwn(current, key))
+			return err("not found" as const)
+
+		current = current[key]
+	}
+
+	return ok(current as Value)
+}
+

package/s/dig/test.ts

@@ -0,0 +1,52 @@
+
+import {suite, expect, assert} from "@e280/science"
+import {dig} from "./dig.js"
+import {need} from "../ok/index.js"
+
+const check = (t: any, path: (string | number)[]) => ({
+	ok: (value: any) => async() => {
+		const result = dig(t, path)
+		expect(need(result)).is(value)
+	},
+	err: (e: any) => async() => {
+		const result = dig(t, path)
+		assert(!result.ok)
+		expect(result.error).is(e)
+	},
+})
+
+export default suite({
+	"get value": check({a: 2}, ["a"])
+		.ok(2),
+
+	"get undefined": check({a: undefined}, ["a"])
+		.ok(undefined),
+
+	"get null": check({a: null}, ["a"])
+		.ok(null),
+
+	"nested get value": check({a: {b: 2}}, ["a", "b"])
+		.ok(2),
+
+	"array get value": check(["a", "b"], [1])
+		.ok("b"),
+
+	"null not traversable": check(null, ["a"])
+		.err("not traversable"),
+
+	"undefined not traversable": check(undefined, ["a"])
+		.err("not traversable"),
+
+	"missing key not found": check({a: 2}, ["b"])
+		.err("not found"),
+
+	"array index not found": check(["a", "b"], [2])
+		.err("not found"),
+
+	"midway not traversable": check({a: 5}, ["a", "b"])
+		.err("not traversable"),
+
+	"midway not found": check({a: {}}, ["a", "b"])
+		.err("not found"),
+})
+

package/s/drill.ts

@@ -1,7 +1,10 @@
 
 import {is} from "./is.js"
 
-/** return a value within an object tree, found at the given path. */
+/**
+ * return a value within an object tree, found at the given path.
+ * @deprecated prefer `dig` instead
+ */
 export function drill<xResult>(
 		object: {[key: string]: any},
 		path: string[],

package/s/index.ts

@@ -15,6 +15,7 @@ export * from "./debounce/microbounce.js"
 export * from "./debounce/types.js"
 
 export * from "./deep/index.js"
+export * from "./dig/dig.js"
 
 export * from "./g/map.js"
 export * from "./g/pool.js"
@@ -23,11 +24,12 @@ export * from "./g/weak-map.js"
 
 export * from "./queue/queue.js"
 
+export * from "./ok/index.js"
 export * from "./toq/index.js"
-
 export * from "./maybe/index.js"
 
 export * from "./all.js"
+export * from "./assert.js"
 export * from "./coalesce.js"
 export * from "./collect.js"
 export * from "./concurrent.js"
@@ -53,6 +55,7 @@ export * from "./provide.js"
 export * from "./pubsub.js"
 export * from "./scope.js"
 export * from "./templating.js"
+export * from "./thrown.js"
 export * from "./time.js"
 export * from "./trash.js"
 export * from "./types.js"

package/s/ok/fns/err.ts

@@ -0,0 +1,8 @@
+
+import type {Err} from "../types/err.js"
+
+/** failure */
+export function err<E = string>(error: E): Err<E> {
+	return {ok: false, error}
+}
+

package/s/ok/fns/grab.ts

@@ -0,0 +1,10 @@
+
+import type {Result} from "../types/result.js"
+
+/** get value or undefined */
+export function grab<Value>(result: Result<Value, unknown>): Value | undefined {
+	return result.ok
+		? result.value
+		: undefined
+}
+

package/s/ok/fns/need.ts

@@ -0,0 +1,20 @@
+
+import type {Result} from "../types/result.js"
+
+/** get value or throw error */
+export function need<Value, E>(result: Result<Value, E>): Value {
+	if (result.ok)
+		return result.value
+
+	const {error} = result
+
+	if (error instanceof Error)
+		throw error
+
+	else if (typeof error === "string")
+		throw new Error(error)
+
+	else
+		throw new Error("unknown")
+}
+

package/s/ok/fns/ok.ts

@@ -0,0 +1,8 @@
+
+import type {Ok} from "../types/ok.js"
+
+/** success */
+export function ok<Value>(value: Value): Ok<Value> {
+	return {ok: true, value}
+}
+

package/s/ok/index.ts

@@ -0,0 +1,10 @@
+
+export * from "./fns/ok.js"
+export * from "./fns/err.js"
+export * from "./fns/grab.js"
+export * from "./fns/need.js"
+
+export * from "./types/ok.js"
+export * from "./types/err.js"
+export * from "./types/result.js"
+

package/s/ok/test.ts

@@ -0,0 +1,47 @@
+
+import {expect, suite, test} from "@e280/science"
+import {thrown} from "../thrown.js"
+import {ok, err, grab, need} from "./index.js"
+
+export default suite({
+	"ok": test(async() => {
+		expect(ok(123).ok).is(true)
+		expect(ok(123).value).is(123)
+		expect("error" in ok(123)).is(false)
+	}),
+
+	"err": test(async() => {
+		expect(err("nope").ok).is(false)
+		expect(err("nope").error).is("nope")
+		expect("value" in err("nope")).is(false)
+	}),
+
+	"grab": test(async() => {
+		expect(grab(ok(123))).is(123)
+		expect(grab(err("nope"))).is(undefined)
+	}),
+
+	"need": test(async() => {
+		expect(need(ok(123))).is(123)
+		expect(() => need(err("nope"))).throws()
+	}),
+
+	"need error handling": {
+		"rethrows errors": test(async() => {
+			const error = new TypeError()
+			expect(() => need(err(error))).throws(TypeError)
+			expect(thrown(() => need(err(error)))).is(error)
+		}),
+
+		"upgrades strings to errors": test(async() => {
+			expect(() => need(err("nope"))).throws(Error)
+			expect(thrown(() => need(err("nope"))).message).is("nope")
+		}),
+
+		"everything else is unknown": test(async() => {
+			expect(() => need(err({code: 234}))).throws(Error)
+			expect(thrown(() => need(err({code: 234}))).message).is("unknown")
+		}),
+	},
+})
+

package/s/ok/types/err.ts

@@ -0,0 +1,4 @@
+
+/** failure */
+export type Err<E> = {ok: false, error: E}
+

package/s/ok/types/ok.ts

@@ -0,0 +1,4 @@
+
+/** success */
+export type Ok<Value> = {ok: true, value: Value}
+

package/s/ok/types/result.ts

@@ -0,0 +1,10 @@
+
+import type {Ok} from "./ok.js"
+import type {Err} from "./err.js"
+
+/** success or failure */
+export type Result<Value, E = unknown> = (
+	| Ok<Value>
+	| Err<E>
+)
+

package/s/tests.test.ts

@@ -1,5 +1,5 @@
 
-import {Science} from "@e280/science"
+import {science} from "@e280/science"
 
 import data from "./data/data.test.js"
 import debounce from "./debounce/debounce.test.js"
@@ -8,8 +8,10 @@ import deep from "./deep/index.test.js"
 import queue from "./queue/queue.test.js"
 import toq from "./toq/toq.test.js"
 import maybe from "./maybe/test.js"
+import dig from "./dig/test.js"
+import ok from "./ok/test.js"
 
-await Science.run({
+await science.run({
 	data,
 	debounce,
 	microbounce,
@@ -17,5 +19,7 @@ await Science.run({
 	queue,
 	toq,
 	maybe,
+	dig,
+	ok,
 })
 

package/s/thrown.ts

@@ -0,0 +1,7 @@
+
+export function thrown(fn: () => unknown): any {
+	try { fn() }
+	catch (error) { return error }
+	throw new Error("didn't throw")
+}
+

package/x/assert.d.ts

@@ -0,0 +1 @@
+export declare function assert<Value>(value: Value, message?: string): asserts value;

package/x/assert.js

@@ -0,0 +1,5 @@
+export function assert(value, message = "assert fail") {
+    if (!value)
+        throw new Error(message);
+}
+//# sourceMappingURL=assert.js.map

package/x/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../s/assert.ts"],"names":[],"mappings":"AACA,MAAM,UAAU,MAAM,CACpB,KAAY,EACZ,OAAO,GAAG,aAAa;IAGxB,IAAI,CAAC,KAAK;QACT,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC"}

package/x/dig/dig.d.ts

@@ -0,0 +1,2 @@
+/** drill into an object/array tree and return the value at the given path */
+export declare function dig<Value>(target: any, path: (string | number)[]): import("../ok/index.js").Err<"not traversable"> | import("../ok/index.js").Err<"not found"> | import("../ok/index.js").Ok<Value>;

package/x/dig/dig.js

@@ -0,0 +1,15 @@
+import { is } from "../is.js";
+import { ok, err } from "../ok/index.js";
+/** drill into an object/array tree and return the value at the given path */
+export function dig(target, path) {
+    let current = target;
+    for (const key of path) {
+        if (!(is.object(current) || is.array(current)))
+            return err("not traversable");
+        if (!Object.hasOwn(current, key))
+            return err("not found");
+        current = current[key];
+    }
+    return ok(current);
+}
+//# sourceMappingURL=dig.js.map

package/x/dig/dig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dig.js","sourceRoot":"","sources":["../../s/dig/dig.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,EAAE,EAAC,MAAM,UAAU,CAAA;AAC3B,OAAO,EAAC,EAAE,EAAE,GAAG,EAAC,MAAM,gBAAgB,CAAA;AAEtC,6EAA6E;AAC7E,MAAM,UAAU,GAAG,CACjB,MAAW,EACX,IAAyB;IAG1B,IAAI,OAAO,GAAQ,MAAM,CAAA;IAEzB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC7C,OAAO,GAAG,CAAC,iBAA0B,CAAC,CAAA;QAEvC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC;YAC/B,OAAO,GAAG,CAAC,WAAoB,CAAC,CAAA;QAEjC,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAED,OAAO,EAAE,CAAC,OAAgB,CAAC,CAAA;AAC5B,CAAC"}

package/x/dig/test.d.ts

@@ -0,0 +1,14 @@
+declare const _default: {
+    "get value": () => Promise<void>;
+    "get undefined": () => Promise<void>;
+    "get null": () => Promise<void>;
+    "nested get value": () => Promise<void>;
+    "array get value": () => Promise<void>;
+    "null not traversable": () => Promise<void>;
+    "undefined not traversable": () => Promise<void>;
+    "missing key not found": () => Promise<void>;
+    "array index not found": () => Promise<void>;
+    "midway not traversable": () => Promise<void>;
+    "midway not found": () => Promise<void>;
+};
+export default _default;

package/x/dig/test.js

@@ -0,0 +1,39 @@
+import { suite, expect, assert } from "@e280/science";
+import { dig } from "./dig.js";
+import { need } from "../ok/index.js";
+const check = (t, path) => ({
+    ok: (value) => async () => {
+        const result = dig(t, path);
+        expect(need(result)).is(value);
+    },
+    err: (e) => async () => {
+        const result = dig(t, path);
+        assert(!result.ok);
+        expect(result.error).is(e);
+    },
+});
+export default suite({
+    "get value": check({ a: 2 }, ["a"])
+        .ok(2),
+    "get undefined": check({ a: undefined }, ["a"])
+        .ok(undefined),
+    "get null": check({ a: null }, ["a"])
+        .ok(null),
+    "nested get value": check({ a: { b: 2 } }, ["a", "b"])
+        .ok(2),
+    "array get value": check(["a", "b"], [1])
+        .ok("b"),
+    "null not traversable": check(null, ["a"])
+        .err("not traversable"),
+    "undefined not traversable": check(undefined, ["a"])
+        .err("not traversable"),
+    "missing key not found": check({ a: 2 }, ["b"])
+        .err("not found"),
+    "array index not found": check(["a", "b"], [2])
+        .err("not found"),
+    "midway not traversable": check({ a: 5 }, ["a", "b"])
+        .err("not traversable"),
+    "midway not found": check({ a: {} }, ["a", "b"])
+        .err("not found"),
+});
+//# sourceMappingURL=test.js.map

package/x/dig/test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.js","sourceRoot":"","sources":["../../s/dig/test.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAC,MAAM,eAAe,CAAA;AACnD,OAAO,EAAC,GAAG,EAAC,MAAM,UAAU,CAAA;AAC5B,OAAO,EAAC,IAAI,EAAC,MAAM,gBAAgB,CAAA;AAEnC,MAAM,KAAK,GAAG,CAAC,CAAM,EAAE,IAAyB,EAAE,EAAE,CAAC,CAAC;IACrD,EAAE,EAAE,CAAC,KAAU,EAAE,EAAE,CAAC,KAAK,IAAG,EAAE;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;QAC3B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;IAC/B,CAAC;IACD,GAAG,EAAE,CAAC,CAAM,EAAE,EAAE,CAAC,KAAK,IAAG,EAAE;QAC1B,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;QAC3B,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QAClB,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC3B,CAAC;CACD,CAAC,CAAA;AAEF,eAAe,KAAK,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC,EAAC,CAAC,EAAE,CAAC,EAAC,EAAE,CAAC,GAAG,CAAC,CAAC;SAC/B,EAAE,CAAC,CAAC,CAAC;IAEP,eAAe,EAAE,KAAK,CAAC,EAAC,CAAC,EAAE,SAAS,EAAC,EAAE,CAAC,GAAG,CAAC,CAAC;SAC3C,EAAE,CAAC,SAAS,CAAC;IAEf,UAAU,EAAE,KAAK,CAAC,EAAC,CAAC,EAAE,IAAI,EAAC,EAAE,CAAC,GAAG,CAAC,CAAC;SACjC,EAAE,CAAC,IAAI,CAAC;IAEV,kBAAkB,EAAE,KAAK,CAAC,EAAC,CAAC,EAAE,EAAC,CAAC,EAAE,CAAC,EAAC,EAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;SAChD,EAAE,CAAC,CAAC,CAAC;IAEP,iBAAiB,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;SACvC,EAAE,CAAC,GAAG,CAAC;IAET,sBAAsB,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;SACxC,GAAG,CAAC,iBAAiB,CAAC;IAExB,2BAA2B,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;SAClD,GAAG,CAAC,iBAAiB,CAAC;IAExB,uBAAuB,EAAE,KAAK,CAAC,EAAC,CAAC,EAAE,CAAC,EAAC,EAAE,CAAC,GAAG,CAAC,CAAC;SAC3C,GAAG,CAAC,WAAW,CAAC;IAElB,uBAAuB,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;SAC7C,GAAG,CAAC,WAAW,CAAC;IAElB,wBAAwB,EAAE,KAAK,CAAC,EAAC,CAAC,EAAE,CAAC,EAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;SACjD,GAAG,CAAC,iBAAiB,CAAC;IAExB,kBAAkB,EAAE,KAAK,CAAC,EAAC,CAAC,EAAE,EAAE,EAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;SAC5C,GAAG,CAAC,WAAW,CAAC;CAClB,CAAC,CAAA"}

package/x/drill.d.ts

@@ -1,4 +1,7 @@
-/** return a value within an object tree, found at the given path. */
+/**
+ * return a value within an object tree, found at the given path.
+ * @deprecated prefer `dig` instead
+ */
 export declare function drill<xResult>(object: {
     [key: string]: any;
 }, path: string[]): xResult;

package/x/drill.js

@@ -1,5 +1,8 @@
 import { is } from "./is.js";
-/** return a value within an object tree, found at the given path. */
+/**
+ * return a value within an object tree, found at the given path.
+ * @deprecated prefer `dig` instead
+ */
 export function drill(object, path) {
     let current = object;
     for (const key of path) {

package/x/drill.js.map

@@ -1 +1 @@
-{"version":3,"file":"drill.js","sourceRoot":"","sources":["../s/drill.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,EAAE,EAAC,MAAM,SAAS,CAAA;AAE1B,qEAAqE;AACrE,MAAM,UAAU,KAAK,CACnB,MAA4B,EAC5B,IAAc;IAGf,IAAI,OAAO,GAAQ,MAAM,CAAA;IAEzB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QACtB,IAAI,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC;YAClB,MAAK;IACP,CAAC;IAED,OAAO,OAAO,CAAA;AACf,CAAC"}
+{"version":3,"file":"drill.js","sourceRoot":"","sources":["../s/drill.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,EAAE,EAAC,MAAM,SAAS,CAAA;AAE1B;;;GAGG;AACH,MAAM,UAAU,KAAK,CACnB,MAA4B,EAC5B,IAAc;IAGf,IAAI,OAAO,GAAQ,MAAM,CAAA;IAEzB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QACtB,IAAI,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC;YAClB,MAAK;IACP,CAAC;IAED,OAAO,OAAO,CAAA;AACf,CAAC"}

package/x/index.d.ts

@@ -12,14 +12,17 @@ export * from "./debounce/debounce.js";
 export * from "./debounce/microbounce.js";
 export * from "./debounce/types.js";
 export * from "./deep/index.js";
+export * from "./dig/dig.js";
 export * from "./g/map.js";
 export * from "./g/pool.js";
 export * from "./g/set.js";
 export * from "./g/weak-map.js";
 export * from "./queue/queue.js";
+export * from "./ok/index.js";
 export * from "./toq/index.js";
 export * from "./maybe/index.js";
 export * from "./all.js";
+export * from "./assert.js";
 export * from "./coalesce.js";
 export * from "./collect.js";
 export * from "./concurrent.js";
@@ -45,6 +48,7 @@ export * from "./provide.js";
 export * from "./pubsub.js";
 export * from "./scope.js";
 export * from "./templating.js";
+export * from "./thrown.js";
 export * from "./time.js";
 export * from "./trash.js";
 export * from "./types.js";

package/x/index.js

@@ -12,14 +12,17 @@ export * from "./debounce/debounce.js";
 export * from "./debounce/microbounce.js";
 export * from "./debounce/types.js";
 export * from "./deep/index.js";
+export * from "./dig/dig.js";
 export * from "./g/map.js";
 export * from "./g/pool.js";
 export * from "./g/set.js";
 export * from "./g/weak-map.js";
 export * from "./queue/queue.js";
+export * from "./ok/index.js";
 export * from "./toq/index.js";
 export * from "./maybe/index.js";
 export * from "./all.js";
+export * from "./assert.js";
 export * from "./coalesce.js";
 export * from "./collect.js";
 export * from "./concurrent.js";
@@ -45,6 +48,7 @@ export * from "./provide.js";
 export * from "./pubsub.js";
 export * from "./scope.js";
 export * from "./templating.js";
+export * from "./thrown.js";
 export * from "./time.js";
 export * from "./trash.js";
 export * from "./types.js";

package/x/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../s/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAA;AAC3C,cAAc,+BAA+B,CAAA;AAC7C,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAE7B,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,qBAAqB,CAAA;AAEnC,cAAc,iBAAiB,CAAA;AAE/B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAE/B,cAAc,kBAAkB,CAAA;AAEhC,cAAc,gBAAgB,CAAA;AAE9B,cAAc,kBAAkB,CAAA;AAEhC,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../s/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAA;AAC3C,cAAc,+BAA+B,CAAA;AAC7C,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAE7B,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,qBAAqB,CAAA;AAEnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAE5B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAE/B,cAAc,kBAAkB,CAAA;AAEhC,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAEhC,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}

package/x/ok/fns/err.d.ts

@@ -0,0 +1,3 @@
+import type { Err } from "../types/err.js";
+/** failure */
+export declare function err<E = string>(error: E): Err<E>;

package/x/ok/fns/err.js

@@ -0,0 +1,5 @@
+/** failure */
+export function err(error) {
+    return { ok: false, error };
+}
+//# sourceMappingURL=err.js.map

package/x/ok/fns/err.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"err.js","sourceRoot":"","sources":["../../../s/ok/fns/err.ts"],"names":[],"mappings":"AAGA,cAAc;AACd,MAAM,UAAU,GAAG,CAAa,KAAQ;IACvC,OAAO,EAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAC,CAAA;AAC1B,CAAC"}

package/x/ok/fns/grab.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../types/result.js";
+/** get value or undefined */
+export declare function grab<Value>(result: Result<Value, unknown>): Value | undefined;

package/x/ok/fns/grab.js

@@ -0,0 +1,7 @@
+/** get value or undefined */
+export function grab(result) {
+    return result.ok
+        ? result.value
+        : undefined;
+}
+//# sourceMappingURL=grab.js.map

package/x/ok/fns/grab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grab.js","sourceRoot":"","sources":["../../../s/ok/fns/grab.ts"],"names":[],"mappings":"AAGA,6BAA6B;AAC7B,MAAM,UAAU,IAAI,CAAQ,MAA8B;IACzD,OAAO,MAAM,CAAC,EAAE;QACf,CAAC,CAAC,MAAM,CAAC,KAAK;QACd,CAAC,CAAC,SAAS,CAAA;AACb,CAAC"}

package/x/ok/fns/need.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../types/result.js";
+/** get value or throw error */
+export declare function need<Value, E>(result: Result<Value, E>): Value;

package/x/ok/fns/need.js

@@ -0,0 +1,13 @@
+/** get value or throw error */
+export function need(result) {
+    if (result.ok)
+        return result.value;
+    const { error } = result;
+    if (error instanceof Error)
+        throw error;
+    else if (typeof error === "string")
+        throw new Error(error);
+    else
+        throw new Error("unknown");
+}
+//# sourceMappingURL=need.js.map

package/x/ok/fns/need.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"need.js","sourceRoot":"","sources":["../../../s/ok/fns/need.ts"],"names":[],"mappings":"AAGA,+BAA+B;AAC/B,MAAM,UAAU,IAAI,CAAW,MAAwB;IACtD,IAAI,MAAM,CAAC,EAAE;QACZ,OAAO,MAAM,CAAC,KAAK,CAAA;IAEpB,MAAM,EAAC,KAAK,EAAC,GAAG,MAAM,CAAA;IAEtB,IAAI,KAAK,YAAY,KAAK;QACzB,MAAM,KAAK,CAAA;SAEP,IAAI,OAAO,KAAK,KAAK,QAAQ;QACjC,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,CAAA;;QAGtB,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC"}

package/x/ok/fns/ok.d.ts

@@ -0,0 +1,3 @@
+import type { Ok } from "../types/ok.js";
+/** success */
+export declare function ok<Value>(value: Value): Ok<Value>;

package/x/ok/fns/ok.js

@@ -0,0 +1,5 @@
+/** success */
+export function ok(value) {
+    return { ok: true, value };
+}
+//# sourceMappingURL=ok.js.map

package/x/ok/fns/ok.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ok.js","sourceRoot":"","sources":["../../../s/ok/fns/ok.ts"],"names":[],"mappings":"AAGA,cAAc;AACd,MAAM,UAAU,EAAE,CAAQ,KAAY;IACrC,OAAO,EAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAC,CAAA;AACzB,CAAC"}

package/x/ok/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./fns/ok.js";
+export * from "./fns/err.js";
+export * from "./fns/grab.js";
+export * from "./fns/need.js";
+export * from "./types/ok.js";
+export * from "./types/err.js";
+export * from "./types/result.js";

package/x/ok/index.js

@@ -0,0 +1,8 @@
+export * from "./fns/ok.js";
+export * from "./fns/err.js";
+export * from "./fns/grab.js";
+export * from "./fns/need.js";
+export * from "./types/ok.js";
+export * from "./types/err.js";
+export * from "./types/result.js";
+//# sourceMappingURL=index.js.map

package/x/ok/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../s/ok/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAE7B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA"}

package/x/ok/test.d.ts

@@ -0,0 +1,12 @@
+declare const _default: {
+    ok: import("@e280/science").Test;
+    err: import("@e280/science").Test;
+    grab: import("@e280/science").Test;
+    need: import("@e280/science").Test;
+    "need error handling": {
+        "rethrows errors": import("@e280/science").Test;
+        "upgrades strings to errors": import("@e280/science").Test;
+        "everything else is unknown": import("@e280/science").Test;
+    };
+};
+export default _default;

package/x/ok/test.js

@@ -0,0 +1,39 @@
+import { expect, suite, test } from "@e280/science";
+import { thrown } from "../thrown.js";
+import { ok, err, grab, need } from "./index.js";
+export default suite({
+    "ok": test(async () => {
+        expect(ok(123).ok).is(true);
+        expect(ok(123).value).is(123);
+        expect("error" in ok(123)).is(false);
+    }),
+    "err": test(async () => {
+        expect(err("nope").ok).is(false);
+        expect(err("nope").error).is("nope");
+        expect("value" in err("nope")).is(false);
+    }),
+    "grab": test(async () => {
+        expect(grab(ok(123))).is(123);
+        expect(grab(err("nope"))).is(undefined);
+    }),
+    "need": test(async () => {
+        expect(need(ok(123))).is(123);
+        expect(() => need(err("nope"))).throws();
+    }),
+    "need error handling": {
+        "rethrows errors": test(async () => {
+            const error = new TypeError();
+            expect(() => need(err(error))).throws(TypeError);
+            expect(thrown(() => need(err(error)))).is(error);
+        }),
+        "upgrades strings to errors": test(async () => {
+            expect(() => need(err("nope"))).throws(Error);
+            expect(thrown(() => need(err("nope"))).message).is("nope");
+        }),
+        "everything else is unknown": test(async () => {
+            expect(() => need(err({ code: 234 }))).throws(Error);
+            expect(thrown(() => need(err({ code: 234 }))).message).is("unknown");
+        }),
+    },
+});
+//# sourceMappingURL=test.js.map

package/x/ok/test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.js","sourceRoot":"","sources":["../../s/ok/test.ts"],"names":[],"mappings":"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"}

package/x/ok/types/err.d.ts

@@ -0,0 +1,5 @@
+/** failure */
+export type Err<E> = {
+    ok: false;
+    error: E;
+};

package/x/ok/types/err.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=err.js.map

package/x/ok/types/err.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"err.js","sourceRoot":"","sources":["../../../s/ok/types/err.ts"],"names":[],"mappings":""}

package/x/ok/types/ok.d.ts

@@ -0,0 +1,5 @@
+/** success */
+export type Ok<Value> = {
+    ok: true;
+    value: Value;
+};

package/x/ok/types/ok.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ok.js.map

package/x/ok/types/ok.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ok.js","sourceRoot":"","sources":["../../../s/ok/types/ok.ts"],"names":[],"mappings":""}

package/x/ok/types/result.d.ts

@@ -0,0 +1,4 @@
+import type { Ok } from "./ok.js";
+import type { Err } from "./err.js";
+/** success or failure */
+export type Result<Value, E = unknown> = (Ok<Value> | Err<E>);

package/x/ok/types/result.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=result.js.map

package/x/ok/types/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../../s/ok/types/result.ts"],"names":[],"mappings":""}

package/x/tests.test.js

@@ -1,4 +1,4 @@
-import { Science } from "@e280/science";
+import { science } from "@e280/science";
 import data from "./data/data.test.js";
 import debounce from "./debounce/debounce.test.js";
 import microbounce from "./debounce/microbounce.test.js";
@@ -6,7 +6,9 @@ import deep from "./deep/index.test.js";
 import queue from "./queue/queue.test.js";
 import toq from "./toq/toq.test.js";
 import maybe from "./maybe/test.js";
-await Science.run({
+import dig from "./dig/test.js";
+import ok from "./ok/test.js";
+await science.run({
     data,
     debounce,
     microbounce,
@@ -14,5 +16,7 @@ await Science.run({
     queue,
     toq,
     maybe,
+    dig,
+    ok,
 });
 //# sourceMappingURL=tests.test.js.map

package/x/tests.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"tests.test.js","sourceRoot":"","sources":["../s/tests.test.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,OAAO,EAAC,MAAM,eAAe,CAAA;AAErC,OAAO,IAAI,MAAM,qBAAqB,CAAA;AACtC,OAAO,QAAQ,MAAM,6BAA6B,CAAA;AAClD,OAAO,WAAW,MAAM,gCAAgC,CAAA;AACxD,OAAO,IAAI,MAAM,sBAAsB,CAAA;AACvC,OAAO,KAAK,MAAM,uBAAuB,CAAA;AACzC,OAAO,GAAG,MAAM,mBAAmB,CAAA;AACnC,OAAO,KAAK,MAAM,iBAAiB,CAAA;AAEnC,MAAM,OAAO,CAAC,GAAG,CAAC;IACjB,IAAI;IACJ,QAAQ;IACR,WAAW;IACX,IAAI;IACJ,KAAK;IACL,GAAG;IACH,KAAK;CACL,CAAC,CAAA"}
+{"version":3,"file":"tests.test.js","sourceRoot":"","sources":["../s/tests.test.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,OAAO,EAAC,MAAM,eAAe,CAAA;AAErC,OAAO,IAAI,MAAM,qBAAqB,CAAA;AACtC,OAAO,QAAQ,MAAM,6BAA6B,CAAA;AAClD,OAAO,WAAW,MAAM,gCAAgC,CAAA;AACxD,OAAO,IAAI,MAAM,sBAAsB,CAAA;AACvC,OAAO,KAAK,MAAM,uBAAuB,CAAA;AACzC,OAAO,GAAG,MAAM,mBAAmB,CAAA;AACnC,OAAO,KAAK,MAAM,iBAAiB,CAAA;AACnC,OAAO,GAAG,MAAM,eAAe,CAAA;AAC/B,OAAO,EAAE,MAAM,cAAc,CAAA;AAE7B,MAAM,OAAO,CAAC,GAAG,CAAC;IACjB,IAAI;IACJ,QAAQ;IACR,WAAW;IACX,IAAI;IACJ,KAAK;IACL,GAAG;IACH,KAAK;IACL,GAAG;IACH,EAAE;CACF,CAAC,CAAA"}

package/x/thrown.d.ts

@@ -0,0 +1 @@
+export declare function thrown(fn: () => unknown): any;

package/x/thrown.js

@@ -0,0 +1,10 @@
+export function thrown(fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        return error;
+    }
+    throw new Error("didn't throw");
+}
+//# sourceMappingURL=thrown.js.map

package/x/thrown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thrown.js","sourceRoot":"","sources":["../s/thrown.ts"],"names":[],"mappings":"AACA,MAAM,UAAU,MAAM,CAAC,EAAiB;IACvC,IAAI,CAAC;QAAC,EAAE,EAAE,CAAA;IAAC,CAAC;IACZ,OAAO,KAAK,EAAE,CAAC;QAAC,OAAO,KAAK,CAAA;IAAC,CAAC;IAC9B,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,CAAA;AAChC,CAAC"}