@fulcro/functions 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 diguu <rodrigogeribola@hotmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @fulcro/functions
+
+Two runtime helpers that turn control flow into values. No dependencies, no
+compiler involvement, nothing to configure.
+
+```ts
+import { switchFor, tryCatch } from '@fulcro/functions';
+```
+
+## `switchFor`
+
+Choosing between branches, as an expression rather than as a statement. It comes
+in two forms, and which one to reach for depends on whether the value is drawn
+from a closed set.
+
+### Exhaustive form — enums and literal unions
+
+Pass one branch per member, and the compiler enforces that every member has one.
+
+```ts
+enum Status {
+	Draft,
+	Published,
+	Archived,
+}
+
+const label = switchFor(status, {
+	[Status.Draft]: () => 'draft',
+	[Status.Published]: () => 'published',
+	[Status.Archived]: () => 'archived',
+});
+```
+
+Leave a member out and it does not compile:
+
+```
+error TS2345: Property '[Status.Archived]' is missing in type
+'{ 0: () => string; 1: () => string; }' but required in type
+'ExhaustiveCases<Status, string>'.
+```
+
+**That error is the whole point.** When a member is added to the enum later,
+every `switchFor` over it stops compiling until the new case is handled — which
+is the moment to decide what it should do, rather than finding the gap in
+production. A native `switch` says nothing in that situation; it just falls
+through.
+
+There is deliberately **no fallback parameter** in this form. A fallback is
+precisely what would absorb the new member in silence and take the guarantee
+away.
+
+Each branch receives the single member it handles, already narrowed:
+
+```ts
+switchFor(status, {
+	[Status.Draft]: (value) => {
+		const draft: Status.Draft = value; // not Status
+		return render(draft);
+	},
+	// …
+});
+```
+
+Works with numeric enums, string enums, and unions of string or number
+literals. A member whose value is `0` is dispatched like any other — the branch
+is found by key, never by testing the value for truthiness.
+
+### Running it for its effects
+
+There is no separate void-returning function, and none is needed. Where the
+branches return nothing, `R` is inferred as `void` and the call stands on its
+own as a statement:
+
+```ts
+switchFor(status, {
+	[Status.Draft]: () => saveDraft(),
+	[Status.Published]: () => publish(),
+	[Status.Archived]: () => archive(),
+});
+```
+
+The exhaustiveness check applies there exactly as it does to a call whose result
+is read — leave a member out and this fails to compile too.
+
+### Predicate form — everything else
+
+Where branches are conditions rather than values:
+
+```ts
+const size = switchFor(
+	order,
+	[
+		{ when: (o) => o.total > 1000, then: () => 'large' },
+		{ when: (o) => o.items.length === 0, then: () => 'empty' },
+	],
+	() => 'standard',
+);
+```
+
+Branches are tested in order, the first match wins, and the rest are never
+evaluated — neither their conditions nor their bodies.
+
+`otherwise` is optional, and leaving it out shows up in the type instead of
+being hidden:
+
+```ts
+const a = switchFor(n, cases); // R | undefined
+const b = switchFor(n, cases, () => fallback); // R
+```
+
+Without a fallback, an unmatched value evaluates to `undefined` and the compiler
+makes you account for it. With one, the `undefined` is gone, because nothing can
+produce it any more.
+
+This form **cannot** be exhaustive. A condition is an arbitrary function, and
+the compiler cannot reason about which values it accepts — which is why it takes
+a fallback and the exhaustive form does not. It also decides a branch without
+narrowing the value inside `then`.
+
+## `tryCatch`
+
+The outcome of an operation as a value, instead of as control flow.
+
+```ts
+const result = await tryCatch(() => fetch(url));
+
+if (result.error !== null) return fallback;
+
+use(result.data);
+```
+
+**Prefer the callback form.** Passing a promise that already exists cannot catch
+anything the expression throws on its way to producing it — in
+`tryCatch(risky())`, `risky` runs first, and a synchronous throw inside it
+escapes before `tryCatch` is ever called. The callback form moves that call
+inside the `try`, which is the only way to cover both the synchronous and the
+asynchronous failure of one operation. The promise form is still accepted, and
+reads better when the promise is already in hand.
+
+**Discriminate on `error`, never on `data`.** `0`, `''` and `null` are perfectly
+good results, and `if (result.data)` reports every one of them as a failure.
+Checking `result.error === null` narrows the union properly:
+
+```ts
+if (result.error === null) {
+	result.data; // T, not T | null
+}
+```
+
+**`E` defaults to `unknown`, not to `Error`.** JavaScript lets any value be
+thrown, so typing the error as an `Error` would be a claim this function cannot
+keep — `result.error.message` would read `undefined` whenever something threw a
+string. Narrow it at the use site, or pass the type explicitly when you own
+every throw site:
+
+```ts
+const result = await tryCatch<User, ApiError>(() => api.load(id));
+```
+
+A thrown `null` or `undefined` — legal, however pathological — is wrapped in an
+`Error` carrying the original value as its `cause`, because storing it as it
+came would make the failure indistinguishable from a success.
+
+`tryCatch` always returns a promise, including for a fully synchronous
+operation.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public entry point of the package, matching the `main` and `types` fields of
+ * `package.json`.
+ *
+ * Listed one by one rather than re-exported wholesale, so that adding an export
+ * to a module below is never enough on its own to put it in front of consumers.
+ */
+export { type ExhaustiveCases, type SwitchCase, switchFor } from './switchFor/index.js';
+export { type Failure, type Result, type Success, tryCatch } from './tryCatch/index.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryCatch = exports.switchFor = void 0;
+/**
+ * Public entry point of the package, matching the `main` and `types` fields of
+ * `package.json`.
+ *
+ * Listed one by one rather than re-exported wholesale, so that adding an export
+ * to a module below is never enough on its own to put it in front of consumers.
+ */
+var switchFor_1 = require("./switchFor/index.js");
+Object.defineProperty(exports, "switchFor", { enumerable: true, get: function () { return switchFor_1.switchFor; } });
+var tryCatch_1 = require("./tryCatch/index.js");
+Object.defineProperty(exports, "tryCatch", { enumerable: true, get: function () { return tryCatch_1.tryCatch; } });

