nalloc 0.0.1

package/src/safe.ts

@@ -0,0 +1,58 @@
+import { some as someUnsafe, ok as okUnsafe, err, none, isErr } from './types.js';
+import type {
+  Some,
+  None,
+  Ok,
+  Err,
+  Option as OptionType,
+  OptionValue,
+  IsOption,
+  InferSome,
+  Result as ResultType,
+  ResultValue,
+  ResultErrorType,
+  IsResult,
+  InferErr,
+  ValueType,
+} from './types.js';
+
+export type { Some, None, Ok, Err, OptionType, OptionValue, IsOption, InferSome, ResultType, ResultValue, ResultErrorType, IsResult, InferErr };
+
+export { none, err };
+export * as Option from './option.js';
+export * as Result from './result.js';
+
+/**
+ * Creates a Some value with runtime validation.
+ * Throws if the value is null or undefined.
+ * @param value - The value to wrap (must be non-nullable)
+ * @returns The value typed as Some
+ * @throws {TypeError} If value is null or undefined
+ * @example
+ * some(42)        // Some(42)
+ * some(null)      // throws TypeError
+ * some(undefined) // throws TypeError
+ */
+export function some<T>(value: T): Some<ValueType<T>> {
+  if (value === null || value === undefined) {
+    throw new TypeError('some() requires a non-nullable value');
+  }
+  return someUnsafe(value as ValueType<T>);
+}
+
+/**
+ * Creates an Ok value with runtime validation.
+ * Throws if the value is an Err (prevents accidental double-wrapping).
+ * @param value - The success value
+ * @returns The value typed as Ok
+ * @throws {TypeError} If value is an Err
+ * @example
+ * ok(42)           // Ok(42)
+ * ok(err('fail'))  // throws TypeError
+ */
+export function ok<T>(value: T): Ok<T> {
+  if (isErr(value)) {
+    throw new TypeError('ok() cannot wrap an Err value');
+  }
+  return okUnsafe(value);
+}

package/src/testing.ts

