@smoothbricks/lmao 0.1.0

package/dist/lib/result.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Result types for type-safe error handling without exceptions.
+ *
+ * ## Classes
+ * - `Ok<V, T>` - Success result with fluent tag API
+ * - `Err<E, T>` - Error result with fluent tag API
+ *
+ * ## Error Factories
+ * - `defineCodeError(code)` - Create callable error class with `code` on prototype
+ *
+ * ## Result Row Writer
+ *
+ * Span start reserves row 1 for the eventual span-end entry, so fluent result
+ * methods can write directly to that fixed row instead of capturing deferred
+ * closure chains.
+ *
+ * @example
+ * ```typescript
+ * // Define error codes as callable classes
+ * const NOT_FOUND = defineCodeError('NOT_FOUND')<{ userId: string }>();
+ * const VALIDATION_FAILED = defineCodeError('VALIDATION_FAILED')<{ field: string }>();
+ *
+ * // Use in ops - no 'new' required
+ * return ctx.err(NOT_FOUND({ userId }));
+ * return ctx.err(VALIDATION_FAILED({ field: 'email' })).message('Invalid email');
+ *
+ * // instanceof works for type narrowing
+ * if (result.isErr(NOT_FOUND)) {
+ *   console.log(result.error.userId); // typed!
+ * }
+ * ```
+ */
+import type { InferSchema, LogSchema } from './schema/types.js';
+import type { AnySpanBuffer } from './types.js';
+/**
+ * Interface for tagged errors that can be discriminated with isErr(Tag).
+ * Used by Blocked, RetriesExhausted, and user-defined error classes.
+ */
+export interface TaggedError<Tag extends string = string> {
+    readonly _tag: Tag;
+}
+/**
+ * Constructor type for tagged errors.
+ * Used with Result.isErr(Tag) to check error type via instanceof.
+ */
+export interface TaggedErrorConstructor<T extends TaggedError = TaggedError> {
+    readonly _tag: T['_tag'];
+    readonly prototype: T;
+    readonly [Symbol.hasInstance]: (value: unknown) => boolean;
+}
+type OkJson<V> = {
+    ok: true;
+    value: V;
+};
+type ErrJson<E> = {
+    ok: false;
+    error: E;
+};
+/**
+ * Success result with fluent tag application.
+ *
+ * Created by `ctx.ok(value)`. Tags are captured as closures and applied when
+ * span()/trace() completes, ensuring writes go to the correct buffer.
+ *
+ * @typeParam V - The type of the success value
+ * @typeParam T - The log schema for buffer tag application
+ *
+ * @example
+ * ```typescript
+ * return ctx.ok(user);
+ * return ctx.ok(user).with({ userId: user.id }).message('Created');
+ * ```
+ */
+export declare class Ok<V, T extends LogSchema = LogSchema> {
+    readonly value: V;
+    private readonly _schema;
+    private readonly _buffer;
+    private _writer;
+    constructor(value: V, schema?: T, buffer?: AnySpanBuffer);
+    private _resultWriter;
+    /** Discriminant for type narrowing. */
+    get success(): true;
+    /** Tag discriminant for tagged result interop — matches the { _tag: 'ok' } protocol. */
+    get _tag(): 'ok';
+    /** Type guard - always returns true for Ok. */
+    isOk(): this is Ok<V, T>;
+    /** Type guard - always returns false for Ok. */
+    isErr(): false;
+    isErr<Tag extends TaggedError>(_Tag: TaggedErrorConstructor<Tag>): false;
+    /** Get the value (always present for Ok). */
+    get maybeValue(): V;
+    /** Get the error (always undefined for Ok). */
+    get maybeError(): undefined;
+    /** Transform the success value. */
+    map<U>(fn: (value: V) => U): Ok<U, T>;
+    /** No-op for Ok (error transformation). */
+    mapErr<F>(_fn: (error: never) => F): Ok<V, T>;
+    /** Transform the success value, potentially returning an error. */
+    flatMap<U, F>(fn: (value: V) => Result<U, F, T>): Result<U, F, T>;
+    /** Get the value (always returns value for Ok). */
+    unwrapOr<U>(_defaultValue: U): V;
+    /** Get the value (always returns value for Ok). */
+    unwrapOrElse<U>(_fn: (error: never) => U): V;
+    /** Pattern match on the result. */
+    match<U>(handlers: {
+        ok: (value: V) => U;
+        err: (error: never) => U;
+    }): U;
+    /**
+     * Set multiple attributes on the span-end entry (row 1).
+     * Deferred - applied when span()/trace() completes.
+     *
+     * @example ctx.ok(result).with({ userId: 'u1', operation: 'CREATE' })
+     */
+    with(attributes: Partial<InferSchema<T>>): this;
+    /**
+     * Set result message on span-end entry (row 1).
+     * Overwrites the default span name in the message column.
+     *
+     * @example ctx.ok(result).message('User created successfully')
+     */
+    message(text: string): this;
+    /**
+     * Set source code line number on span-end entry (row 1).
+     * Typically injected by transformer.
+     *
+     * @example ctx.ok(result).line(42)
+     */
+    line(lineNumber: number): this;
+    toJSON(): OkJson<V>;
+}
+/**
+ * Error result with fluent tag application.
+ *
+ * Created by `ctx.err(error)`. The error is stored directly (flat structure).
+ * Supports fluent `.with()`, `.message()`, `.line()` for deferred tag application.
+ *
+ * @typeParam E - The type of the error
+ * @typeParam T - The log schema for buffer tag application
+ *
+ * @example
+ * ```typescript
+ * const NOT_FOUND = defineCodeError('NOT_FOUND')<{ userId: string }>();
+ * return ctx.err(NOT_FOUND({ userId }));
+ * return ctx.err(NOT_FOUND({ userId })).message('User not found');
+ *
+ * // Tagged errors work too
+ * return ctx.err(Blocked.service('payment-api'));
+ * ```
+ */
+export declare class Err<E, T extends LogSchema = LogSchema> {
+    readonly error: E;
+    private readonly _schema;
+    private readonly _buffer;
+    private _writer;
+    constructor(error: E, schema?: T, buffer?: AnySpanBuffer);
+    private _resultWriter;
+    /** Discriminant for type narrowing. */
+    get success(): false;
+    /** Tag discriminant for tagged result interop — matches the { _tag: 'err' } protocol. */
+    get _tag(): 'err';
+    /** Type guard - always returns false for Err. */
+    isOk(): false;
+    /**
+     * Check if this is an error result, optionally matching a tagged type or predicate.
+     *
+     * @example
+     * ```typescript
+     * if (result.isErr()) { ... }  // Always true for Err
+     * if (result.isErr(Blocked)) { ... }  // Check instanceof Blocked
+     * if (result.isErr(NOT_FOUND)) { ... }  // Check instanceof NOT_FOUND
+     * if (result.isErr(e => e.code === 'X')) { ... }  // Predicate
+     * ```
+     */
+    isErr(): this is Err<E, T>;
+    isErr<Tag extends TaggedError>(Tag: TaggedErrorConstructor<Tag>): this is Err<Tag, T>;
+    isErr<C extends abstract new (...args: never[]) => unknown>(Class: C): this is Err<InstanceType<C>, T>;
+    isErr(predicate: (error: E) => boolean): boolean;
+    /** Get the value (always undefined for Err). */
+    get maybeValue(): undefined;
+    /** Get the error (always present for Err). */
+    get maybeError(): E;
+    /** No-op for Err (value transformation). */
+    map<U>(_fn: (value: never) => U): Err<E, T>;
+    /** Transform the error. */
+    mapErr<F>(fn: (error: E) => F): Err<F, T>;
+    /** No-op for Err (returns self). */
+    flatMap<U, F>(_fn: (value: never) => Result<U, F>): Err<E, T>;
+    /** Get the default value (error is ignored). */
+    unwrapOr<U>(defaultValue: U): U;
+    /** Compute a value from the error. */
+    unwrapOrElse<U>(fn: (error: E) => U): U;
+    /** Pattern match on the result. */
+    match<U>(handlers: {
+        ok: (value: never) => U;
+        err: (error: E) => U;
+    }): U;
+    /**
+     * Set multiple attributes on the span-end entry (row 1).
+     * Deferred - applied when span()/trace() completes.
+     *
+     * @example ctx.err(error).with({ user_id: 'u1' })
+     */
+    with(attributes: Partial<InferSchema<T>>): this;
+    /**
+     * Set result message on span-end entry (row 1).
+     * Overwrites the default span name in the message column.
+     *
+     * @example ctx.err('ERROR', details).message('Operation failed')
+     */
+    message(text: string): this;
+    /**
+     * Set source code line number on span-end entry (row 1).
+     * Typically injected by transformer.
+     *
+     * @example ctx.err('ERROR', details).line(42)
+     */
+    line(lineNumber: number): this;
+    toJSON(): ErrJson<E>;
+}
+/** Union type for Result - either Ok or Err. */
+export type Result<V, E, T extends LogSchema = LogSchema> = Ok<V, T> | Err<E, T>;
+/**
+ * Code error instance type - has `code` on prototype plus fields as own properties.
+ */
+export interface CodeErrorInstance<Code extends string, _Fields extends object> {
+    readonly code: Code;
+}
+/**
+ * Callable class type returned by defineCodeError.
+ * Can be called without `new`, instanceof works.
+ */
+export interface CodeErrorClass<Code extends string, Fields extends object> {
+    (fields: Fields): CodeErrorInstance<Code, Fields> & Fields;
+    readonly prototype: {
+        readonly code: Code;
+    };
+}
+/**
+ * Create a callable error class with `code` on prototype.
+ *
+ * The returned class can be called without `new` and supports `instanceof`.
+ *
+ * @param code - The error code string (becomes a literal type)
+ * @returns A curried function that takes type parameter for fields
+ *
+ * @example
+ * ```typescript
+ * const NOT_FOUND = defineCodeError('NOT_FOUND')<{ userId: string }>();
+ * const VALIDATION_FAILED = defineCodeError('VALIDATION_FAILED')<{ field: string }>();
+ *
+ * // Call without 'new'
+ * const err = NOT_FOUND({ userId: 'u1' });
+ * err.code;     // 'NOT_FOUND' (from prototype)
+ * err.userId;   // 'u1' (own property)
+ *
+ * // instanceof works
+ * err instanceof NOT_FOUND;  // true
+ *
+ * // Use with ctx.err()
+ * return ctx.err(NOT_FOUND({ userId }));
+ *
+ * // Type narrowing with isErr()
+ * if (result.isErr(NOT_FOUND)) {
+ *   result.error.userId;  // typed!
+ * }
+ * ```
+ */
+export declare function defineCodeError<Code extends string>(code: Code): <Fields extends object = Record<string, never>>() => CodeErrorClass<Code, Fields>;
+/**
+ * Check if an error has a `code` property.
+ * Used by writeSpanEnd to extract error_code for logging.
+ */
+export declare function hasErrorCode(error: unknown): error is {
+    code: string;
+};
+/**
+ * Extract success type from a Result type.
+ * Returns `never` if R is not a Result.
+ */
+export type ResultSuccess<R> = R extends Result<infer S, unknown, LogSchema> ? S : never;
+/**
+ * Extract success type from a Promise<Result> type.
+ * Returns `never` if R is not a Promise<Result>.
+ */
+export type PromiseResultSuccess<R> = R extends Promise<Result<infer S, unknown, LogSchema>> ? S : never;
+/**
+ * Extract success type from either Result or Promise<Result>.
+ * Useful for inferring the success type from Op return values.
+ */
+export type ExtractSuccess<R> = ResultSuccess<R> | PromiseResultSuccess<R>;
+/**
+ * Extract error type from a Result type.
+ * Returns `never` if R is not a Result.
+ */
+export type ResultError<R> = R extends Result<unknown, infer E, LogSchema> ? E : never;
+/**
+ * Extract error type from a Promise<Result> type.
+ * Returns `never` if R is not a Promise<Result>.
+ */
+export type PromiseResultError<R> = R extends Promise<Result<unknown, infer E, LogSchema>> ? E : never;
+/**
+ * Extract error type from either Result or Promise<Result>.
+ * Useful for inferring the error type from Op return values.
+ */
+export type ExtractError<R> = ResultError<R> | PromiseResultError<R>;
+export {};
+//# sourceMappingURL=result.d.ts.map