package/dist/switchFor/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * One branch of the predicate form of {@link switchFor}.
+ *
+ * @template T Type of the evaluated value.
+ * @template R Type produced by the branch.
+ */
+export interface SwitchCase<T, R> {
+    /**
+     * Condition deciding whether this branch handles the value.
+     *
+     * @param value Value being evaluated.
+     * @returns `true` when this branch handles it.
+     */
+    readonly when: (value: T) => boolean;
+    /**
+     * Produces the result of this branch.
+     *
+     * Only called for the branch that matched, so a branch may do work that
+     * would be wrong or expensive for a value it does not handle.
+     *
+     * @param value Value being evaluated.
+     * @returns The result of the branch.
+     */
+    readonly then: (value: T) => R;
+}
+/**
+ * A branch for every member of a closed set of values.
+ *
+ * Written as a mapped type over the union rather than as an index signature,
+ * which is what makes the exhaustiveness a compile error: a missing member is a
+ * missing required property, and an unknown one has nothing to be assigned to.
+ *
+ * Each branch receives the single member it handles, not the whole union, so
+ * the value arrives already narrowed.
+ *
+ * @template T Union of the values being matched, typically an enum.
+ * @template R Type produced by every branch.
+ */
+export type ExhaustiveCases<T extends PropertyKey, R> = {
+    readonly [K in T]: (value: K) => R;
+};
+/**
+ * Chooses between branches, as an expression.
+ *
+ * Comes in two forms, and which one to reach for depends on whether the value
+ * being matched is drawn from a closed set.
+ *
+ * **Exhaustive form** — for an enum, or any union of string or number literals.
+ * Pass one branch per member and the compiler enforces that every member has
+ * one:
+ *
+ * ```ts
+ * enum Status {
+ * 	Draft,
+ * 	Published,
+ * 	Archived,
+ * }
+ *
+ * const label = switchFor(status, {
+ * 	[Status.Draft]: () => 'draft',
+ * 	[Status.Published]: () => 'published',
+ * 	[Status.Archived]: () => 'archived',
+ * });
+ * ```
+ *
+ * Leaving a member out does not compile, and neither does adding a branch for
+ * something that is not a member. That is the point of this form: when a
+ * member is added to the enum later, every `switchFor` over it stops compiling
+ * until it is handled — which is exactly the moment to decide what it should
+ * do, rather than discovering the gap at runtime. There is deliberately no
+ * fallback parameter here, because a fallback is precisely what would absorb
+ * the new member in silence and take the guarantee away.
+ *
+ * **Predicate form** — for anything else, where branches are conditions rather
+ * than values:
+ *
+ * ```ts
+ * const size = switchFor(
+ * 	order,
+ * 	[
+ * 		{ when: (o) => o.total > 1000, then: () => 'large' },
+ * 		{ when: (o) => o.items.length === 0, then: () => 'empty' },
+ * 	],
+ * 	() => 'standard',
+ * );
+ * ```
+ *
+ * Branches are tested in order and the first match wins; the rest are never
+ * evaluated, neither their conditions nor their bodies.
+ *
+ * `otherwise` is optional, and leaving it out is reflected in the type rather
+ * than hidden: the call then evaluates to `R | undefined`, so the compiler
+ * makes the caller account for the value that matched nothing. Passing a
+ * fallback removes the `undefined`, because nothing can produce it any more.
+ *
+ * The predicate form cannot be exhaustive. A condition is an arbitrary function
+ * and the compiler cannot reason about which values it accepts, which is why
+ * only this form has a fallback at all. It also decides a branch without
+ * narrowing the value inside `then`, where the exhaustive form hands each
+ * branch the single member it handles.
+ *
+ * **Using it for its effects needs no separate function.** Where the branches
+ * return nothing, `R` is inferred as `void` and the call stands on its own as a
+ * statement:
+ *
+ * ```ts
+ * switchFor(status, {
+ * 	[Status.Draft]: () => saveDraft(),
+ * 	[Status.Published]: () => publish(),
+ * 	[Status.Archived]: () => archive(),
+ * });
+ * ```
+ *
+ * The exhaustiveness check applies there exactly as it does to a call whose
+ * result is read.
+ *
+ * @template T Type of the evaluated value.
+ * @template R Type produced by every branch.
+ * @param value Value being evaluated.
+ * @param cases One branch per member, or branches tested in order.
+ * @param otherwise Produces the result when no branch matches. Predicate form
+ * only; omitting it admits `undefined` into the result.
+ * @returns The result of the branch that handled the value, the result of
+ * `otherwise`, or `undefined` when nothing matched and no fallback was given.
+ */
+export declare function switchFor<T extends PropertyKey, R>(value: T, cases: ExhaustiveCases<T, R>): R;
+export declare function switchFor<T, R>(value: T, cases: readonly SwitchCase<T, R>[], otherwise: (value: T) => R): R;
+export declare function switchFor<T, R>(value: T, cases: readonly SwitchCase<T, R>[]): R | undefined;