@@ -0,0 +1,159 @@
+import { isOk, isErr, isSome, isNone, Result, Err, Option } from './types.js';
+import { formatOption, formatResult } from './devtools.js';
+
+/** Result shape returned by custom matchers. */
+type MatcherResult = { pass: boolean; message(): string };
+
+/**
+ * Asserts that a Result is Ok and returns the value.
+ * Throws if the Result is Err.
+ * @param result - The Result to check
+ * @param message - Optional custom error message
+ * @returns The Ok value
+ * @throws {Error} If the Result is Err
+ * @example
+ * expectOk(ok(42))        // returns 42
+ * expectOk(err('fail'))   // throws Error
+ */
+export function expectOk<T, E>(result: Result<T, E>, message?: string): T {
+  if (isOk(result)) {
+    return result;
+  }
+
+  const fallback = message ?? `Expected Ok(...) but received ${formatResult(result)}`;
+  throw new Error(fallback);
+}
+
+/**
+ * Asserts that a Result is Err and returns the error.
+ * Throws if the Result is Ok.
+ * @param result - The Result to check
+ * @param message - Optional custom error message
+ * @returns The error value
+ * @throws {Error} If the Result is Ok
+ * @example
+ * expectErr(err('fail'))  // returns 'fail'
+ * expectErr(ok(42))       // throws Error
+ */
+export function expectErr<T, E>(result: Result<T, E>, message?: string): E {
+  if (isErr(result)) {
+    return (result as Err<E>).error;
+  }
+
+  const fallback = message ?? `Expected Err(...) but received ${formatResult(result)}`;
+  throw new Error(fallback);
+}
+
+/**
+ * Asserts that an Option is Some and returns the value.
+ * Throws if the Option is None.
+ * @param opt - The Option to check
+ * @param message - Optional custom error message
+ * @returns The Some value
+ * @throws {Error} If the Option is None
+ * @example
+ * expectSome(42)   // returns 42
+ * expectSome(null) // throws Error
+ */
+export function expectSome<T>(opt: Option<T>, message?: string): T {
+  if (isSome(opt)) {
+    return opt;
+  }
+  const fallback = message ?? `Expected Some(...) but received ${formatOption(opt)}`;
+  throw new Error(fallback);
+}
+
+/**
+ * Asserts that an Option is None.
+ * Throws if the Option is Some.
+ * @param opt - The Option to check
+ * @param message - Optional custom error message
+ * @throws {Error} If the Option is Some
+ * @example
+ * expectNone(null) // succeeds
+ * expectNone(42)   // throws Error
+ */
+export function expectNone<T>(opt: Option<T>, message?: string): void {
+  if (isNone(opt)) {
+    return;
+  }
+  const fallback = message ?? `Expected None but received ${formatOption(opt)}`;
+  throw new Error(fallback);
+}
+
+const resultMatchers = {
+  toBeOk(this: unknown, received: Result<unknown, unknown>): MatcherResult {
+    const pass = isOk(received);
+    return {
+      pass,
+      message: () => (pass ? 'Result is Ok as expected.' : `Expected Ok(...) but received ${formatResult(received)}`),
+    };
+  },
+  toBeErr(this: unknown, received: Result<unknown, unknown>): MatcherResult {
+    const pass = isErr(received);
+    return {
+      pass,
+      message: () => (pass ? 'Result is Err as expected.' : `Expected Err(...) but received ${formatResult(received)}`),
+    };
+  },
+  toContainErr(this: unknown, received: Result<unknown, unknown>, expected: unknown): MatcherResult {
+    const pass = isErr(received) && (received as Err<unknown>).error === expected;
+    return {
+      pass,
+      message: () => {
+        if (pass) return `Err matched expected value ${String(expected)}.`;
+        return `Expected Err(${String(expected)}) but received ${formatResult(received)}`;
+      },
+    };
+  },
+};
+
+const optionMatchers = {
+  toBeSome(this: unknown, received: Option<unknown>): MatcherResult {
+    const pass = isSome(received);
+    return {
+      pass,
+      message: () => (pass ? 'Option is Some as expected.' : `Expected Some(...) but received ${formatOption(received)}`),
+    };
+  },
+  toBeNone(this: unknown, received: Option<unknown>): MatcherResult {
+    const pass = isNone(received);
+    return {
+      pass,
+      message: () => (pass ? 'Option is None as expected.' : `Expected None but received ${formatOption(received)}`),
+    };
+  },
+};
+
+/**
+ * Custom matchers for Jest/Vitest.
+ * Includes toBeOk, toBeErr, toContainErr, toBeSome, toBeNone.
+ * Use with expect.extend(matchers) or extendExpect(expect).
+ */
+export const matchers = {
+  ...resultMatchers,
+  ...optionMatchers,
+};
+
+/** Interface for test frameworks with an extend method (Jest, Vitest). */
+export type ExpectLike = {
+  extend(matchers: Record<string, (...args: any[]) => MatcherResult>): void;
+};
+
+/**
+ * Extends a test framework's expect with Option and Result matchers.
+ * @param expectLike - The expect object to extend (Jest/Vitest)
+ * @example
+ * import { expect } from 'vitest';
+ * import { extendExpect } from 'nalloc/testing';
+ * extendExpect(expect);
+ *
+ * // Now you can use:
+ * expect(result).toBeOk();
+ * expect(result).toBeErr();
+ * expect(option).toBeSome();
+ * expect(option).toBeNone();
+ */
+export function extendExpect(expectLike: ExpectLike): void {
+  expectLike.extend(matchers);
+}

package/src/types.ts

