@terrygonguet/utils 0.0.1 → 0.0.2

package/package.json

@@ -1,20 +1,35 @@
 {
 	"name": "@terrygonguet/utils",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"type": "module",
 	"scripts": {
 		"dev": "vite",
 		"build": "tsc && vite build",
-		"preview": "vite preview"
+		"test": "vitest test --ui --watch --update",
+		"coverage": "vitest run --coverage"
 	},
 	"devDependencies": {
+		"@vitest/ui": "^0.32.0",
+		"prettier": "^2.8.8",
 		"typescript": "^5.0.2",
-		"vite": "^4.3.9"
+		"vite": "^4.3.9",
+		"vitest": "^0.32.0"
 	},
 	"exports": {
 		".": {
-			"types": "./dist/main.js",
-			"import": "./types/main.d.ts"
+			"types": "./types/main.js",
+			"import": "./dist/main.d.ts"
+		},
+		"./async": {
+			"types": "./types/async.js",
+			"import": "./dist/async.d.ts"
+		},
+		"./functional": {
+			"types": "./types/functional/index.d.ts",
+			"import": "./dist/functional.js"
 		}
+	},
+	"dependencies": {
+		"just-compose": "^2.3.0"
 	}
 }

package/src/async.test.js

@@ -0,0 +1,9 @@
+import { describe } from "vitest"
+import { wait } from "./async.ts"
+
+describe("wait", it => {
+	it("Waits", async ({ expect }) => {
+		// TODO: figure out how to test that
+		await expect(wait(25)).resolves
+	})
+})

package/src/async.ts

@@ -0,0 +1,3 @@
+export function wait(ms: number): Promise<void> {
+	return new Promise(resolve => setTimeout(resolve, ms))
+}

package/src/functional/index.test.js

@@ -0,0 +1,11 @@
+import { describe } from "vitest"
+import { identity } from "./index.ts"
+
+describe.concurrent("identity()", it => {
+	it("does nothing", ({ expect }) => {
+		expect(identity(5)).to.equal(5)
+		expect(identity("test")).to.equal("test")
+		const object = { prop: "value" }
+		expect(identity(object)).to.equal(object)
+	})
+})

package/src/functional/index.ts

@@ -0,0 +1,7 @@
+export * from "./maybe.ts"
+export * from "./result.ts"
+export { default as compose } from "just-compose"
+
+export function identity<T>(value: T) {
+	return value
+}

package/src/functional/maybe.test.js