package/dist/switchFor/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.switchFor = switchFor;
+function switchFor(value, cases, otherwise) {
+    if (!Array.isArray(cases)) {
+        return cases[value](value);
+    }
+    const matched = cases.find(({ when }) => when(value));
+    if (matched !== undefined)
+        return matched.then(value);
+    return otherwise === undefined ? undefined : otherwise(value);
+}

package/dist/tryCatch/index.d.ts

@@ -0,0 +1,77 @@
+/** Outcome of an operation that produced a value. */
+export interface Success<T> {
+    /** Value the operation produced. */
+    readonly data: T;
+    /** Always `null`, which is what tells a success from a failure. */
+    readonly error: null;
+}
+/**
+ * Outcome of an operation that threw.
+ *
+ * The error is non nullable by construction, so that `error === null` is enough
+ * to tell the two cases apart. {@link tryCatch} upholds that at runtime: a
+ * thrown `null` or `undefined` — legal in JavaScript, however pathological — is
+ * wrapped in an `Error` rather than stored as is, because storing it would make
+ * a failure indistinguishable from a success.
+ *
+ * @template E Type of the captured error.
+ */
+export interface Failure<E> {
+    /** Always `null`, since the operation produced no value. */
+    readonly data: null;
+    /** The captured error. */
+    readonly error: NonNullable<E>;
+}
+/**
+ * The outcome of an operation, as a value rather than as control flow.
+ *
+ * Discriminate on `error`, never on `data`:
+ *
+ * ```ts
+ * if (result.error === null) use(result.data);
+ * ```
+ *
+ * `data` is a valid discriminant only while the success type excludes every
+ * falsy value, which is a property of `T` and not of this type — `0`, `''` and
+ * `null` are all perfectly good results, and `if (result.data)` reports each of
+ * them as a failure.
+ *
+ * @template T Type produced on success.
+ * @template E Type of the error captured on failure.
+ */
+export type Result<T, E = unknown> = Success<T> | Failure<E>;
+/**
+ * Runs an operation and returns its outcome instead of throwing.
+ *
+ * ```ts
+ * const result = await tryCatch(() => fetch(url));
+ *
+ * if (result.error !== null) return fallback;
+ *
+ * use(result.data);
+ * ```
+ *
+ * **Prefer the callback form.** Passing a promise that already exists cannot
+ * catch anything the expression throws on its way to producing it: in
+ * `tryCatch(risky())`, `risky` runs first, and a synchronous throw inside it
+ * escapes before this function is ever called. The callback form moves that
+ * call inside the `try`, which is the only way to cover both the synchronous
+ * and the asynchronous failure of the same operation. The promise form is kept
+ * because it reads better when the promise is already in hand.
+ *
+ * `E` defaults to `unknown` rather than to `Error`, deliberately. JavaScript
+ * lets any value be thrown, and typing the error as an `Error` without checking
+ * would be a claim this function cannot keep — `result.error.message` would
+ * then read `undefined` whenever something threw a string. Narrow it at the use
+ * site, or pass the type explicitly when you own every throw site.
+ *
+ * Always returns a promise, including for an operation that is entirely
+ * synchronous.
+ *
+ * @template T Type produced by the operation.
+ * @template E Type of the error captured on failure.
+ * @param operation Callback performing the operation, or a promise already
+ * running it.
+ * @returns The outcome of the operation.
+ */
+export declare const tryCatch: <T, E = unknown>(operation: Promise<T> | (() => T | PromiseLike<T>)) => Promise<Result<Awaited<T>, E>>;

