nalloc 0.0.1

package/src/__tests__/result.types.ts

@@ -0,0 +1,249 @@
+import { assert, type Not, type Equals } from 'tsafe';
+import {
+  isOk,
+  isErr,
+  map,
+  mapErr,
+  flatMap,
+  bimap,
+  unwrap,
+  unwrapErr,
+  unwrapOr,
+  unwrapOrElse,
+  expect,
+  expectErr,
+  and,
+  or,
+  orElse,
+  flatten,
+  match,
+  partition,
+  collect,
+  collectAll,
+  transpose,
+  isOkAnd,
+  isErrAnd,
+  of,
+  ofAsync,
+  tryCatch,
+  tryAsync,
+  fromPromise,
+  unwrapOrReturn,
+  assertOk,
+  assertErr,
+  all,
+  any,
+  partitionAsync
+} from '../result.js';
+import { Result, Ok, Err, ok, err, Option, type InferErr } from '../types.js';
+
+const okValue = ok<number>(42);
+assert<Equals<typeof okValue, Ok<number>>>;
+assert<Not<Equals<typeof okValue, Err<any>>>>;
+
+const okValue2 = ok<number>(5);
+assert<Equals<typeof okValue2, Ok<number>>>;
+
+const errValue = err("error");
+assert<Equals<typeof errValue, Err<string>>>;
+assert<Not<Equals<typeof errValue, Ok<any>>>>;
+
+const errValue2 = err<number>(404);
+assert<Equals<typeof errValue2, Err<number>>>;
+
+const result: Result<number, string> = Math.random() > 0 ? ok(42) : err("error");
+if (isOk(result)) {
+  assert<Equals<typeof result, Ok<number>>>;
+  const value: number = result;
+} else {
+  assert<Equals<typeof result, Err<string>>>;
+  const error: string = result.error;
+}
+
+const knownOk = ok(123);
+const isOkResult = isOk(knownOk);
+assert<Equals<typeof isOkResult, true>>;
+assert<Not<Equals<typeof isOkResult, false>>>;
+assert<Not<Equals<typeof isOkResult, boolean>>>;
+
+const knownErr = err("error");
+const isErrResult = isErr(knownErr);
+assert<Equals<typeof isErrResult, true>>;
+assert<Not<Equals<typeof isErrResult, false>>>;
+assert<Not<Equals<typeof isErrResult, boolean>>>;
+
+const isOkOnErr = isOk(knownErr);
+assert<Equals<typeof isOkOnErr, false>>;
+assert<Not<Equals<typeof isOkOnErr, true>>>;
+
+const isErrOnOk = isErr(knownOk);
+assert<Equals<typeof isErrOnOk, false>>;
+assert<Not<Equals<typeof isErrOnOk, true>>>;
+
+const mapped = map(ok<number>(5) as Result<number, never>, x => x * 2);
+assert<Equals<typeof mapped, Result<number, never>>>;
+
+const mappedErr = map(err<string>("error") as Result<number, string>, (x: number) => x * 2);
+assert<Equals<typeof mappedErr, Result<number, string>>>;
+
+const errorMapped = mapErr(err<string>("error") as Result<never, string>, e => e.length);
+// errorMapped has type Result<never, number>
+
+const errorMappedOk = mapErr(ok<number>(42) as Result<number, string>, e => e.length);
+assert<Equals<typeof errorMappedOk, Result<number, number>>>;
+
+const chained = flatMap(ok<number>(5) as Result<number, string>, x => 
+  x > 0 ? ok(x * 2) : err("negative")
+);
+assert<Equals<typeof chained, Result<number, string>>>;
+
+const flatMapped = flatMap(ok<number>(5) as Result<number, string>, x => ok(x.toString()));
+assert<Equals<typeof flatMapped, Result<string, string>>>;
+
+const bimapped = bimap(
+  result,
+  v => v.toString(),
+  e => e.length
+);
+assert<Equals<typeof bimapped, Result<string, number>>>;
+
+const andResult = and(ok<number>(1) as Result<number, string>, ok<number>(2) as Result<number, string>);
+assert<Equals<typeof andResult, Result<number, string>>>;
+
+const orResult = or(err<string>("error") as Result<number, string>, ok<number>(42) as Result<number, boolean>);
+assert<Equals<typeof orResult, Result<number, boolean>>>;
+
+const orElseResult = orElse(err<string>("error") as Result<number, string>, e => ok<number>(e.length) as Result<number, number>);
+assert<Equals<typeof orElseResult, Result<number, number>>>;
+
+const numErr: Result<string, number> = err(404);
+const strErr: Result<string, string> = err("not found");
+assert<Not<Equals<typeof numErr, typeof strErr>>>;
+
+const okNum: Ok<number> = ok(100);
+const plainNum: number = okNum;
+assert<Equals<typeof plainNum, number>>;
+
+const nested: Result<Result<number, string>, Error> = ok(ok(42));
+const flattened = flatten(nested as Result<Result<number, string>, string>);
+assert<Equals<typeof flattened, Result<number, string>>>;
+
+
+const matchResult = match(
+  result,
+  v => v.toString(),
+  e => e,
+);
+assert<Equals<typeof matchResult, string>>;
+
+const results: Result<number, string>[] = [ok(1), err("error"), ok(2)];
+const [oks, errs] = partition(results);
+assert<Equals<typeof oks, number[]>>;
+assert<Equals<typeof errs, string[]>>;
+
+const collected = collect(results);
+assert<Equals<typeof collected, Result<number[], string>>>;
+
+const collectedAll = collectAll(results);
+assert<Equals<typeof collectedAll, Result<number[], string[]>>>;
+
+const transposed = transpose(ok(42 as Option<number>) as Result<Option<number>, string>);
+assert<Equals<typeof transposed, Option<Result<number, string>>>>;
+
+const isOkAndResult = isOkAnd(ok<number>(42) as Result<number, never>, x => x > 0);
+assert<Equals<typeof isOkAndResult, boolean>>;
+
+const isErrAndResult = isErrAnd(err<string>("error") as Result<never, string>, e => e.length > 0);
+assert<Equals<typeof isErrAndResult, boolean>>;
+
+const tryResult = of(() => {
+  if (Math.random() > 0.5) throw new Error("oops");
+  return 42;
+});
+assert<Equals<typeof tryResult, Result<number, unknown>>>;
+
+const tryResultTyped = of<number, Error>(() => {
+  if (Math.random() > 0.5) throw new Error("oops");
+  return 42;
+});
+assert<Equals<typeof tryResultTyped, Result<number, Error>>>;
+
+const asyncResult = ofAsync<number>(async () => {
+  return 42;
+});
+assert<Equals<typeof asyncResult, Promise<Result<number, unknown>>>>;
+
+
+
+const unwrapOrResult = unwrapOr(err<string>("error") as Result<number, string>, 42);
+assert<Equals<typeof unwrapOrResult, number>>;
+
+const unwrapOrElseResult = unwrapOrElse(err<string>("error") as Result<number, string>, e => e.length);
+assert<Equals<typeof unwrapOrElseResult, number>>;
+
+const complexResult: Result<{ id: number; name: string }, Error> = 
+  Math.random() > 0.5 
+    ? ok({ id: 1, name: "test" })
+    : err(new Error("failed"));
+
+if (isOk(complexResult)) {
+  assert<Equals<typeof complexResult, Ok<{ id: number; name: string }>>>;
+  const obj: { id: number; name: string } = complexResult;
+  const id: number = complexResult.id;
+  const name: string = complexResult.name;
+}
+
+if (isErr(complexResult)) {
+  // complexResult is narrowed to Err<Error> here
+  const error: Error = (complexResult as Err<Error>).error;
+}
+
+const okString: Result<string, never> = ok<string>("hello");
+const mappedString = map(okString, s => s.length);
+// mappedString is Result<number, never>
+
+const errString: Result<never, string> = err<string>("error");
+const mappedErrString = mapErr(errString, s => s.length);
+// mappedErrString is Result<never, number>
+
+const tryCatchResult = tryCatch(() => 1);
+assert<Equals<typeof tryCatchResult, Result<number, unknown>>>;
+
+const tryCatchTyped = tryCatch<number, string>(() => {
+  throw new Error('boom');
+}, error => (error as Error).message);
+assert<Equals<typeof tryCatchTyped, Result<number, string>>>;
+
+const tryAsyncResult = tryAsync(async () => 1);
+assert<Equals<typeof tryAsyncResult, Promise<Result<number, unknown>>>>;
+
+const tryAsyncTyped = tryAsync<number, string>(async () => {
+  throw new Error('boom');
+}, error => (error as Error).message);
+assert<Equals<typeof tryAsyncTyped, Promise<Result<number, string>>>>;
+
+const fromPromiseResult = fromPromise(Promise.resolve(1));
+assert<Equals<typeof fromPromiseResult, Promise<Result<number, unknown>>>>;
+
+const unwrapFallback = unwrapOrReturn(ok(1) as Result<number, string>, () => 'fallback');
+assert<Equals<typeof unwrapFallback, number | string>>;
+
+declare const maybeResult: Result<number, string>;
+assertOk(maybeResult);
+const narrowedOk: Ok<number> = maybeResult;
+
+declare const maybeErr: Result<number, string>;
+assertErr(maybeErr);
+const narrowedErr: Err<string> = maybeErr;
+
+const allResult = all([ok(1), ok(2)]);
+assert<Equals<typeof allResult, Result<number[], unknown>>>;
+
+const anyResult = any([err('a'), ok(3)]);
+assert<Equals<typeof anyResult, Result<number, string[]>>>;
+
+const partitionAsyncResult = partitionAsync([Promise.resolve(ok(1)), Promise.resolve(err('a'))]);
+assert<Equals<typeof partitionAsyncResult, Promise<[number[], string[]]>>>;
+
+type ExtractedErr = InferErr<Result<number, string>>;
+assert<Equals<ExtractedErr, Err<string>>>;