@@ -0,0 +1,85 @@
+import { describe } from "vitest"
+import { Some, None, Maybe } from "./maybe.ts"
+
+describe.concurrent("Maybe", it => {
+	/** @type {Maybe<number>} */
+	const some = Some(5)
+	/** @type {Maybe<number>} */
+	const none = None
+
+	it("isSome()", ({ expect }) => {
+		expect(some.isSome()).to.be.true
+		expect(none.isSome()).to.be.false
+	})
+
+	it("isNone()", ({ expect }) => {
+		expect(some.isNone()).to.be.false
+		expect(none.isNone()).to.be.true
+	})
+
+	it("orDefault()", ({ expect }) => {
+		expect(some.orDefault(15)).to.equal(5)
+		expect(none.orDefault(15)).to.equal(15)
+	})
+
+	it("map()", ({ expect }) => {
+		const mappedSome = some.map(n => n * 2)
+		expect(mappedSome.isSome()).to.be.true
+		expect(mappedSome.value).to.equal(10)
+		const mappedNone = none.map(n => n * 2)
+		expect(mappedNone.isNone()).to.be.true
+	})
+
+	it("flatMap()", ({ expect }) => {
+		const some1 = some.flatMap(n => Some(n * 2))
+		expect(some1.isSome()).to.be.true
+		expect(some1.value).to.equal(10)
+		const none1 = some.flatMap(n => None)
+		expect(none1.isNone()).to.be.true
+		const some2 = none.flatMap(n => Some(n * 2))
+		expect(some2.isSome()).to.be.false
+		const none2 = some.flatMap(n => None)
+		expect(none2.isNone()).to.be.true
+	})
+
+	it("toJSON()", ({ expect }) => {
+		expect(some.toJSON()).toMatchInlineSnapshot()
+		expect(none.toJSON()).toMatchInlineSnapshot()
+	})
+
+	describe.concurrent("Maybe.JSONReviver()", it => {
+		const $_kind = "@terrygonguet/utils/functional/maybe"
+		const $_variant_Some = "@terrygonguet/utils/functional/maybe/Some"
+		const $_variant_None = "@terrygonguet/utils/functional/maybe/None"
+
+		it("does nothing to normal objects", ({ expect }) => {
+			const json1 = `{"prop":"value"}`
+			const obj1 = JSON.parse(json1, Maybe.JSONReviver)
+			expect(obj1).to.deep.equal({ prop: "value" })
+		})
+
+		it("revives a Some", ({ expect }) => {
+			const json2 = `{"prop":"value","some":{"$_kind":"${$_kind}","$_variant":"${$_variant_Some}","value":5}}`
+			const obj2 = JSON.parse(json2, Maybe.JSONReviver)
+			expect(obj2.prop).to.equal("value")
+			expect(obj2.some.isSome()).to.be.true
+			expect(obj2.some.value).to.equal(5)
+		})
+
+		it("revives a None", ({ expect }) => {
+			const json3 = `{"prop":"value","none":{"$_kind":"${$_kind}","$_variant":"${$_variant_None}"}}`
+			const obj3 = JSON.parse(json3, Maybe.JSONReviver)
+			expect(obj3.prop).to.equal("value")
+			expect(obj3.none).to.equal(None)
+		})
+
+		it("does a round trip", ({ expect }) => {
+			const json4 = JSON.stringify({ prop: "value", some: Some(5), none: None })
+			const obj4 = JSON.parse(json4, Maybe.JSONReviver)
+			expect(obj4.prop).to.equal("value")
+			expect(obj4.some.isSome()).to.be.true
+			expect(obj4.some.value).to.equal(5)
+			expect(obj4.none).to.equal(None)
+		})
+	})
+})

package/src/functional/maybe.ts

@@ -0,0 +1,75 @@
+import { identity } from "./index.ts"
+
+interface API<T> {
+	isSome(this: Maybe<T>): this is Some<T>
+	isNone(this: Maybe<T>): this is None
+	orDefault(this: Maybe<T>, defaultValue: T): T
+	map<U>(this: Maybe<T>, f: (value: T) => U): Maybe<U>
+	flatMap<U>(this: Maybe<T>, f: (value: T) => Maybe<U>): Maybe<U>
+	toJSON(this: Maybe<T>): Object
+}
+
+export type Some<T> = { value: T } & API<T>
+export type None = {} & API<never>
+export type Maybe<T> = Some<T> | None
+
+const $_kind = "@terrygonguet/utils/functional/maybe"
+const $_variant_Some = "@terrygonguet/utils/functional/maybe/Some"
+const $_variant_None = "@terrygonguet/utils/functional/maybe/None"
+
+export function Some<T>(value: NonNullable<T>): Some<T> {
+	const SomePrototype: API<T> = {
+		isSome: () => true,
+		isNone: () => false,
+		orDefault(this: Some<T>) {
+			return this.value
+		},
+		map(this: Some<T>, f) {
+			return Some(f(this.value)!)
+		},
+		flatMap(this: Some<T>, f) {
+			return f(this.value)
+		},
+		toJSON(this: Some<T>) {
+			return { $_kind, $_variant: $_variant_Some, value: this.value }
+		},
+	}
+	return Object.create(SomePrototype, {
+		$_kind: { value: $_kind, enumerable: false, writable: false },
+		$_variant: { value: $_variant_Some, enumerable: false, writable: false },
+		value: { value, writable: false },
+	})
+}
+
+const NonePrototype: API<never> = {
+	isSome: () => false,
+	isNone: () => true,
+	orDefault: identity,
+	map: () => None,
+	flatMap: () => None,
+	toJSON: () => ({ $_kind, $_variant: $_variant_None }),
+}
+export const None: None = Object.create(NonePrototype, {
+	$_kind: { value: $_kind, enumerable: false, writable: false },
+	$_variant: { value: $_variant_None, enumerable: false, writable: false },
+})
+
+export const Maybe = {
+	from<T>(value: T | undefined | null): Maybe<T> {
+		switch (value) {
+			case null:
+			case undefined:
+				return None
+			default:
+				return Some(value!)
+		}
+	},
+	JSONReviver(_key: string, value: any) {
+		if (value?.$_kind == $_kind) {
+			const $_variant = value?.$_variant
+			if ($_variant == $_variant_Some) return Some<unknown>(value?.value)
+			else if ($_variant == $_variant_None) return None
+			else return value
+		} else return value
+	},
+}