package/dist/tryCatch/index.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryCatch = void 0;
+/**
+ * Something a thrown value can be stored as without defeating the discriminant.
+ *
+ * @param error Value that was thrown.
+ * @returns The value itself, or an `Error` standing in for a nullish throw.
+ */
+const asStorableError = (error) => {
+    if (error !== null && error !== undefined)
+        return error;
+    return new Error(`Operation rejected with ${String(error)}`, {
+        cause: error,
+    });
+};
+/**
+ * Runs an operation and returns its outcome instead of throwing.
+ *
+ * ```ts
+ * const result = await tryCatch(() => fetch(url));
+ *
+ * if (result.error !== null) return fallback;
+ *
+ * use(result.data);
+ * ```
+ *
+ * **Prefer the callback form.** Passing a promise that already exists cannot
+ * catch anything the expression throws on its way to producing it: in
+ * `tryCatch(risky())`, `risky` runs first, and a synchronous throw inside it
+ * escapes before this function is ever called. The callback form moves that
+ * call inside the `try`, which is the only way to cover both the synchronous
+ * and the asynchronous failure of the same operation. The promise form is kept
+ * because it reads better when the promise is already in hand.
+ *
+ * `E` defaults to `unknown` rather than to `Error`, deliberately. JavaScript
+ * lets any value be thrown, and typing the error as an `Error` without checking
+ * would be a claim this function cannot keep — `result.error.message` would
+ * then read `undefined` whenever something threw a string. Narrow it at the use
+ * site, or pass the type explicitly when you own every throw site.
+ *
+ * Always returns a promise, including for an operation that is entirely
+ * synchronous.
+ *
+ * @template T Type produced by the operation.
+ * @template E Type of the error captured on failure.
+ * @param operation Callback performing the operation, or a promise already
+ * running it.
+ * @returns The outcome of the operation.
+ */
+const tryCatch = async (operation) => {
+    try {
+        const data = await (typeof operation === 'function'
+            ? operation()
+            : operation);
+        return { data, error: null };
+    }
+    catch (error) {
+        return { data: null, error: asStorableError(error) };
+    }
+};
+exports.tryCatch = tryCatch;

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@fulcro/functions",
+	"version": "0.1.0",
+	"description": "Runtime helpers turning control flow into values: an exhaustive switchFor and a throwing-free tryCatch.",
+	"keywords": [
+		"switch",
+		"exhaustive",
+		"enum",
+		"result",
+		"try-catch",
+		"typescript"
+	],
+	"license": "ISC",
+	"author": "diguu <rodrigogeribola@hotmail.com>",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": false,
+	"engines": {
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DigUu-RL/fulcro.git",
+		"directory": "packages/functions"
+	},
+	"homepage": "https://github.com/DigUu-RL/fulcro/tree/main/packages/functions#readme",
+	"bugs": {
+		"url": "https://github.com/DigUu-RL/fulcro/issues"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"prepublishOnly": "npm run build"
+	}
+}