package/src/__tests__/safe.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import * as safe from '../safe.js';
+import { err } from '../types.js';
+
+describe('nalloc/safe exports', () => {
+  it('exports match nalloc', () => {
+    expect(safe.some).toBeDefined();
+    expect('none' in safe).toBe(true);
+    expect(safe.ok).toBeDefined();
+    expect(safe.err).toBeDefined();
+    expect(safe.Option).toBeDefined();
+    expect(safe.Result).toBeDefined();
+  });
+
+  it('safe some throws on null/undefined', () => {
+    expect(() => safe.some(null as any)).toThrow();
+    expect(() => safe.some(undefined as any)).toThrow();
+  });
+
+  it('safe ok throws on Err', () => {
+    const error = err('test');
+    expect(() => safe.ok(error)).toThrow();
+  });
+});

package/src/__tests__/tooling.ts

@@ -0,0 +1,86 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { ok, err, none, some } from '../types.js';
+import {
+  expectOk,
+  expectErr,
+  expectSome,
+  expectNone,
+  extendExpect,
+} from '../testing.js';
+import {
+  formatOption,
+  formatResult,
+  inspectOption,
+  inspectResult,
+  logOption,
+  logResult,
+  toJSONOption,
+  toJSONResult,
+} from '../devtools.js';
+
+describe('testing utilities', () => {
+  beforeAll(() => {
+    extendExpect(expect as any);
+  });
+
+  it('expectOk returns Ok payload or throws', () => {
+    const value = expectOk(ok(5));
+    expect(value).toBe(5);
+    expect(() => expectOk(err('nope'))).toThrow(/Err/);
+  });
+
+  it('expectErr returns error payload or throws', () => {
+    const error = expectErr(err('boom'));
+    expect(error).toBe('boom');
+    expect(() => expectErr(ok(1))).toThrow(/Ok/);
+  });
+
+  it('expectSome / expectNone validate Option', () => {
+    const value = expectSome(some(3));
+    expect(value).toBe(3);
+    expect(() => expectSome(none)).toThrow(/None/);
+    expect(() => expectNone(some(2))).toThrow(/Some/);
+  });
+
+  it('adds matchers to expect', () => {
+    expect(ok(1)).toBeOk();
+    expect(err('oops')).toBeErr();
+    expect(some(4)).toBeSome();
+    expect(none).toBeNone();
+  });
+});
+
+describe('devtools utilities', () => {
+  it('formats option', () => {
+    expect(formatOption(some('x'))).toBe('Some(x)');
+    expect(formatOption(none)).toBe('None');
+  });
+
+  it('formats result', () => {
+    expect(formatResult(ok(7))).toBe('Ok(7)');
+    expect(formatResult(err('fail'))).toBe('Err(fail)');
+  });
+
+  it('inspects option/result', () => {
+    expect(inspectOption(some('x'))).toEqual({ kind: 'some', value: 'x' });
+    expect(inspectOption(none)).toEqual({ kind: 'none' });
+    expect(inspectResult(ok('y'))).toEqual({ status: 'ok', value: 'y' });
+    expect(inspectResult(err('fail'))).toEqual({ status: 'err', error: 'fail' });
+  });
+
+  it('logs option/result via logger', () => {
+    const calls: unknown[][] = [];
+    const logger = (...args: unknown[]) => calls.push(args);
+    logOption(some(1), logger);
+    logResult(err('fail'), logger);
+    expect(calls[0]).toEqual(['Some(1)']);
+    expect(calls[1]).toEqual(['Err', 'fail']);
+  });
+
+  it('serialises option/result to JSON friendly data', () => {
+    expect(toJSONOption(some(2))).toEqual({ kind: 'some', value: 2 });
+    expect(toJSONOption(none)).toEqual({ kind: 'none' });
+    expect(toJSONResult(ok(3))).toEqual({ status: 'ok', value: 3 });
+    expect(toJSONResult(err('fail'))).toEqual({ status: 'err', error: 'fail' });
+  });
+});

