@fnndsc/fond 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FNNDSC / BCH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @fnndsc/fond
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The neutral base of the mise stack: the small, generic pieces that the engine (`@fnndsc/brasa`), the session host (`@fnndsc/calypso`) and the ChRIS packages all stand on, and that have nothing to do with ChRIS.
+
+The name is from the kitchen, like the rest of the stack: *fonds de cuisine* are the base stocks a kitchen cooks everything else from.
+
+```
+npm install @fnndsc/fond
+```
+
+## Why it exists
+
+mise is being made backend-neutral: one engine, one session host, one wire and one surface frame, with ChRIS (CUBE) as the first backend among possibly several (see [docs/backend-neutral.adoc](https://github.com/FNNDSC/mise/blob/main/docs/backend-neutral.adoc)). For that to be true, the generic pieces cannot live inside a ChRIS package. Before fond, `Result` and the error stack lived in `@fnndsc/cumin`, whose root also loads CUBE's API client, so any layer that wanted an `Ok()` loaded CUBE with it.
+
+fond is where those pieces go instead. Its one rule: **it depends on nothing in `@fnndsc`**. CI holds it to that (`npm run lint:fond`), so a layer that is not about CUBE can use fond without loading CUBE.
+
+## What's in it
+
+| Export | What it is |
+| --- | --- |
+| `Result<T>`, `Ok`, `Err`, `result_isOk`, `result_isErr` | An explicit success-or-failure value. A function returns `Result<T>` rather than `T \| null`, and TypeScript will not let a caller read `.value` until it has checked `.ok`. |
+| `errorStack` | The process-wide message stack that failures are reported on, with context-isolated scopes and checkpoints. |
+| `errorStack_configure`, `errorStack_getAllOfType`, `StackMessage` | Configuration, a convenience reader, and the message type. |
+
+The steps after this one add the VFS framework (mount interface and dispatcher) and the output sink and surface interfaces the engine and the session host share.
+
+## Using `Result`
+
+A failure carries no payload of its own: the reason goes on the error stack, where a surface can show it, and the `Result` says only that it failed.
+
+```typescript
+import { Ok, Err, errorStack, type Result } from '@fnndsc/fond';
+
+async function config_read(path: string): Promise<Result<Config>> {
+  const text: string | null = await file_read(path);
+  if (text === null) {
+    errorStack.stack_push('error', `No configuration at ${path}.`);
+    return Err();
+  }
+  return Ok(config_parse(text));
+}
+
+const config: Result<Config> = await config_read('~/.config/app.yml');
+if (!config.ok) {
+  // config.value does not exist here; TypeScript says so.
+  return;
+}
+config_apply(config.value);
+```
+
+## Using the error stack
+
+`errorStack` is a single instance for the whole process. Each message is stamped with the name of the function that pushed it:
+
+```typescript
+errorStack.stack_push('error', 'CUBE refused the login');
+errorStack.stack_pop();
+// { type: 'error', message: '[login_run                               ] | CUBE refused the login' }
+```
+
+Reading and clearing:
+
+| Method | Does |
+| --- | --- |
+| `stack_push(type, message)` | Pushes an `error` or a `warning`. |
+| `stack_pop()`, `stack_getAll()` | Takes the newest message; lists them all. |
+| `stack_search(text)`, `messagesOfType_search(type, text)` | Finds messages containing some text. |
+| `allOfType_get(type)`, `messages_has()`, `messagesOfType_has(type)` | Reads by type; asks whether anything is there. |
+| `stack_clear()`, `type_clear(type)` | Empties the stack, or one type. |
+
+Two features keep concurrent work from mixing up its errors:
+
+* **Scopes.** Work run inside `errorStack.scope_run(fn)` pushes to and pops from its own isolated stack, carried by Node's `AsyncLocalStorage` through every `await` inside it. Background work (cache warming, refreshes) runs in a scope so its failures never land in a foreground command's report.
+* **Checkpoints.** A command calls `checkpoint_mark()` before it works and `checkpoint_drain(mark)` after, and gets exactly the messages pushed in between.
+
+```typescript
+const mark: number = errorStack.checkpoint_mark();
+const answer: Result<Listing> = await listing_fetch(path);
+const reasons: StackMessage[] = errorStack.checkpoint_drain(mark);
+```
+
+`errorStack_configure({ functionNamePadWidth })` sets how wide the function-name stamp is padded.
+
+## One instance, whoever loads it
+
+The error stack only works if the whole process shares one. fond is built as CommonJS, so packages that `require` it (cumin) and packages that `import` it (salsa, brasa, calypso) load the same module and so the same stack. `@fnndsc/cumin` re-exports fond's `Result` and `errorStack` rather than keeping copies, so code that still imports them from cumin shares that stack too. If you bundle code that uses fond, keep it to one copy.
+
+## Where it sits
+
+```
+  brasa (engine)    calypso (session host)    cumin, salsa (the ChRIS backend)
+        │                     │                          │
+        └─────────────────────┼──────────────────────────┘
+                              ▼
+                      ┌───────────────┐
+                      │     fond      │   depends on nothing in @fnndsc
+                      └───────────────┘
+```
+
+## License
+
+MIT. Part of [mise](https://github.com/FNNDSC/mise).

package/dist/errorStack.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @file Process-wide error/message stack for deferred, structured reporting.
+ *
+ * The stack is a process singleton, but it is *async-context aware*: work run
+ * inside {@link ErrorStack.scope_run} pushes to and pops from its own isolated
+ * stack rather than the shared one. This lets fire-and-forget background work
+ * (cache warming, background refreshes) keep its error traffic off the shared
+ * stack, so a foreground command that checkpoints the stack and drains it
+ * afterward (see {@link ErrorStack.checkpoint_mark} /
+ * {@link ErrorStack.checkpoint_drain}) captures only its own messages and is
+ * never corrupted by a background push landing in its drain window.
+ *
+ * @module
+ */
+type MessageType = "error" | "warning";
+/**
+ * Represents a single message in the error stack.
+ */
+export interface StackMessage {
+    type: MessageType;
+    message: string;
+}
+/**
+ * Options for configuring the ErrorStack.
+ */
+interface ErrorStackOptions {
+    functionNamePadWidth?: number;
+}
+/**
+ * Singleton class for managing a stack of error and warning messages.
+ * Provides methods to push, pop, search, and filter messages.
+ */
+declare class ErrorStack {
+    private static instance;
+    private stack;
+    private functionNamePadWidth;
+    /**
+     * Holds the isolated stack for work running inside {@link scope_run}. When
+     * a store is present, all operations target it instead of the shared stack.
+     */
+    private scopeStorage;
+    private constructor();
+    /**
+     * Returns the stack the current async context should operate on: the
+     * isolated stack when inside a {@link scope_run}, otherwise the shared one.
+     *
+     * @returns The active stack array.
+     */
+    private stack_active;
+    /**
+     * Runs a function with an isolated error stack that the shared stack — and
+     * any foreground command draining it — never sees. Fire-and-forget
+     * background work wraps its body in this so its error traffic cannot land
+     * in a concurrent foreground command's drain window. The isolation follows
+     * the whole async causal chain started inside `fn`.
+     *
+     * @param fn - The work to run against a fresh, isolated stack.
+     * @returns Whatever `fn` returns.
+     */
+    scope_run<T>(fn: () => T): T;
+    /**
+     * Marks the current depth of the active stack, for a later
+     * {@link checkpoint_drain}.
+     *
+     * @returns An opaque checkpoint (the current stack depth).
+     */
+    checkpoint_mark(): number;
+    /**
+     * Removes and returns every message pushed above a checkpoint, so a command
+     * boundary can drain exactly the messages produced since it marked the
+     * stack. Messages the command's own code already popped are simply absent.
+     *
+     * @param checkpoint - A checkpoint from {@link checkpoint_mark}.
+     * @returns The drained messages, oldest first.
+     */
+    checkpoint_drain(checkpoint: number): StackMessage[];
+    /**
+     * Get the singleton instance of the ErrorStack.
+     *
+     * @param options - Optional configuration options for the stack.
+     * @returns The singleton ErrorStack instance.
+     */
+    static instance_get(options?: ErrorStackOptions): ErrorStack;
+    /**
+     * Push a new message onto the stack.
+     *
+     * Captures the calling function name and formats the message.
+     *
+     * @param type - The type of message ("error" or "warning").
+     * @param message - The message string.
+     */
+    stack_push(type: MessageType, message: string): void;
+    /**
+     * Pop the last message from the stack.
+     *
+     * @returns The last message object or undefined if the stack is empty.
+     */
+    stack_pop(): StackMessage | undefined;
+    /**
+     * Search the stack for messages containing a substring.
+     *
+     * @param substring - The string to search for (case-insensitive).
+     * @returns An array of formatted strings matching the search.
+     */
+    stack_getAll(): StackMessage[];
+    stack_search(substring: string): string[];
+    /**
+     * Get all messages of a specific type.
+     *
+     * @param type - The message type to filter by.
+     * @returns An array of message strings.
+     */
+    allOfType_get(type: MessageType): string[];
+    /**
+     * Search for messages of a specific type containing a substring.
+     *
+     * @param type - The message type to filter by.
+     * @param substring - The string to search for (case-insensitive).
+     * @returns An array of matching message strings.
+     */
+    messagesOfType_search(type: MessageType, substring: string): string[];
+    /**
+     * Clear all messages from the stack.
+     */
+    stack_clear(): void;
+    /**
+     * Clear all messages of a specific type from the stack.
+     *
+     * @param type - The message type to clear.
+     */
+    type_clear(type: MessageType): void;
+    /**
+     * Check if the stack contains any messages.
+     *
+     * @returns True if the stack is not empty, false otherwise.
+     */
+    messages_has(): boolean;
+    /**
+     * Check if the stack contains any messages of a specific type.
+     *
+     * @param type - The message type to check for.
+     * @returns True if messages of the given type exist, false otherwise.
+     */
+    messagesOfType_has(type: MessageType): boolean;
+}
+/**
+ * The global singleton instance of the ErrorStack.
+ */
+export declare const errorStack: ErrorStack;
+/**
+ * Reconfigures the error stack with new options.
+ *
+ * @param options - The new configuration options.
+ */
+export declare function errorStack_configure(options: ErrorStackOptions): void;
+/**
+ * Get all messages of a specific type from the global error stack.
+ *
+ * @param type - The message type to filter by.
+ * @returns An array of message strings.
+ */
+export declare function errorStack_getAllOfType(type: MessageType): string[];
+export {};

package/dist/errorStack.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * @file Process-wide error/message stack for deferred, structured reporting.
+ *
+ * The stack is a process singleton, but it is *async-context aware*: work run
+ * inside {@link ErrorStack.scope_run} pushes to and pops from its own isolated
+ * stack rather than the shared one. This lets fire-and-forget background work
+ * (cache warming, background refreshes) keep its error traffic off the shared
+ * stack, so a foreground command that checkpoints the stack and drains it
+ * afterward (see {@link ErrorStack.checkpoint_mark} /
+ * {@link ErrorStack.checkpoint_drain}) captures only its own messages and is
+ * never corrupted by a background push landing in its drain window.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorStack = void 0;
+exports.errorStack_configure = errorStack_configure;
+exports.errorStack_getAllOfType = errorStack_getAllOfType;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * Pads a string to the right with spaces to a specified length.
+ * If the string is longer than the length, it is truncated with ellipses.
+ *
+ * @param str - The string to pad.
+ * @param length - The target length.
+ * @returns The padded or truncated string.
+ */
+function str_padRight(str, length) {
+    if (str.length > length) {
+        return str.substring(0, length - 3) + "...";
+    }
+    return str.padEnd(length);
+}
+/**
+ * Retrieves the name of the function that called the current function.
+ * Uses the error stack trace to parse the caller's name.
+ *
+ * @returns The name of the calling function, or a default string if not found.
+ */
+function functionName_getCurrent() {
+    const error = new Error();
+    const stack = error.stack?.split("\n");
+    if (!stack || stack.length < 4) {
+        return "Unknown Function";
+    }
+    const callerLine = stack[3];
+    const functionNameMatch = callerLine.match(/at\s+([\w\.<>]+)\s*\(/);
+    return functionNameMatch ? functionNameMatch[1] : "Anonymous Function";
+}
+/**
+ * Singleton class for managing a stack of error and warning messages.
+ * Provides methods to push, pop, search, and filter messages.
+ */
+class ErrorStack {
+    constructor(options = {}) {
+        this.stack = [];
+        /**
+         * Holds the isolated stack for work running inside {@link scope_run}. When
+         * a store is present, all operations target it instead of the shared stack.
+         */
+        this.scopeStorage = new node_async_hooks_1.AsyncLocalStorage();
+        this.functionNamePadWidth = options.functionNamePadWidth || 45; // Default to 45 if not specified
+    }
+    /**
+     * Returns the stack the current async context should operate on: the
+     * isolated stack when inside a {@link scope_run}, otherwise the shared one.
+     *
+     * @returns The active stack array.
+     */
+    stack_active() {
+        return this.scopeStorage.getStore() ?? this.stack;
+    }
+    /**
+     * Runs a function with an isolated error stack that the shared stack — and
+     * any foreground command draining it — never sees. Fire-and-forget
+     * background work wraps its body in this so its error traffic cannot land
+     * in a concurrent foreground command's drain window. The isolation follows
+     * the whole async causal chain started inside `fn`.
+     *
+     * @param fn - The work to run against a fresh, isolated stack.
+     * @returns Whatever `fn` returns.
+     */
+    scope_run(fn) {
+        return this.scopeStorage.run([], fn);
+    }
+    /**
+     * Marks the current depth of the active stack, for a later
+     * {@link checkpoint_drain}.
+     *
+     * @returns An opaque checkpoint (the current stack depth).
+     */
+    checkpoint_mark() {
+        return this.stack_active().length;
+    }
+    /**
+     * Removes and returns every message pushed above a checkpoint, so a command
+     * boundary can drain exactly the messages produced since it marked the
+     * stack. Messages the command's own code already popped are simply absent.
+     *
+     * @param checkpoint - A checkpoint from {@link checkpoint_mark}.
+     * @returns The drained messages, oldest first.
+     */
+    checkpoint_drain(checkpoint) {
+        return this.stack_active().splice(checkpoint);
+    }
+    /**
+     * Get the singleton instance of the ErrorStack.
+     *
+     * @param options - Optional configuration options for the stack.
+     * @returns The singleton ErrorStack instance.
+     */
+    static instance_get(options) {
+        if (!ErrorStack.instance) {
+            ErrorStack.instance = new ErrorStack(options);
+        }
+        return ErrorStack.instance;
+    }
+    /**
+     * Push a new message onto the stack.
+     *
+     * Captures the calling function name and formats the message.
+     *
+     * @param type - The type of message ("error" or "warning").
+     * @param message - The message string.
+     */
+    stack_push(type, message) {
+        const functionName = functionName_getCurrent();
+        const paddedFunctionName = str_padRight(functionName, this.functionNamePadWidth);
+        const enhancedMessage = `[${paddedFunctionName}] | ${message}`;
+        this.stack_active().push({ type, message: enhancedMessage });
+    }
+    /**
+     * Pop the last message from the stack.
+     *
+     * @returns The last message object or undefined if the stack is empty.
+     */
+    stack_pop() {
+        return this.stack_active().pop();
+    }
+    /**
+     * Search the stack for messages containing a substring.
+     *
+     * @param substring - The string to search for (case-insensitive).
+     * @returns An array of formatted strings matching the search.
+     */
+    stack_getAll() {
+        return [...this.stack_active()];
+    }
+    stack_search(substring) {
+        return this.stack_active()
+            .filter((item) => item.message.toLowerCase().includes(substring.toLowerCase()))
+            .map((item) => `${item.type}: ${item.message}`);
+    }
+    /**
+     * Get all messages of a specific type.
+     *
+     * @param type - The message type to filter by.
+     * @returns An array of message strings.
+     */
+    allOfType_get(type) {
+        return this.stack_active()
+            .filter((item) => item.type === type)
+            .map((item) => item.message);
+    }
+    /**
+     * Search for messages of a specific type containing a substring.
+     *
+     * @param type - The message type to filter by.
+     * @param substring - The string to search for (case-insensitive).
+     * @returns An array of matching message strings.
+     */
+    messagesOfType_search(type, substring) {
+        return this.stack_active()
+            .filter((item) => item.type === type &&
+            item.message.toLowerCase().includes(substring.toLowerCase()))
+            .map((item) => item.message);
+    }
+    /**
+     * Clear all messages from the stack.
+     */
+    stack_clear() {
+        const active = this.stack_active();
+        active.length = 0;
+    }
+    /**
+     * Clear all messages of a specific type from the stack.
+     *
+     * @param type - The message type to clear.
+     */
+    type_clear(type) {
+        const active = this.stack_active();
+        const kept = active.filter((item) => item.type !== type);
+        active.length = 0;
+        active.push(...kept);
+    }
+    /**
+     * Check if the stack contains any messages.
+     *
+     * @returns True if the stack is not empty, false otherwise.
+     */
+    messages_has() {
+        return this.stack_active().length > 0;
+    }
+    /**
+     * Check if the stack contains any messages of a specific type.
+     *
+     * @param type - The message type to check for.
+     * @returns True if messages of the given type exist, false otherwise.
+     */
+    messagesOfType_has(type) {
+        return this.stack_active().some((item) => item.type === type);
+    }
+}
+/**
+ * The global singleton instance of the ErrorStack.
+ */
+exports.errorStack = ErrorStack.instance_get({ functionNamePadWidth: 40 });
+/**
+ * Reconfigures the error stack with new options.
+ *
+ * @param options - The new configuration options.
+ */
+function errorStack_configure(options) {
+    ErrorStack.instance_get(options);
+}
+/**
+ * Get all messages of a specific type from the global error stack.
+ *
+ * @param type - The message type to filter by.
+ * @returns An array of message strings.
+ */
+function errorStack_getAllOfType(type) {
+    return exports.errorStack.allOfType_get(type);
+}
+//# sourceMappingURL=errorStack.js.map

package/dist/errorStack.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file fond: the neutral base under mise's engine and session host.
+ *
+ * What is generic and once lived in a ChRIS package moves here, so a layer
+ * that is not about CUBE can use it without loading CUBE's client. fond
+ * depends on nothing in `@fnndsc` (law of docs/backend-neutral.adoc, held by
+ * `npm run lint:fond`).
+ *
+ * @module
+ */
+export * from './result.js';
+export * from './errorStack.js';

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @file fond: the neutral base under mise's engine and session host.
+ *
+ * What is generic and once lived in a ChRIS package moves here, so a layer
+ * that is not about CUBE can use it without loading CUBE's client. fond
+ * depends on nothing in `@fnndsc` (law of docs/backend-neutral.adoc, held by
+ * `npm run lint:fond`).
+ *
+ * @module
+ */
+__exportStar(require("./result.js"), exports);
+__exportStar(require("./errorStack.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;GASG;AACH,8CAA4B;AAC5B,kDAAgC"}

package/dist/result.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file Result Type for Explicit Error Handling
+ *
+ * Provides a type-safe Result type that forces explicit error checking.
+ * Used in conjunction with errorStack for error accumulation and UI display.
+ *
+ * Pattern:
+ * - Functions return Result<T> instead of T | null
+ * - Errors are pushed to errorStack (for UI display)
+ * - Result type forces caller to check .ok before accessing .value
+ * - TypeScript prevents accessing .value when ok === false
+ *
+ * @module
+ */
+/**
+ * Result type representing success or failure.
+ *
+ * @example
+ * ```typescript
+ * async function getData(): Promise<Result<Data>> {
+ *   if (error) {
+ *     errorStack.stack_push("error", "Failed to get data");
+ *     return Err();
+ *   }
+ *   return Ok(data);
+ * }
+ *
+ * const result = await getData();
+ * if (!result.ok) {
+ *   // Can't access result.value here - TypeScript error
+ *   console.log(errorStack.stack_search("data"));
+ *   return;
+ * }
+ * // TypeScript knows result.ok === true, so .value exists
+ * useData(result.value);
+ * ```
+ */
+export type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+};
+/**
+ * Creates a successful Result containing a value.
+ *
+ * @param value - The success value to wrap
+ * @returns A Result indicating success
+ */
+export declare function Ok<T>(value: T): Result<T>;
+/**
+ * Creates a failed Result.
+ *
+ * Note: Error details should be pushed to errorStack before calling this.
+ *
+ * @returns A Result indicating failure
+ */
+export declare function Err<T>(): Result<T>;
+/**
+ * Type guard to check if a Result is successful.
+ *
+ * @param result - The Result to check.
+ * @returns True if the Result contains a value.
+ */
+export declare function result_isOk<T>(result: Result<T>): result is {
+    ok: true;
+    value: T;
+};
+/**
+ * Type guard to check if a Result is a failure.
+ *
+ * @param result - The Result to check.
+ * @returns True if the Result is a failure.
+ */
+export declare function result_isErr<T>(result: Result<T>): result is {
+    ok: false;
+};

package/dist/result.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * @file Result Type for Explicit Error Handling
+ *
+ * Provides a type-safe Result type that forces explicit error checking.
+ * Used in conjunction with errorStack for error accumulation and UI display.
+ *
+ * Pattern:
+ * - Functions return Result<T> instead of T | null
+ * - Errors are pushed to errorStack (for UI display)
+ * - Result type forces caller to check .ok before accessing .value
+ * - TypeScript prevents accessing .value when ok === false
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ok = Ok;
+exports.Err = Err;
+exports.result_isOk = result_isOk;
+exports.result_isErr = result_isErr;
+/**
+ * Creates a successful Result containing a value.
+ *
+ * @param value - The success value to wrap
+ * @returns A Result indicating success
+ */
+function Ok(value) {
+    return { ok: true, value };
+}
+/**
+ * Creates a failed Result.
+ *
+ * Note: Error details should be pushed to errorStack before calling this.
+ *
+ * @returns A Result indicating failure
+ */
+function Err() {
+    return { ok: false };
+}
+/**
+ * Type guard to check if a Result is successful.
+ *
+ * @param result - The Result to check.
+ * @returns True if the Result contains a value.
+ */
+function result_isOk(result) {
+    return result.ok === true;
+}
+/**
+ * Type guard to check if a Result is a failure.
+ *
+ * @param result - The Result to check.
+ * @returns True if the Result is a failure.
+ */
+function result_isErr(result) {
+    return result.ok === false;
+}
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AAmCH,gBAEC;AASD,kBAEC;AAQD,kCAEC;AAQD,oCAEC;AAvCD;;;;;GAKG;AACH,SAAgB,EAAE,CAAI,KAAQ;IAC5B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,GAAG;IACjB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,WAAW,CAAI,MAAiB;IAC9C,OAAO,MAAM,CAAC,EAAE,KAAK,IAAI,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAAI,MAAiB;IAC/C,OAAO,MAAM,CAAC,EAAE,KAAK,KAAK,CAAC;AAC7B,CAAC"}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@fnndsc/fond",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The neutral base under mise's engine and session host: Result, the error stack, and (in later steps) the VFS framework and the sink and surface interfaces. Depends on nothing in @fnndsc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FNNDSC/mise.git",
+    "directory": "packages/fond"
+  },
+  "homepage": "https://github.com/FNNDSC/mise/tree/main/packages/fond#readme",
+  "bugs": {
+    "url": "https://github.com/FNNDSC/mise/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -fr dist && tsc",
+    "test": "jest --coverage",
+    "prepublishOnly": "test -f dist/index.js && test -f dist/index.d.ts"
+  },
+  "keywords": [
+    "chris",
+    "mise",
+    "fnndsc"
+  ],
+  "author": "Rudolph Pienaar",
+  "license": "MIT",
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.0.0"
+  }
+}