package/src/functional/result.test.js

@@ -0,0 +1,150 @@
+import { describe } from "vitest"
+import { Success, Failure, Result } from "./result.ts"
+
+describe.concurrent("Result", it => {
+	/** @type {Result<number, string>} */
+	const success = Success(5)
+	/** @type {Result<number, string>} */
+	const failure = Failure("reason")
+
+	it("isSuccess()", ({ expect }) => {
+		expect(success.isSuccess()).to.be.true
+		expect(failure.isSuccess()).to.be.false
+	})
+
+	it("isFailure()", ({ expect }) => {
+		expect(success.isFailure()).to.be.false
+		expect(failure.isFailure()).to.be.true
+	})
+
+	it("map()", ({ expect }) => {
+		const mappedSuccess = success.map(n => n * 2)
+		expect(mappedSuccess.isSuccess()).to.be.true
+		expect(mappedSuccess.value).to.equal(10)
+		const mappedFailure = failure.map(n => n * 2)
+		expect(mappedFailure.isSuccess()).to.be.false
+	})
+
+	it("flatMap()", ({ expect }) => {
+		const succ1 = success.flatMap(n => Success(n * 2))
+		expect(succ1.isSuccess()).to.be.true
+		expect(succ1.value).to.equal(10)
+
+		const fail1 = success.flatMap(n => Failure("fail"))
+		expect(fail1.isSuccess()).to.be.false
+		expect(fail1.reason).to.equal("fail")
+
+		const fail2 = failure.flatMap(n => Success(n * 2))
+		expect(fail2.isSuccess()).to.be.false
+		expect(fail2.reason).to.equal("reason")
+
+		const fail3 = failure.flatMap(n => Failure("fail"))
+		expect(fail3.isSuccess()).to.be.false
+		expect(fail3.reason).to.equal("reason")
+	})
+
+	it("toJSON()", ({ expect }) => {
+		expect(success.toJSON()).toMatchInlineSnapshot(`
+			{
+			  "$_kind": "@terrygonguet/utils/functional/result",
+			  "$_variant": "@terrygonguet/utils/functional/result/Success",
+			  "value": 5,
+			}
+		`)
+		expect(failure.toJSON()).toMatchInlineSnapshot(`
+			{
+			  "$_kind": "@terrygonguet/utils/functional/result",
+			  "$_variant": "@terrygonguet/utils/functional/result/Failure",
+			  "reason": "reason",
+			}
+		`)
+	})
+
+	describe.concurrent("Result.JSONReviver()", it => {
+		const $_kind = "@terrygonguet/utils/functional/result"
+		const $_variant_Success = "@terrygonguet/utils/functional/result/Success"
+		const $_variant_Failure = "@terrygonguet/utils/functional/result/Failure"
+
+		it("does nothing to normal objects", ({ expect }) => {
+			const json = `{"prop":"value"}`
+			const obj = JSON.parse(json, Result.JSONReviver)
+			expect(obj.prop).to.equal("value")
+		})
+
+		it("revives a Success", ({ expect }) => {
+			const json = `{
+				"prop":"value",
+				"success": {
+					"$_kind": "@terrygonguet/utils/functional/result",
+					"$_variant": "@terrygonguet/utils/functional/result/Success",
+					"value": 5
+				}
+			}`
+			const obj = JSON.parse(json, Result.JSONReviver)
+			expect(obj.prop).to.equal("value")
+			expect(obj.success.isSuccess()).to.be.true
+			expect(obj.success.value).to.equal(5)
+		})
+
+		it("revives a Failure", ({ expect }) => {
+			const json = `{
+				"prop":"value",
+				"failure": {
+					"$_kind": "@terrygonguet/utils/functional/result",
+					"$_variant": "@terrygonguet/utils/functional/result/Failure",
+					"reason": "reason"
+				}
+			}`
+			const obj = JSON.parse(json, Result.JSONReviver)
+			expect(obj.prop).to.equal("value")
+			expect(obj.failure.isSuccess()).to.be.false
+			expect(obj.failure.reason).to.equal("reason")
+		})
+
+		it("does a round trip", ({ expect }) => {
+			const json = JSON.stringify({ prop: "value", success, failure })
+			const obj = JSON.parse(json, Result.JSONReviver)
+			expect(obj.prop).to.equal("value")
+			expect(obj.success.isSuccess()).to.be.true
+			expect(obj.success.value).to.equal(5)
+			expect(obj.failure.isSuccess()).to.be.false
+			expect(obj.failure.reason).to.equal("reason")
+		})
+	})
+
+	describe("Result.try()", it => {
+		it("gets the value from the try function", ({ expect }) => {
+			const result = Result.try(() => {
+				const n = 5
+				return n * 2
+			}).exec()
+			expect(result.isSuccess()).to.be.true
+			expect(result.value).to.equal(10)
+		})
+
+		it("gets the value from catch on error", ({ expect }) => {
+			const result = Result.try(() => {
+				throw new Error("fail")
+			})
+				.catch(err => {
+					return err.message
+				})
+				.exec()
+			expect(result.isSuccess()).to.be.false
+			expect(result.reason).to.equal("fail")
+		})
+
+		it("ignores catch if try does not throw", ({ expect }) => {
+			const result = Result.try(() => {
+				const n = 5
+				return n * 2
+			})
+				.catch(err => {
+					throw new Error("Should not run")
+				})
+				.exec()
+			expect(result.isSuccess()).to.be.true
+			expect(result.value).to.equal(10)
+		})
+	})
+})