package/src/__tests__/unsafe.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import * as unsafe from '../unsafe.js';
+import { err } from '../types.js';
+
+describe('nalloc/unsafe exports', () => {
+  it('exports match nalloc', () => {
+    expect(unsafe.some).toBeDefined();
+    expect('none' in unsafe).toBe(true);
+    expect(unsafe.ok).toBeDefined();
+    expect(unsafe.err).toBeDefined();
+    expect(unsafe.Option).toBeDefined();
+    expect(unsafe.Result).toBeDefined();
+  });
+
+  it('unsafe some does not throw on null/undefined', () => {
+    expect(() => unsafe.some(null)).not.toThrow();
+    expect(() => unsafe.some(undefined)).not.toThrow();
+  });
+
+  it('unsafe ok does not throw on Err', () => {
+    const error = err('test');
+    expect(() => unsafe.ok(error)).not.toThrow();
+  });
+});

package/src/devtools.ts

@@ -0,0 +1,97 @@
+import { Option, Result, isSome, isOk } from './types.js';
+
+/** Logger function signature for custom logging. */
+type Logger = (message: string, ...args: unknown[]) => void;
+
+/**
+ * Formats an Option as a human-readable string.
+ * @param opt - The Option to format
+ * @returns "Some(value)" or "None"
+ * @example
+ * formatOption(42)        // "Some(42)"
+ * formatOption(null)      // "None"
+ * formatOption(undefined) // "None"
+ */
+export function formatOption<T>(opt: Option<T>): string {
+  return isSome(opt) ? `Some(${String(opt)})` : 'None';
+}
+
+/**
+ * Formats a Result as a human-readable string.
+ * For Err containing an Error, displays the error message.
+ * @param result - The Result to format
+ * @returns "Ok(value)" or "Err(error)"
+ * @example
+ * formatResult(42)                      // "Ok(42)"
+ * formatResult(err('fail'))             // "Err(fail)"
+ * formatResult(err(new Error('oops')))  // "Err(oops)"
+ */
+export function formatResult<T, E>(result: Result<T, E>): string {
+  if (isOk(result)) {
+    return `Ok(${String(result)})`;
+  }
+  const error = (result as { error: E }).error;
+  return `Err(${error instanceof Error ? error.message : String(error)})`;
+}
+
+/**
+ * Inspects an Option, returning a tagged object for debugging or serialization.
+ * @param opt - The Option to inspect
+ * @returns `{ kind: 'some', value: T }` or `{ kind: 'none' }`
+ * @example
+ * inspectOption(42)   // { kind: 'some', value: 42 }
+ * inspectOption(null) // { kind: 'none' }
+ */
+export function inspectOption<T>(opt: Option<T>) {
+  return isSome(opt) ? { kind: 'some' as const, value: opt } : { kind: 'none' as const };
+}
+
+/**
+ * Inspects a Result, returning a tagged object for debugging or serialization.
+ * @param result - The Result to inspect
+ * @returns `{ status: 'ok', value: T }` or `{ status: 'err', error: E }`
+ * @example
+ * inspectResult(42)           // { status: 'ok', value: 42 }
+ * inspectResult(err('fail'))  // { status: 'err', error: 'fail' }
+ */
+export function inspectResult<T, E>(result: Result<T, E>) {
+  return isOk(result) ? { status: 'ok' as const, value: result } : { status: 'err' as const, error: (result as { error: E }).error };
+}
+
+/**
+ * Logs an Option using the provided logger (defaults to console.log).
+ * @param opt - The Option to log
+ * @param logger - The logging function to use
+ * @example
+ * logOption(42)              // logs "Some(42)"
+ * logOption(null)            // logs "None"
+ * logOption(42, console.warn) // logs "Some(42)" as warning
+ */
+export function logOption<T>(opt: Option<T>, logger: Logger = console.log): void {
+  logger(formatOption(opt));
+}
+
+/**
+ * Logs a Result using the provided logger (defaults to console.log).
+ * Logs "Ok" with the value or "Err" with the error.
+ * @param result - The Result to log
+ * @param logger - The logging function to use
+ * @example
+ * logResult(42)              // logs "Ok", 42
+ * logResult(err('fail'))     // logs "Err", "fail"
+ * logResult(42, console.warn) // logs "Ok", 42 as warning
+ */
+export function logResult<T, E>(result: Result<T, E>, logger: Logger = console.log): void {
+  const tagged = inspectResult(result);
+  if (tagged.status === 'ok') {
+    logger(`Ok`, tagged.value);
+    return;
+  }
+  logger(`Err`, tagged.error);
+}
+
+/** Alias for inspectOption. Returns a JSON-serializable representation. */
+export const toJSONOption = inspectOption;
+
+/** Alias for inspectResult. Returns a JSON-serializable representation. */
+export const toJSONResult = inspectResult;

package/src/index.ts

@@ -0,0 +1,18 @@
+export { some, none, ok, 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';