@@ -0,0 +1,201 @@
+/** Values that represent None (absence of a value). */
+export type NoneValueType = null | undefined | void;
+
+/** Widens literal types to their base types for better type inference. */
+export type Widen<T> = T extends string
+  ? string
+  : T extends number
+    ? number
+    : T extends boolean
+      ? boolean
+      : T extends bigint
+        ? bigint
+        : T extends symbol
+          ? symbol
+          : T;
+
+/** Widens never to unknown, otherwise preserves the type. */
+export type WidenNever<T> = [T] extends [never] ? unknown : T;
+
+/** Excludes None values from a type, leaving only valid Some values. */
+export type ValueType<T> = Exclude<T, NoneValueType>;
+
+export declare const SOME_BRAND: unique symbol;
+
+/** Represents a value that is present. The value itself is the Some - no wrapper object. */
+export type Some<T> = ValueType<T> & { readonly [SOME_BRAND]: true };
+
+/** Represents the absence of a value (null or undefined). */
+export type None = NoneValueType & { readonly [SOME_BRAND]: false };
+
+/** Constant representing None. Use this instead of null/undefined for clarity. */
+export const NONE = undefined as None;
+
+/** A value that may or may not be present. Some(T) is the value itself; None is null/undefined. */
+export type Option<T> = Some<ValueType<T>> | None;
+
+/** Extracts the value type from an Option type. */
+export type OptionValue<TOption> = TOption extends Option<infer TValue> ? TValue : never;
+
+/** Type predicate: true if T is an Option type. */
+export type IsOption<T> = T extends Option<any> ? true : false;
+
+/** Infers the Some type from a value, preserving the inner type. */
+export type InferSome<T> = T extends Some<infer TValue> ? Some<ValueType<TValue>> : never;
+
+/**
+ * Checks if an Option contains a value (is Some).
+ * @param opt - The Option to check
+ * @returns true if the Option is Some, false if None
+ * @example
+ * isSome(42)        // true
+ * isSome(null)      // false
+ * isSome(undefined) // false
+ */
+export function isSome<T>(opt: Some<T>): true;
+export function isSome(opt: None): false;
+export function isSome<T>(opt: unknown): opt is Some<T>;
+export function isSome(opt: unknown): boolean {
+  return opt !== null && opt !== undefined;
+}
+
+/**
+ * Checks if an Option is None (absent).
+ * @param opt - The Option to check
+ * @returns true if the Option is None, false if Some
+ * @example
+ * isNone(null)      // true
+ * isNone(undefined) // true
+ * isNone(42)        // false
+ */
+export function isNone<T>(opt: Some<T>): false;
+export function isNone(opt: None): true;
+export function isNone(opt: unknown): opt is None;
+export function isNone(opt: unknown): boolean {
+  return opt === null || opt === undefined;
+}
+
+/**
+ * Creates an Option from a nullable value. Returns None for null/undefined, Some otherwise.
+ * @param value - The value to wrap
+ * @returns Some(value) if value is non-null, None otherwise
+ * @example
+ * optionOf(42)        // Some(42)
+ * optionOf(null)      // None
+ * optionOf(undefined) // None
+ */
+export function optionOf(value: null): None;
+export function optionOf(value: undefined): None;
+export function optionOf<T>(value: T): T extends NoneValueType ? None : Some<T>;
+export function optionOf<T>(value: T): Option<T> {
+  return isNone(value as Option<T>) ? NONE : (value as Some<T>);
+}
+
+/**
+ * Creates a Some value. Does not validate - use safe.some() for validation.
+ * @param value - The value to wrap (must be non-null)
+ * @returns The value typed as Some
+ * @example
+ * some(42) // Some(42)
+ */
+export function some<T>(value: ValueType<T>): Some<ValueType<T>> {
+  return value as Some<ValueType<T>>;
+}
+
+/** Constant representing None. Alias for NONE. */
+export const none: None = NONE;
+
+declare const OK_BRAND: unique symbol;
+
+/** Represents a successful Result value. The value itself is the Ok - no wrapper object. */
+export type Ok<T> = T & { readonly [OK_BRAND]: true };
+
+const ERR_BRAND = Symbol.for('nalloc.ResultError');
+
+interface ResultErrorShape<E> {
+  readonly error: E;
+  readonly [ERR_BRAND]: true;
+}
+
+function ResultErrorCtor<E>(this: ResultErrorShape<E>, error: E): void {
+  (this as { error: E }).error = error;
+}
+(ResultErrorCtor.prototype as { [ERR_BRAND]: true })[ERR_BRAND] = true;
+
+/** The error wrapper type used internally. */
+export type ResultError<E> = ResultErrorShape<E>;
+
+function hasErrBrand(value: unknown): value is ResultError<unknown> {
+  return (value as Record<symbol, unknown>)?.[ERR_BRAND] === true;
+}
+
+/** Represents a failed Result containing an error. */
+export type Err<E> = ResultError<E>;
+
+/** A value that is either successful (Ok) or failed (Err). Ok is the value itself; Err wraps the error. */
+export type Result<T, E> = Ok<T> | Err<E>;
+
+/** Extracts the success value type from a Result type. */
+export type ResultValue<TResult> = TResult extends Result<infer TValue, any> ? TValue : never;
+
+/** Extracts the error type from a Result type. */
+export type ResultErrorType<TResult> = TResult extends Result<any, infer TError> ? TError : never;
+
+/** Type predicate: true if T is a Result type. */
+export type IsResult<T> = T extends Result<any, any> ? true : false;
+
+/** Infers the Err type from a value, preserving the error type. */
+export type InferErr<T> = T extends Err<infer TError> ? Err<TError> : never;
+
+/**
+ * Checks if a Result is Ok (successful).
+ * @param result - The Result to check
+ * @returns true if the Result is Ok, false if Err
+ * @example
+ * isOk(42)           // true (Ok value)
+ * isOk(err('fail'))  // false
+ */
+export function isOk<T>(result: Ok<T>): true;
+export function isOk<E>(result: Err<E>): false;
+export function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
+export function isOk<T, E>(result: Result<T, E>): boolean {
+  return !hasErrBrand(result);
+}
+
+/**
+ * Checks if a Result is Err (failed).
+ * @param result - The Result to check
+ * @returns true if the Result is Err, false if Ok
+ * @example
+ * isErr(err('fail')) // true
+ * isErr(42)          // false (Ok value)
+ */
+export function isErr<E>(result: Err<E>): true;
+export function isErr(result: Ok<any>): false;
+export function isErr<T, E>(result: Result<T, E>): result is Err<E>;
+export function isErr<T, E>(result: Result<T, E>): boolean {
+  return hasErrBrand(result);
+}
+
+/**
+ * Creates an Ok value. Does not validate - use safe.ok() for validation.
+ * @param value - The success value
+ * @returns The value typed as Ok
+ * @example
+ * ok(42) // Ok(42)
+ */
+export function ok<T>(value: T): Ok<T> {
+  return value as Ok<T>;
+}
+
+/**
+ * Creates an Err value wrapping an error.
+ * @param error - The error value
+ * @returns An Err containing the error
+ * @example
+ * err('something went wrong') // Err('something went wrong')
+ * err(new Error('failed'))    // Err(Error)
+ */
+export function err<E>(error: E): Err<E> {
+  return new (ResultErrorCtor as unknown as new (error: E) => Err<E>)(error);
+}