package/dist/lib/result.d.ts.map

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

package/dist/lib/result.js

@@ -0,0 +1,359 @@
+/**
+ * Result types for type-safe error handling without exceptions.
+ *
+ * ## Classes
+ * - `Ok<V, T>` - Success result with fluent tag API
+ * - `Err<E, T>` - Error result with fluent tag API
+ *
+ * ## Error Factories
+ * - `defineCodeError(code)` - Create callable error class with `code` on prototype
+ *
+ * ## Result Row Writer
+ *
+ * Span start reserves row 1 for the eventual span-end entry, so fluent result
+ * methods can write directly to that fixed row instead of capturing deferred
+ * closure chains.
+ *
+ * @example
+ * ```typescript
+ * // Define error codes as callable classes
+ * const NOT_FOUND = defineCodeError('NOT_FOUND')<{ userId: string }>();
+ * const VALIDATION_FAILED = defineCodeError('VALIDATION_FAILED')<{ field: string }>();
+ *
+ * // Use in ops - no 'new' required
+ * return ctx.err(NOT_FOUND({ userId }));
+ * return ctx.err(VALIDATION_FAILED({ field: 'email' })).message('Invalid email');
+ *
+ * // instanceof works for type narrowing
+ * if (result.isErr(NOT_FOUND)) {
+ *   console.log(result.error.userId); // typed!
+ * }
+ * ```
+ */
+import { createResultWriter } from './codegen/fixedPositionWriterGenerator.js';
+function ensureResultWriter(writer, schema, buffer, resultOrError, isError) {
+    if (writer) {
+        return writer;
+    }
+    if (!schema || !buffer) {
+        return undefined;
+    }
+    return createResultWriter(schema, buffer, resultOrError, isError);
+}
+function isErrPredicate(value) {
+    const prototype = Reflect.get(value, 'prototype');
+    return prototype === undefined || prototype === Function.prototype;
+}
+function isInstanceofMatcher(value) {
+    return typeof value === 'function' && !isErrPredicate(value);
+}
+function createCodeErrorValue(prototype, fields) {
+    return Object.assign(Object.create(prototype), fields);
+}
+// =============================================================================
+// OK CLASS
+// =============================================================================
+/**
+ * Success result with fluent tag application.
+ *
+ * Created by `ctx.ok(value)`. Tags are captured as closures and applied when
+ * span()/trace() completes, ensuring writes go to the correct buffer.
+ *
+ * @typeParam V - The type of the success value
+ * @typeParam T - The log schema for buffer tag application
+ *
+ * @example
+ * ```typescript
+ * return ctx.ok(user);
+ * return ctx.ok(user).with({ userId: user.id }).message('Created');
+ * ```
+ */
+export class Ok {
+    value;
+    _schema;
+    _buffer;
+    _writer;
+    constructor(value, schema, buffer) {
+        this.value = value;
+        this._schema = schema;
+        this._buffer = buffer;
+    }
+    _resultWriter() {
+        this._writer = ensureResultWriter(this._writer, this._schema, this._buffer, this.value, false);
+        return this._writer;
+    }
+    /** Discriminant for type narrowing. */
+    get success() {
+        return true;
+    }
+    /** Tag discriminant for tagged result interop — matches the { _tag: 'ok' } protocol. */
+    get _tag() {
+        return 'ok';
+    }
+    /** Type guard - always returns true for Ok. */
+    isOk() {
+        return true;
+    }
+    isErr(_predicate) {
+        return false;
+    }
+    /** Get the value (always present for Ok). */
+    get maybeValue() {
+        return this.value;
+    }
+    /** Get the error (always undefined for Ok). */
+    get maybeError() {
+        return undefined;
+    }
+    /** Transform the success value. */
+    map(fn) {
+        return new Ok(fn(this.value), this._schema, this._buffer);
+    }
+    /** No-op for Ok (error transformation). */
+    mapErr(_fn) {
+        return this;
+    }
+    /** Transform the success value, potentially returning an error. */
+    flatMap(fn) {
+        return fn(this.value);
+    }
+    /** Get the value (always returns value for Ok). */
+    unwrapOr(_defaultValue) {
+        return this.value;
+    }
+    /** Get the value (always returns value for Ok). */
+    unwrapOrElse(_fn) {
+        return this.value;
+    }
+    /** Pattern match on the result. */
+    match(handlers) {
+        return handlers.ok(this.value);
+    }
+    /**
+     * Set multiple attributes on the span-end entry (row 1).
+     * Deferred - applied when span()/trace() completes.
+     *
+     * @example ctx.ok(result).with({ userId: 'u1', operation: 'CREATE' })
+     */
+    with(attributes) {
+        this._resultWriter()?.with(attributes);
+        return this;
+    }
+    /**
+     * Set result message on span-end entry (row 1).
+     * Overwrites the default span name in the message column.
+     *
+     * @example ctx.ok(result).message('User created successfully')
+     */
+    message(text) {
+        this._resultWriter()?.message(text);
+        return this;
+    }
+    /**
+     * Set source code line number on span-end entry (row 1).
+     * Typically injected by transformer.
+     *
+     * @example ctx.ok(result).line(42)
+     */
+    line(lineNumber) {
+        this._resultWriter()?.line(lineNumber);
+        return this;
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return { ok: true, value: this.value };
+    }
+    toJSON() {
+        return { ok: true, value: this.value };
+    }
+}
+// =============================================================================
+// ERR CLASS
+// =============================================================================
+/**
+ * Error result with fluent tag application.
+ *
+ * Created by `ctx.err(error)`. The error is stored directly (flat structure).
+ * Supports fluent `.with()`, `.message()`, `.line()` for deferred tag application.
+ *
+ * @typeParam E - The type of the error
+ * @typeParam T - The log schema for buffer tag application
+ *
+ * @example
+ * ```typescript
+ * const NOT_FOUND = defineCodeError('NOT_FOUND')<{ userId: string }>();
+ * return ctx.err(NOT_FOUND({ userId }));
+ * return ctx.err(NOT_FOUND({ userId })).message('User not found');
+ *
+ * // Tagged errors work too
+ * return ctx.err(Blocked.service('payment-api'));
+ * ```
+ */
+export class Err {
+    error;
+    _schema;
+    _buffer;
+    _writer;
+    constructor(error, schema, buffer) {
+        this.error = error;
+        this._schema = schema;
+        this._buffer = buffer;
+    }
+    _resultWriter() {
+        this._writer = ensureResultWriter(this._writer, this._schema, this._buffer, this.error, true);
+        return this._writer;
+    }
+    /** Discriminant for type narrowing. */
+    get success() {
+        return false;
+    }
+    /** Tag discriminant for tagged result interop — matches the { _tag: 'err' } protocol. */
+    get _tag() {
+        return 'err';
+    }
+    /** Type guard - always returns false for Err. */
+    isOk() {
+        return false;
+    }
+    isErr(tagOrPredicate) {
+        if (tagOrPredicate === undefined)
+            return true;
+        // instanceof check for classes (including TaggedError and CodeError)
+        if (isErrPredicate(tagOrPredicate)) {
+            return tagOrPredicate(this.error);
+        }
+        if (isInstanceofMatcher(tagOrPredicate)) {
+            return this.error instanceof tagOrPredicate;
+        }
+        return false;
+    }
+    /** Get the value (always undefined for Err). */
+    get maybeValue() {
+        return undefined;
+    }
+    /** Get the error (always present for Err). */
+    get maybeError() {
+        return this.error;
+    }
+    /** No-op for Err (value transformation). */
+    map(_fn) {
+        return this;
+    }
+    /** Transform the error. */
+    mapErr(fn) {
+        return new Err(fn(this.error), this._schema, this._buffer);
+    }
+    /** No-op for Err (returns self). */
+    flatMap(_fn) {
+        return this;
+    }
+    /** Get the default value (error is ignored). */
+    unwrapOr(defaultValue) {
+        return defaultValue;
+    }
+    /** Compute a value from the error. */
+    unwrapOrElse(fn) {
+        return fn(this.error);
+    }
+    /** Pattern match on the result. */
+    match(handlers) {
+        return handlers.err(this.error);
+    }
+    /**
+     * Set multiple attributes on the span-end entry (row 1).
+     * Deferred - applied when span()/trace() completes.
+     *
+     * @example ctx.err(error).with({ user_id: 'u1' })
+     */
+    with(attributes) {
+        this._resultWriter()?.with(attributes);
+        return this;
+    }
+    /**
+     * Set result message on span-end entry (row 1).
+     * Overwrites the default span name in the message column.
+     *
+     * @example ctx.err('ERROR', details).message('Operation failed')
+     */
+    message(text) {
+        this._resultWriter()?.message(text);
+        return this;
+    }
+    /**
+     * Set source code line number on span-end entry (row 1).
+     * Typically injected by transformer.
+     *
+     * @example ctx.err('ERROR', details).line(42)
+     */
+    line(lineNumber) {
+        this._resultWriter()?.line(lineNumber);
+        return this;
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return { ok: false, error: this.error };
+    }
+    toJSON() {
+        return { ok: false, error: this.error };
+    }
+}
+/**
+ * Create a callable error class with `code` on prototype.
+ *
+ * The returned class can be called without `new` and supports `instanceof`.
+ *
+ * @param code - The error code string (becomes a literal type)
+ * @returns A curried function that takes type parameter for fields
+ *
+ * @example
+ * ```typescript
+ * const NOT_FOUND = defineCodeError('NOT_FOUND')<{ userId: string }>();
+ * const VALIDATION_FAILED = defineCodeError('VALIDATION_FAILED')<{ field: string }>();
+ *
+ * // Call without 'new'
+ * const err = NOT_FOUND({ userId: 'u1' });
+ * err.code;     // 'NOT_FOUND' (from prototype)
+ * err.userId;   // 'u1' (own property)
+ *
+ * // instanceof works
+ * err instanceof NOT_FOUND;  // true
+ *
+ * // Use with ctx.err()
+ * return ctx.err(NOT_FOUND({ userId }));
+ *
+ * // Type narrowing with isErr()
+ * if (result.isErr(NOT_FOUND)) {
+ *   result.error.userId;  // typed!
+ * }
+ * ```
+ */
+export function defineCodeError(code) {
+    return () => {
+        // Constructor function that works with or without 'new'
+        const CodeError = function (fields) {
+            // Allow calling without 'new'
+            if (!(this instanceof CodeError)) {
+                return createCodeErrorValue(CodeError.prototype, fields);
+            }
+            // Assign fields as own properties
+            Object.assign(this, fields);
+            return this;
+        };
+        // Put code on prototype so all instances share it
+        Object.defineProperty(CodeError.prototype, 'code', {
+            value: code,
+            writable: false,
+            enumerable: true,
+            configurable: false,
+        });
+        return CodeError;
+    };
+}
+/**
+ * Check if an error has a `code` property.
+ * Used by writeSpanEnd to extract error_code for logging.
+ */
+export function hasErrorCode(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'code' in error &&
+        typeof error.code === 'string');
+}