package/src/functional/result.ts

@@ -0,0 +1,96 @@
+import { identity } from "./index.ts"
+
+interface API<S, F> {
+	isSuccess(this: Result<S, F>): this is Success<S, F>
+	isFailure(this: Result<S, F>): this is Failure<S, F>
+	map<S2>(this: Result<S, F>, f: (value: S) => S2): Result<S2, F>
+	flatMap<S2, F2>(this: Result<S, F>, f: (value: S) => Result<S2, F | F2>): Result<S2, F | F2>
+	toJSON(this: Result<S, F>): Object
+}
+
+export type Success<S, F> = { value: S } & API<S, F>
+export type Failure<S, F> = { reason: F } & API<S, F>
+export type Result<S, F> = Success<S, F> | Failure<S, F>
+
+const $_kind = "@terrygonguet/utils/functional/result"
+const $_variant_Success = "@terrygonguet/utils/functional/result/Success"
+const $_variant_Failure = "@terrygonguet/utils/functional/result/Failure"
+
+export function Success<S, F>(value: S): Success<S, F> {
+	const SuccessPrototype: API<S, F> = {
+		isSuccess: () => true,
+		isFailure: () => false,
+		map<S2>(this: Success<S, F>, f: (value: S) => S2) {
+			return Success(f(this.value))
+		},
+		flatMap<S2, F2>(this: Success<S, F>, f: (value: S) => Result<S2, F2>) {
+			return f(this.value)
+		},
+		toJSON(this: Success<S, F>) {
+			return { $_kind, $_variant: $_variant_Success, value: this.value }
+		},
+	}
+	return Object.create(SuccessPrototype, {
+		$_kind: { value: $_kind, enumerable: false, writable: false },
+		$_variant: { value: $_variant_Success, enumerable: false, writable: false },
+		value: { value, writable: false },
+	})
+}
+
+export function Failure<S, F>(reason: F): Failure<S, F> {
+	const FailurePrototype: API<S, F> = {
+		isSuccess: () => false,
+		isFailure: () => true,
+		map<S2>(this: Failure<S, F>) {
+			return this as unknown as Result<S2, F>
+		},
+		flatMap<S2, F2>(this: Failure<S, F>) {
+			return this as unknown as Result<S2, F | F2>
+		},
+		toJSON(this: Failure<S, F>) {
+			return { $_kind, $_variant: $_variant_Failure, reason: this.reason }
+		},
+	}
+	return Object.create(FailurePrototype, {
+		$_kind: { value: $_kind, enumerable: false, writable: false },
+		$_variant: { value: $_variant_Success, enumerable: false, writable: false },
+		reason: { value: reason, writable: false },
+	})
+}
+
+export const Result = {
+	try<S, F>(tryFn: () => S) {
+		return new TryCatch<S, F>(tryFn)
+	},
+	JSONReviver(_key: string, value: any) {
+		if (value?.$_kind == $_kind) {
+			const $_variant = value?.$_variant
+			if ($_variant == $_variant_Success) return Success<unknown, unknown>(value?.value)
+			else if ($_variant == $_variant_Failure) return Failure<unknown, unknown>(value?.reason)
+			else return value
+		} else return value
+	},
+}
+
+class TryCatch<S, F> {
+	tryFn: () => S
+	catchFn: (err: unknown) => F
+
+	constructor(tryFn: () => S) {
+		this.tryFn = tryFn
+		this.catchFn = identity as any
+	}
+
+	catch(catchFn: (err: unknown) => F) {
+		this.catchFn = catchFn
+		return this
+	}
+
+	exec(): Result<S, F> {
+		try {
+			return Success<S, F>(this.tryFn())
+		} catch (error) {
+			return Failure<S, F>(this.catchFn(error))
+		}
+	}
+}