package/src/unsafe.ts

@@ -0,0 +1,47 @@
+import type { Some, Ok } from './types.js';
+export { none, err } from './types.js';
+export type {
+  Some,
+  None,
+  Ok,
+  Err,
+  Option as OptionType,
+  OptionValue,
+  IsOption,
+  InferSome,
+  Result as ResultType,
+  ResultValue,
+  ResultErrorType,
+  IsResult,
+  InferErr,
+} from './types.js';
+export * as Option from './option.js';
+export * as Result from './result.js';
+
+/**
+ * Creates a Some value without runtime validation.
+ * Use when you are certain the value is non-nullable.
+ * For validated creation, use safe.some() instead.
+ * @param value - The value to wrap (assumed non-nullable)
+ * @returns The value typed as Some
+ * @example
+ * some(42)   // Some(42)
+ * some(null) // Some(null) - no validation, may cause issues
+ */
+export function some<T>(value: T): Some<T> {
+  return value as unknown as Some<T>;
+}
+
+/**
+ * Creates an Ok value without runtime validation.
+ * Use when you are certain the value is not an Err.
+ * For validated creation, use safe.ok() instead.
+ * @param value - The success value (assumed not an Err)
+ * @returns The value typed as Ok
+ * @example
+ * ok(42)          // Ok(42)
+ * ok(err('fail')) // Ok(Err) - no validation, may cause issues
+ */
+export function ok<T>(value: T): Ok<T> {
+  return value as Ok<T>;
+}