@smoothbricks/lmao 0.1.0

package/src/lib/result.ts

@@ -0,0 +1,550 @@
+/**
+ * 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, type ResultWriter } from './codegen/fixedPositionWriterGenerator.js';
+import type { InferSchema, LogSchema } from './schema/types.js';
+import type { AnySpanBuffer } from './types.js';
+
+// =============================================================================
+// TAGGED ERROR INTERFACE
+// =============================================================================
+
+/**
+ * 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 };
+
+type ErrPredicate<E> = (error: E) => boolean;
+type ErrClassMatcher = abstract new (...args: never[]) => unknown;
+type ErrMatcher<E> = TaggedErrorConstructor<TaggedError> | ErrClassMatcher | ErrPredicate<E>;
+
+type BoundResultWriter<T extends LogSchema, R, E> = ResultWriter<T, R, E>;
+
+function ensureResultWriter<T extends LogSchema, R, E>(
+  writer: BoundResultWriter<T, R, E> | undefined,
+  schema: T | undefined,
+  buffer: AnySpanBuffer | undefined,
+  resultOrError: R | E,
+  isError: boolean,
+): BoundResultWriter<T, R, E> | undefined {
+  if (writer) {
+    return writer;
+  }
+
+  if (!schema || !buffer) {
+    return undefined;
+  }
+
+  return createResultWriter<T, R, E>(schema, buffer, resultOrError, isError);
+}
+
+function isErrPredicate<E>(value: ErrMatcher<E>): value is ErrPredicate<E> {
+  const prototype = Reflect.get(value, 'prototype');
+  return prototype === undefined || prototype === Function.prototype;
+}
+
+function isInstanceofMatcher<E>(value: ErrMatcher<E>): value is TaggedErrorConstructor<TaggedError> | ErrClassMatcher {
+  return typeof value === 'function' && !isErrPredicate(value);
+}
+
+function createCodeErrorValue<Code extends string, Fields extends object>(
+  prototype: object,
+  fields: Fields,
+): CodeErrorInstance<Code, Fields> & 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<V, T extends LogSchema = LogSchema> {
+  readonly value: V;
+
+  private readonly _schema: T | undefined;
+  private readonly _buffer: AnySpanBuffer | undefined;
+  private _writer: BoundResultWriter<T, V, never> | undefined;
+
+  constructor(value: V, schema?: T, buffer?: AnySpanBuffer) {
+    this.value = value;
+    this._schema = schema;
+    this._buffer = buffer;
+  }
+
+  private _resultWriter(): BoundResultWriter<T, V, never> | undefined {
+    this._writer = ensureResultWriter<T, V, never>(this._writer, this._schema, this._buffer, this.value, false);
+    return this._writer;
+  }
+
+  /** Discriminant for type narrowing. */
+  get success(): true {
+    return true;
+  }
+
+  /** Tag discriminant for tagged result interop — matches the { _tag: 'ok' } protocol. */
+  get _tag(): 'ok' {
+    return 'ok';
+  }
+
+  /** Type guard - always returns true for Ok. */
+  isOk(): this is Ok<V, T> {
+    return true;
+  }
+
+  /** Type guard - always returns false for Ok. */
+  isErr(): false;
+  isErr<Tag extends TaggedError>(_Tag: TaggedErrorConstructor<Tag>): false;
+  isErr(_predicate?: unknown): false {
+    return false;
+  }
+
+  /** Get the value (always present for Ok). */
+  get maybeValue(): V {
+    return this.value;
+  }
+
+  /** Get the error (always undefined for Ok). */
+  get maybeError(): undefined {
+    return undefined;
+  }
+
+  /** Transform the success value. */
+  map<U>(fn: (value: V) => U): Ok<U, T> {
+    return new Ok<U, T>(fn(this.value), this._schema, this._buffer);
+  }
+
+  /** No-op for Ok (error transformation). */
+  mapErr<F>(_fn: (error: never) => F): Ok<V, T> {
+    return this;
+  }
+
+  /** Transform the success value, potentially returning an error. */
+  flatMap<U, F>(fn: (value: V) => Result<U, F, T>): Result<U, F, T> {
+    return fn(this.value);
+  }
+
+  /** Get the value (always returns value for Ok). */
+  unwrapOr<U>(_defaultValue: U): V {
+    return this.value;
+  }
+
+  /** Get the value (always returns value for Ok). */
+  unwrapOrElse<U>(_fn: (error: never) => U): V {
+    return this.value;
+  }
+
+  /** Pattern match on the result. */
+  match<U>(handlers: { ok: (value: V) => U; err: (error: never) => U }): U {
+    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: Partial<InferSchema<T>>): this {
+    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: string): this {
+    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: number): this {
+    this._resultWriter()?.line(lineNumber);
+    return this;
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')](): OkJson<V> {
+    return { ok: true, value: this.value };
+  }
+
+  toJSON(): OkJson<V> {
+    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<E, T extends LogSchema = LogSchema> {
+  readonly error: E;
+
+  private readonly _schema: T | undefined;
+  private readonly _buffer: AnySpanBuffer | undefined;
+  private _writer: BoundResultWriter<T, never, E> | undefined;
+
+  constructor(error: E, schema?: T, buffer?: AnySpanBuffer) {
+    this.error = error;
+    this._schema = schema;
+    this._buffer = buffer;
+  }
+
+  private _resultWriter(): BoundResultWriter<T, never, E> | undefined {
+    this._writer = ensureResultWriter<T, never, E>(this._writer, this._schema, this._buffer, this.error, true);
+    return this._writer;
+  }
+
+  /** Discriminant for type narrowing. */
+  get success(): false {
+    return false;
+  }
+
+  /** Tag discriminant for tagged result interop — matches the { _tag: 'err' } protocol. */
+  get _tag(): 'err' {
+    return 'err';
+  }
+
+  /** Type guard - always returns false for Err. */
+  isOk(): false {
+    return 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;
+  isErr<Tag extends TaggedError>(
+    tagOrPredicate?: TaggedErrorConstructor<Tag> | ErrClassMatcher | ErrPredicate<E>,
+  ): boolean {
+    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(): undefined {
+    return undefined;
+  }
+
+  /** Get the error (always present for Err). */
+  get maybeError(): E {
+    return this.error;
+  }
+
+  /** No-op for Err (value transformation). */
+  map<U>(_fn: (value: never) => U): Err<E, T> {
+    return this;
+  }
+
+  /** Transform the error. */
+  mapErr<F>(fn: (error: E) => F): Err<F, T> {
+    return new Err<F, T>(fn(this.error), this._schema, this._buffer);
+  }
+
+  /** No-op for Err (returns self). */
+  flatMap<U, F>(_fn: (value: never) => Result<U, F>): Err<E, T> {
+    return this;
+  }
+
+  /** Get the default value (error is ignored). */
+  unwrapOr<U>(defaultValue: U): U {
+    return defaultValue;
+  }
+
+  /** Compute a value from the error. */
+  unwrapOrElse<U>(fn: (error: E) => U): U {
+    return fn(this.error);
+  }
+
+  /** Pattern match on the result. */
+  match<U>(handlers: { ok: (value: never) => U; err: (error: E) => U }): U {
+    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: Partial<InferSchema<T>>): this {
+    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: string): this {
+    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: number): this {
+    this._resultWriter()?.line(lineNumber);
+    return this;
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')](): ErrJson<E> {
+    return { ok: false, error: this.error };
+  }
+
+  toJSON(): ErrJson<E> {
+    return { ok: false, error: this.error };
+  }
+}
+
+// =============================================================================
+// RESULT TYPE
+// =============================================================================
+
+/** 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 FACTORY
+// =============================================================================
+
+/**
+ * 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 function defineCodeError<Code extends string>(code: Code) {
+  return <Fields extends object = Record<string, never>>(): CodeErrorClass<Code, Fields> => {
+    // Constructor function that works with or without 'new'
+    const CodeError: CodeErrorClass<Code, Fields> = function (
+      this: (CodeErrorInstance<Code, Fields> & Fields) | undefined,
+      fields: Fields,
+    ): CodeErrorInstance<Code, Fields> & Fields {
+      // Allow calling without 'new'
+      if (!(this instanceof CodeError)) {
+        return createCodeErrorValue<Code, Fields>(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: unknown): error is { code: string } {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    'code' in error &&
+    typeof (error as { code: unknown }).code === 'string'
+  );
+}
+
+// =============================================================================
+// RESULT TYPE EXTRACTION UTILITIES
+// =============================================================================
+
+/**
+ * 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>;

package/src/lib/schema/LogSchema.ts

@@ -0,0 +1,153 @@
+/**
+ * LogSchema class for logging-specific schema functionality
+ *
+ * Extends ColumnSchema from arrow-builder with logging-specific features:
+ * - Schema extension with reserved name validation
+ * - Integration with lmao's logging system
+ *
+ * The base ColumnSchema provides generic cached field access.
+ * LogSchema adds logging-specific extension capabilities.
+ */
+
+import { ColumnSchema } from '@smoothbricks/arrow-builder';
+import type { SchemaFields } from './types.js';
+
+/**
+ * Reserved method names that cannot be used as attribute names
+ *
+ * These names are reserved to prevent conflicts or confusion:
+ * - Technically conflicting: Names that would shadow actual methods/properties
+ *   on TagWriter, SpanLogger, FluentLogEntry, or result objects
+ * - Confusing: Names that would create confusing code patterns even though
+ *   they don't technically conflict (e.g., ctx.tag.tag() or ctx.scope.scope)
+ */
+const RESERVED_NAMES = new Set([
+  // Technically conflicting - methods on TagWriter/FluentLogEntry/result objects
+  'with', // Used on TagWriter, FluentLogEntry, Ok, Err
+  'message', // Used on Ok, Err
+
+  // Technically conflicting - log level methods on SpanLogger
+  'info', // ctx.log.info()
+  'debug', // ctx.log.debug()
+  'warn', // ctx.log.warn()
+  'error', // ctx.log.error()
+  'trace', // ctx.log.trace()
+
+  // Internal SpanLogger methods (prefixed with _ but included for completeness)
+  '_nextRow', // Internal row advancement
+  '_buffer', // Internal buffer reference
+  '_writeIndex', // Internal write position
+  '_getNextBuffer', // Internal buffer chaining
+  '_setScope', // Internal scope setter
+  '_prefillScopedAttributes', // Internal scope prefill
+
+  // Internal FF logging methods (called by evaluator, not on public type)
+  'ffAccess', // Feature flag access logging
+  'ffUsage', // Feature flag usage logging
+
+  // Confusing - properties on SpanContext (not technically conflicting)
+  'tag', // ctx.tag is TagWriter; ctx.tag.tag() would be confusing
+  'scope', // ctx.scope is readonly; ctx.scope.scope would be confusing
+
+  // Confusing - methods on SpanContext (not technically conflicting)
+  'ok', // ctx.ok() is method; ctx.tag.ok() or ctx.ok(result).ok() would be confusing
+  'err', // ctx.err() is method; ctx.tag.err() or ctx.err(code, details).err() would be confusing
+  'span', // ctx.span() is method; ctx.tag.span() would be confusing
+]);
+
+/**
+ * LogSchema class - extends ColumnSchema with logging-specific features
+ *
+ * Provides all the generic schema functionality from ColumnSchema plus
+ * logging-specific extension with reserved name validation.
+ *
+ * @template T - The schema fields type (SchemaFields)
+ */
+export class LogSchema<T extends SchemaFields = SchemaFields> extends ColumnSchema<T> {
+  /**
+   * Assert that user-provided field names don't conflict with reserved names
+   * and don't start with underscore (reserved for system properties)
+   *
+   * @throws Error if any field name is reserved or starts with _
+   */
+  static assertUserFieldNames(fieldNames: readonly string[]): void {
+    for (const name of fieldNames) {
+      if (name.startsWith('_')) {
+        throw new Error(`Field name '${name}' cannot start with '_' - this prefix is reserved for system properties`);
+      }
+      if (RESERVED_NAMES.has(name)) {
+        throw new Error(
+          `Attribute name '${name}' is reserved and cannot be used. ` +
+            `Reserved names: ${Array.from(RESERVED_NAMES).join(', ')}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Extend this schema with additional fields
+   *
+   * Creates a new LogSchema instance with merged fields.
+   * Validates that extension fields don't conflict with existing fields
+   * and don't use reserved names (logging-specific validation).
+   *
+   * @param extension - Additional schema fields to add
+   * @returns New LogSchema instance with merged fields
+   * @throws Error if field names conflict or reserved names are used
+   *
+   * @example
+   * ```typescript
+   * const base = new LogSchema({ requestId: S.category() });
+   * const extended = base.extend({ duration: S.number() });
+   * // extended.fields = { requestId: ..., duration: ... }
+   * ```
+   */
+  extend<U extends SchemaFields>(extension: U): LogSchema<T & U> {
+    // Check for field name conflicts
+    const extensionKeys = Object.keys(extension);
+    for (const key of extensionKeys) {
+      if (this._columnNames.includes(key)) {
+        throw new Error(
+          `Schema conflict: attribute '${key}' already exists in base schema. ` +
+            `Base schema has: ${this._columnNames.join(', ')}`,
+        );
+      }
+    }
+
+    // Assert extension doesn't use reserved names (logging-specific)
+    LogSchema.assertUserFieldNames(extensionKeys);
+
+    // Perform shallow merge
+    // Create merged via explicit property assignment to preserve property order for V8 hidden class stability
+    const merged = Object.create(null);
+    for (const key of this._columnNames) {
+      // Use prototypeless object for stable prototype, prevents hidden class deopt
+      merged[key] = this.fields[key];
+    }
+    for (const key of extensionKeys) {
+      merged[key] = extension[key];
+    }
+
+    // Return new LogSchema instance
+    return new LogSchema(merged);
+  }
+
+  /**
+   * Check if this is a LogSchema instance
+   *
+   * Used for type guards and instanceof checks
+   */
+  static isLogSchema(value: unknown): value is LogSchema {
+    return value instanceof LogSchema;
+  }
+}
+
+/**
+ * Type guard to check if a value is a LogSchema instance
+ *
+ * @param value - Value to check
+ * @returns True if value is a LogSchema instance
+ */
+export function isLogSchema(value: unknown): value is LogSchema {
+  return LogSchema.isLogSchema(value);
+}