package/src/main.test.js

@@ -0,0 +1,43 @@
+import { describe } from "vitest"
+import { clamp, safeParse } from "./main.ts"
+
+describe.concurrent("clamp()", it => {
+	it("does nothing to values within range", ({ expect }) => {
+		expect(clamp(5, 0, 10)).to.equal(5)
+		expect(clamp(10, 10, 10)).to.equal(10)
+		expect(clamp(0, 0, 10)).to.equal(0)
+		expect(clamp(10, 0, 10)).to.equal(10)
+	})
+
+	it("clamps values outside of range", ({ expect }) => {
+		expect(clamp(-5, 0, 10)).to.equal(0)
+		expect(clamp(15, 0, 10)).to.equal(10)
+		expect(clamp(-5, 10, 10)).to.equal(10)
+		expect(clamp(15, 10, 10)).to.equal(10)
+	})
+})
+
+describe.concurrent("safeParse()", it => {
+	it("works the same as JSON.parse for valid objects", ({ expect }) => {
+		const json = `{"prop":"value"}`
+		expect(safeParse(json, {})).to.deep.equal(JSON.parse(json))
+	})
+
+	it("uses default value for malformed JSON", ({ expect }) => {
+		const json = `{"prop":}`
+		expect(safeParse(json, { prop: "default" })).to.deep.equal({ prop: "default" })
+	})
+
+	it("uses revivers", ({ expect }) => {
+		const json = `{"prop":"value","other":"ignored"}`
+		function reviver(key, value) {
+			if (key == "prop") return "replaced"
+			else return value
+		}
+		const defaultValue = { prop: "value", other: "ignored" }
+		expect(safeParse(json, defaultValue, reviver)).to.deep.equal({
+			prop: "replaced",
+			other: "ignored",
+		})
+	})
+})

package/src/main.ts

@@ -1,3 +1,18 @@
+/**
+ * Behaviour is undefined when max < min
+ */
 export function clamp(value: number, min: number, max: number) {
 	return Math.min(Math.max(value, min), max)
-}
+}
+
+export function safeParse<T>(
+	str: string,
+	defaultValue: T,
+	reviver?: (key: string, value: any) => any,
+) {
+	try {
+		return JSON.parse(str, reviver)
+	} catch (_) {
+		return defaultValue
+	}
+}

package/tsconfig.json

@@ -3,12 +3,13 @@
 		"target": "ES2020",
 		"useDefineForClassFields": true,
 		"module": "ESNext",
-		"lib": ["ES2020"],
+		"lib": ["ES2020", "DOM", "DOM.Iterable"],
 		"skipLibCheck": true,
 
 		/* Bundler mode */
 		"moduleResolution": "node16",
 		"allowImportingTsExtensions": true,
+		"allowSyntheticDefaultImports": true,
 		"resolveJsonModule": true,
 		"isolatedModules": true,
 		"declaration": true,
@@ -18,8 +19,7 @@
 		/* Linting */
 		"strict": true,
 		"noUnusedLocals": true,
-		"noUnusedParameters": true,
-		"noFallthroughCasesInSwitch": true
+		"noUnusedParameters": true
 	},
 	"include": ["src"]
 }

package/types/async.d.ts

@@ -0,0 +1 @@
+export declare function wait(ms: number): Promise<void>;

package/types/functional/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./maybe.ts";
+export * from "./result.ts";
+export { default as compose } from "just-compose";
+export declare function identity<T>(value: T): T;

package/types/functional/maybe.d.ts

@@ -0,0 +1,20 @@
+interface API<T> {
+    isSome(this: Maybe<T>): this is Some<T>;
+    isNone(this: Maybe<T>): this is None;
+    orDefault(this: Maybe<T>, defaultValue: T): T;
+    map<U>(this: Maybe<T>, f: (value: T) => U): Maybe<U>;
+    flatMap<U>(this: Maybe<T>, f: (value: T) => Maybe<U>): Maybe<U>;
+    toJSON(this: Maybe<T>): Object;
+}
+export type Some<T> = {
+    value: T;
+} & API<T>;
+export type None = {} & API<never>;
+export type Maybe<T> = Some<T> | None;
+export declare function Some<T>(value: NonNullable<T>): Some<T>;
+export declare const None: None;
+export declare const Maybe: {
+    from<T>(value: T | null | undefined): Maybe<T>;
+    JSONReviver(_key: string, value: any): any;
+};
+export {};

package/types/functional/result.d.ts

@@ -0,0 +1,28 @@
+interface API<S, F> {
+    isSuccess(this: Result<S, F>): this is Success<S, F>;
+    isFailure(this: Result<S, F>): this is Failure<S, F>;
+    map<S2>(this: Result<S, F>, f: (value: S) => S2): Result<S2, F>;
+    flatMap<S2, F2>(this: Result<S, F>, f: (value: S) => Result<S2, F | F2>): Result<S2, F | F2>;
+    toJSON(this: Result<S, F>): Object;
+}
+export type Success<S, F> = {
+    value: S;
+} & API<S, F>;
+export type Failure<S, F> = {
+    reason: F;
+} & API<S, F>;
+export type Result<S, F> = Success<S, F> | Failure<S, F>;
+export declare function Success<S, F>(value: S): Success<S, F>;
+export declare function Failure<S, F>(reason: F): Failure<S, F>;
+export declare const Result: {
+    try<S, F>(tryFn: () => S): TryCatch<S, F>;
+    JSONReviver(_key: string, value: any): any;
+};
+declare class TryCatch<S, F> {
+    tryFn: () => S;
+    catchFn: (err: unknown) => F;
+    constructor(tryFn: () => S);
+    catch(catchFn: (err: unknown) => F): this;
+    exec(): Result<S, F>;
+}
+export {};

package/types/main.d.ts

@@ -1 +1,5 @@
+/**
+ * Behaviour is undefined when max < min
+ */
 export declare function clamp(value: number, min: number, max: number): number;
+export declare function safeParse<T>(str: string, defaultValue: T, reviver?: (key: string, value: any) => any): any;

package/vite.config.js

@@ -1,13 +1,15 @@
-import { resolve } from "path"
-import { defineConfig } from "vite"
-
-export default defineConfig({
-	build: {
-		lib: {
-			formats: ["es"],
-			entry: {
-				main: resolve(__dirname, "src/main.ts"),
-			},
-		},
-	},
-})
+import { resolve } from "path"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+	build: {
+		lib: {
+			formats: ["es"],
+			entry: {
+				main: resolve(__dirname, "src/main.ts"),
+				async: resolve(__dirname, "src/async.ts"),
+				functional: resolve(__dirname, "src/functional/index.ts"),
+			},
+		},
+	},
+})