selaws 0.0.0-stage → 0.1.0

package/src/internal/promise-like.ts

@@ -0,0 +1,32 @@
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+type BroadFunction = FunctionConstructor["prototype"];
+
+type HasCallableThen<T> = T extends object
+  ? "then" extends keyof T
+    ? Extract<T["then"], BroadFunction> extends never
+      ? false
+      : true
+    : false
+  : false;
+
+export type NotPromiseLike<T> =
+  IsAny<T> extends true
+    ? T
+    : true extends (T extends unknown ? HasCallableThen<T> : never)
+      ? never
+      : T;
+
+export const isPromiseLike = (value: unknown): value is PromiseLike<unknown> => {
+  if ((typeof value !== "object" && typeof value !== "function") || value === null) {
+    return false;
+  }
+
+  return typeof (value as { readonly then?: unknown }).then === "function";
+};
+
+export const assertNotPromiseLike = (value: unknown, message: string): void => {
+  if (isPromiseLike(value)) {
+    throw new TypeError(message);
+  }
+};

package/src/internal/scalar.ts

@@ -0,0 +1,43 @@
+/** Immutable scalar carriers that can hold Selaws phantom meaning. */
+export type Scalar = string | number | bigint | boolean | symbol;
+
+export type Token = string | symbol;
+
+type IsUnion<T, Whole = T> = T extends Whole
+  ? [Whole] extends [T]
+    ? false
+    : true
+  : never;
+
+// An empty record is assignable to broad, patterned, and branded key spaces,
+// but not to one concrete string or unique-symbol key.
+type SingleToken<Key extends Token> =
+  true extends IsUnion<Key>
+    ? never
+    : Record<never, never> extends Record<Key, never>
+      ? never
+      : Key;
+
+type SingletonSymbolMembers<Key extends symbol> = Key extends unknown
+  ? SingleToken<Key>
+  : never;
+
+export type NarrowSymbolSet<Key extends symbol> = [Key] extends [
+  SingletonSymbolMembers<Key>,
+]
+  ? Key
+  : never;
+
+export type SingleSymbol<Key extends symbol> = SingleToken<Key>;
+export type SingleName<Name extends string> = SingleToken<Name>;
+
+export const isString = (value: unknown): value is string => typeof value === "string";
+
+export const isNumber = (value: unknown): value is number => typeof value === "number";
+
+export const isBigint = (value: unknown): value is bigint => typeof value === "bigint";
+
+export const isBoolean = (value: unknown): value is boolean =>
+  typeof value === "boolean";
+
+export const isSymbol = (value: unknown): value is symbol => typeof value === "symbol";

package/src/option.ts

@@ -0,0 +1,214 @@
+import type { CallbackResult } from "./internal/callback.js";
+import { assertNotPromiseLike, type NotPromiseLike } from "./internal/promise-like.js";
+
+/** A present Option value. */
+export type Some<T> = Readonly<{
+  some: true;
+  value: T;
+}>;
+
+/** Reasonless absence. */
+export type None = Readonly<{
+  some: false;
+}>;
+
+/** Explicit presence or absence. */
+export type Option<T> = Some<T> | None;
+
+/** Extracts the present value type from an Option union. */
+export type OptionValue<O> = O extends Some<infer T> ? T : never;
+
+type OptionValues<O extends readonly Option<unknown>[]> = {
+  [K in keyof O]: OptionValue<O[K]>;
+};
+
+type SynchronousReturn<T> = [T] extends [NotPromiseLike<T>] ? unknown : never;
+
+type IsMutableArray<Value> = Value extends unknown[] ? true : false;
+
+type StableArrayInput<Value extends readonly unknown[]> =
+  true extends IsMutableArray<Value> ? never : unknown;
+
+/** Constructs a present Option value. */
+export const some = <T>(value: T): Option<T> => ({
+  some: true,
+  value,
+});
+
+/** Constructs reasonless absence. */
+export const none = (): Option<never> => ({
+  some: false,
+});
+
+/** Narrows an Option to Some. */
+export const isSome = <T>(option: Option<T>): option is Some<T> => option.some;
+
+/** Narrows an Option to None. */
+export const isNone = <T>(option: Option<T>): option is None => !option.some;
+
+/** Eliminates an Option under the shared Match law. */
+export const match = <
+  T,
+  Some extends (this: void, value: NoInfer<T>) => unknown,
+  None extends (this: void) => unknown,
+>(
+  option: Option<T>,
+  arms: Readonly<{
+    some: Some;
+    none: None;
+  }>,
+): CallbackResult<Some> | CallbackResult<None> => {
+  if (option.some) {
+    const selected = arms.some;
+    return selected(option.value) as CallbackResult<Some>;
+  }
+
+  const selected = arms.none;
+  return selected() as CallbackResult<None>;
+};
+
+/** Transforms the Some value and preserves None. */
+export const map = <T, U>(option: Option<T>, transform: (value: T) => U): Option<U> =>
+  option.some ? some(transform(option.value)) : option;
+
+/** Sequences an Option-producing computation when a value is present. */
+export const andThen = <T, U>(
+  option: Option<T>,
+  next: (value: T) => Option<U>,
+): Option<U> => (option.some ? next(option.value) : option);
+
+/** Lazily provides another Option when the input is None. */
+export const orElse = <T, U>(
+  option: Option<T>,
+  fallback: () => Option<U>,
+): Option<T | U> => (option.some ? option : fallback());
+
+/** Removes one explicit nested Option layer. */
+export const flatten = <T>(option: Option<Option<T>>): Option<T> =>
+  option.some ? option.value : option;
+
+/** Retains Some when a type-guard predicate accepts its value. */
+export function filter<T, U extends T>(
+  option: Option<T>,
+  predicate: (value: T) => value is U,
+): Option<U>;
+
+/** Retains Some when the predicate accepts its value. */
+export function filter<T>(
+  option: Option<T>,
+  predicate: (value: T) => boolean,
+): Option<T>;
+
+export function filter<T>(
+  option: Option<T>,
+  predicate: (value: T) => boolean,
+): Option<T> {
+  if (!option.some) {
+    return option;
+  }
+  return predicate(option.value) ? option : none();
+}
+
+/** Synchronously observes Some and returns the original Option. */
+export const inspect = <T, R>(
+  option: Option<T>,
+  observe: ((value: T) => R) & SynchronousReturn<R>,
+): Option<T> => {
+  if (option.some) {
+    const completion = observe(option.value);
+    assertNotPromiseLike(
+      completion,
+      "Option.inspect() expects a synchronous observer.",
+    );
+  }
+  return option;
+};
+
+/** Returns the Some value or an eager fallback. */
+export const unwrapOr = <T, U>(option: Option<T>, fallback: U): T | U =>
+  option.some ? option.value : fallback;
+
+/** Returns the Some value or evaluates a lazy fallback. */
+export const unwrapOrElse = <T, U>(option: Option<T>, fallback: () => U): T | U =>
+  option.some ? option.value : fallback();
+
+/**
+ * Combines already-materialized Options.
+ *
+ * All Some values produce a position-preserving tuple; any None produces None.
+ */
+export const all = <const O extends readonly Option<unknown>[]>(
+  options: O & StableArrayInput<O>,
+): Option<OptionValues<O>> => {
+  const values: unknown[] = [];
+  const length = options.length;
+
+  for (let index = 0; index < length; index += 1) {
+    const option = options[index] as Option<unknown>;
+    if (!option.some) {
+      return none();
+    }
+    values.push(option.value);
+  }
+
+  return some(values as OptionValues<O>);
+};
+
+/** Maps exactly undefined to None and every other value to Some. */
+export const fromUndefined = <T>(value: T): Option<Exclude<T, undefined>> =>
+  value === undefined ? none() : some(value as Exclude<T, undefined>);
+
+/** Maps null or undefined to None and every other value to Some. */
+export const fromNullable = <T>(value: T): Option<NonNullable<T>> =>
+  value === undefined || value === null ? none() : some(value as NonNullable<T>);
+
+/** Maps None to undefined and returns the Some value unchanged. */
+export const toUndefined = <T>(option: Option<T>): T | undefined =>
+  option.some ? option.value : undefined;
+
+/** Maps None to null and returns the Some value unchanged. */
+export const toNullable = <T>(option: Option<T>): T | null =>
+  option.some ? option.value : null;
+
+type OptionFacade = Readonly<{
+  all: typeof all;
+  andThen: typeof andThen;
+  filter: typeof filter;
+  flatten: typeof flatten;
+  fromNullable: typeof fromNullable;
+  fromUndefined: typeof fromUndefined;
+  inspect: typeof inspect;
+  isNone: typeof isNone;
+  isSome: typeof isSome;
+  map: typeof map;
+  match: typeof match;
+  none: typeof none;
+  orElse: typeof orElse;
+  some: typeof some;
+  toNullable: typeof toNullable;
+  toUndefined: typeof toUndefined;
+  unwrapOr: typeof unwrapOr;
+  unwrapOrElse: typeof unwrapOrElse;
+}>;
+
+/** Facade for Option construction, transformation, elimination, and collection. */
+export const Option: OptionFacade = {
+  all,
+  andThen,
+  filter,
+  flatten,
+  fromNullable,
+  fromUndefined,
+  inspect,
+  isNone,
+  isSome,
+  map,
+  match,
+  none,
+  orElse,
+  some,
+  toNullable,
+  toUndefined,
+  unwrapOr,
+  unwrapOrElse,
+};

package/src/protocol.ts

@@ -0,0 +1,174 @@
+import type { Scalar } from "./internal/scalar.js";
+
+/** Scalar identifiers used as Protocol states. */
+export type State = Scalar;
+
+/** Scalar identifiers used to distinguish transitions. */
+export type Label = Scalar;
+
+/** One admissible labeled transition. */
+export type Transition<
+  From extends State = State,
+  Via extends Label = Label,
+  To extends State = State,
+> = readonly [from: From, label: Via, to: To];
+
+type TransitionUnion<Transitions extends readonly Transition[]> = Transitions[number];
+
+type SourceOf<One> = One extends readonly [infer From extends State, Label, State]
+  ? From
+  : never;
+
+type LabelOf<One> = One extends readonly [State, infer Via extends Label, State]
+  ? Via
+  : never;
+
+type TargetOf<One> = One extends readonly [State, Label, infer To extends State]
+  ? To
+  : never;
+
+/** All state identifiers that occur as a source or target. */
+export type States<Transitions extends readonly Transition[]> =
+  | SourceOf<TransitionUnion<Transitions>>
+  | TargetOf<TransitionUnion<Transitions>>;
+
+/** All transition labels that occur in a declaration. */
+export type Labels<Transitions extends readonly Transition[]> = LabelOf<
+  TransitionUnion<Transitions>
+>;
+
+type NextFrom<One, From extends State, Via extends Label> = One extends readonly [
+  infer Source extends State,
+  infer EdgeLabel extends Label,
+  infer To extends State,
+]
+  ? [Source & From] extends [never]
+    ? never
+    : [EdgeLabel & Via] extends [never]
+      ? never
+      : To
+  : never;
+
+/** The statically admissible targets for one source state and transition label. */
+export type Next<
+  Transitions extends readonly Transition[],
+  From extends States<Transitions>,
+  Via extends Labels<Transitions>,
+> = NextFrom<TransitionUnion<Transitions>, From, Via>;
+
+type IsMutableArray<Value> = Value extends unknown[] ? true : false;
+
+type ClosedTransitions<Transitions extends readonly Transition[]> =
+  true extends IsMutableArray<Transitions>
+    ? never
+    : true extends IsMutableArray<Transitions[number]>
+      ? never
+      : Transitions;
+
+/** Runtime membership for one immutable labeled transition relation. */
+export type Protocol<Transitions extends readonly Transition[]> = Readonly<{
+  allows<
+    From extends States<Transitions>,
+    Via extends Labels<Transitions>,
+    To extends States<Transitions>,
+  >(from: From, label: Via, to: To): boolean;
+}>;
+
+const isScalarIdentifier = (value: unknown): value is Scalar => {
+  switch (typeof value) {
+    case "string":
+    case "number":
+    case "bigint":
+    case "boolean":
+    case "symbol":
+      return true;
+    default:
+      return false;
+  }
+};
+
+/**
+ * Defines one immutable admissible labeled transition relation.
+ *
+ * The runtime relation snapshots the supplied triples and uses SameValueZero
+ * equality through Map and Set.
+ */
+export const define = <const Transitions extends readonly Transition[]>(
+  transitions: Transitions &
+    (ClosedTransitions<Transitions> extends never ? never : unknown),
+): Protocol<Transitions> => {
+  if (!Array.isArray(transitions)) {
+    throw new TypeError("Protocol declarations must be arrays.");
+  }
+
+  const relation = new Map<State, Map<Label, Set<State>>>();
+
+  const length = transitions.length;
+
+  for (let index = 0; index < length; index += 1) {
+    if (!Object.hasOwn(transitions, index)) {
+      throw new TypeError("Protocol declarations must contain own transition entries.");
+    }
+
+    const transition = transitions[index] as unknown;
+
+    if (
+      !Array.isArray(transition) ||
+      transition.length !== 3 ||
+      !Object.hasOwn(transition, 0) ||
+      !Object.hasOwn(transition, 1) ||
+      !Object.hasOwn(transition, 2)
+    ) {
+      throw new TypeError(
+        "Protocol transitions must be own [from, label, to] triples.",
+      );
+    }
+
+    const from = transition[0];
+    const label = transition[1];
+    const to = transition[2];
+
+    if (
+      !isScalarIdentifier(from) ||
+      !isScalarIdentifier(label) ||
+      !isScalarIdentifier(to)
+    ) {
+      throw new TypeError("Protocol states and labels must be scalar identifiers.");
+    }
+
+    let labels = relation.get(from);
+
+    if (labels === undefined) {
+      labels = new Map<Label, Set<State>>();
+      relation.set(from, labels);
+    }
+
+    let targets = labels.get(label);
+
+    if (targets === undefined) {
+      targets = new Set<State>();
+      labels.set(label, targets);
+    }
+
+    targets.add(to);
+  }
+
+  return Object.freeze({
+    allows<
+      From extends States<Transitions>,
+      Via extends Labels<Transitions>,
+      To extends States<Transitions>,
+    >(from: From, label: Via, to: To): boolean {
+      return relation.get(from)?.get(label)?.has(to) ?? false;
+    },
+  });
+};
+
+type ProtocolFacade = Readonly<{
+  define: typeof define;
+}>;
+
+/** Admissible labeled transition relations. */
+export const Protocol: ProtocolFacade = {
+  define,
+};

package/src/result/capture.ts

@@ -0,0 +1,209 @@
+import { assertNotPromiseLike, type NotPromiseLike } from "../internal/promise-like.js";
+import { err, ok, type Result } from "./core.js";
+
+type SyncPrimitive = string | number | boolean | bigint | symbol | null | undefined;
+
+type NonThenableObject = object & {
+  readonly then?: never;
+};
+
+type OverloadUnion<Callable, Partial = unknown> = Callable extends (
+  this: infer This,
+  ...args: infer Args
+) => infer Return
+  ? Partial extends Callable
+    ? never
+    :
+        | OverloadUnion<
+            Partial & Callable,
+            Partial & ((this: This, ...args: Args) => Return)
+          >
+        | ((this: This, ...args: Args) => Return)
+  : never;
+
+type IsUnion<T, Whole = T> = T extends unknown
+  ? [Whole] extends [T]
+    ? false
+    : true
+  : never;
+
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (
+  value: infer Intersection,
+) => void
+  ? Intersection
+  : never;
+
+type HasAsyncOverload<Callable> = true extends (
+  OverloadUnion<Callable> extends infer One
+    ? One extends (...args: never[]) => infer Return
+      ? [Return] extends [NotPromiseLike<Return>]
+        ? false
+        : true
+      : never
+    : never
+)
+  ? true
+  : false;
+
+type HasNonPromiseOverload<Callable> = true extends (
+  OverloadUnion<Callable> extends infer One
+    ? One extends (...args: never[]) => infer Return
+      ? [Return] extends [PromiseLike<unknown>]
+        ? false
+        : true
+      : never
+    : never
+)
+  ? true
+  : false;
+
+type SyncWrappedOne<Callable, E> = Callable extends (
+  this: infer This,
+  ...args: infer Args
+) => infer Return
+  ? (this: This, ...args: Args) => Result<Return, E>
+  : never;
+
+type SyncWrappedOverloads<Callable, E> = UnionToIntersection<
+  OverloadUnion<Callable> extends infer One
+    ? One extends unknown
+      ? SyncWrappedOne<One, E>
+      : never
+    : never
+>;
+
+type AsyncWrappedOne<Callable, E> = Callable extends (
+  this: infer This,
+  ...args: infer Args
+) => infer Return
+  ? (this: This, ...args: Args) => Promise<Result<Awaited<Return>, E>>
+  : never;
+
+type AsyncWrappedOverloads<Callable, E> = UnionToIntersection<
+  OverloadUnion<Callable> extends infer One
+    ? One extends unknown
+      ? AsyncWrappedOne<One, E>
+      : never
+    : never
+>;
+
+const attemptRuntime = <T, E>(
+  read: () => T,
+  mapThrown: (caught: unknown) => E,
+): Result<T, E> => {
+  let value: T;
+
+  try {
+    value = read();
+  } catch (caught) {
+    return err(mapThrown(caught));
+  }
+
+  assertNotPromiseLike(value, "attempt() expects a synchronous thunk.");
+  return ok(value);
+};
+
+/**
+ * Captures one synchronous invocation boundary as Result.
+ *
+ * Thrown values are mapped from unknown into the caller's recoverable error
+ * type. Promise-like returns are rejected as a sync-boundary contract error.
+ * A thrown mapper remains an abrupt JavaScript completion.
+ */
+export function attempt<T extends SyncPrimitive, E>(
+  read: () => T,
+  mapThrown: (caught: unknown) => E,
+): Result<T, E>;
+
+export function attempt<T extends NonThenableObject, E>(
+  read: () => T,
+  mapThrown: (caught: unknown) => E,
+): Result<T, E>;
+
+export function attempt<T, E>(
+  read: () => NotPromiseLike<T>,
+  mapThrown: (caught: unknown) => E,
+): Result<T, E>;
+
+export function attempt<T, E>(
+  read: () => T,
+  mapThrown: (caught: unknown) => E,
+): Result<T, E> {
+  return attemptRuntime(read, mapThrown);
+}
+
+/**
+ * Captures synchronous invocation plus Promise rejection as Result.
+ *
+ * The returned Promise resolves to Result; the mapper defines the recoverable
+ * error vocabulary for both abrupt paths.
+ */
+export const attemptAsync = async <T, E>(
+  read: () => PromiseLike<T>,
+  mapThrown: (caught: unknown) => E,
+): Promise<Result<Awaited<T>, E>> => {
+  try {
+    return ok(await read());
+  } catch (caught) {
+    return err(mapThrown(caught));
+  }
+};
+
+/** Wraps a synchronous function with the attempt boundary while preserving this and arguments. */
+export function wrap<Callable extends (...args: never[]) => unknown, E>(
+  read: Callable &
+    (true extends IsUnion<Callable> ? never : unknown) &
+    (true extends IsUnion<OverloadUnion<Callable>> ? unknown : never) &
+    (HasAsyncOverload<Callable> extends false ? unknown : never),
+  mapThrown: (caught: unknown) => E,
+): SyncWrappedOverloads<Callable, E>;
+
+export function wrap<This, Args extends unknown[], T extends SyncPrimitive, E>(
+  read: (this: This, ...args: Args) => T,
+  mapThrown: (caught: unknown) => E,
+): (this: This, ...args: Args) => Result<T, E>;
+
+export function wrap<This, Args extends unknown[], T extends NonThenableObject, E>(
+  read: (this: This, ...args: Args) => T,
+  mapThrown: (caught: unknown) => E,
+): (this: This, ...args: Args) => Result<T, E>;
+
+export function wrap<This, Args extends unknown[], T, E>(
+  read: (this: This, ...args: Args) => NotPromiseLike<T>,
+  mapThrown: (caught: unknown) => E,
+): (this: This, ...args: Args) => Result<T, E>;
+
+export function wrap<This, Args extends unknown[], T, E>(
+  read: (this: This, ...args: Args) => T,
+  mapThrown: (caught: unknown) => E,
+): (this: This, ...args: Args) => Result<T, E> {
+  return function wrapped(this: This, ...args: Args): Result<T, E> {
+    return attemptRuntime(() => Reflect.apply(read, this, args), mapThrown);
+  };
+}
+
+/** Wraps an async function with the attemptAsync boundary while preserving this and arguments. */
+export function wrapAsync<Callable extends (...args: never[]) => unknown, E>(
+  read: Callable &
+    (true extends IsUnion<Callable> ? never : unknown) &
+    (true extends IsUnion<OverloadUnion<Callable>> ? unknown : never) &
+    (HasNonPromiseOverload<Callable> extends false ? unknown : never),
+  mapThrown: (caught: unknown) => E,
+): AsyncWrappedOverloads<Callable, E>;
+
+export function wrapAsync<This, Args extends unknown[], T, E>(
+  read: (this: This, ...args: Args) => PromiseLike<T>,
+  mapThrown: (caught: unknown) => E,
+): (this: This, ...args: Args) => Promise<Result<Awaited<T>, E>>;
+
+export function wrapAsync<This, Args extends unknown[], T, E>(
+  read: (this: This, ...args: Args) => PromiseLike<T>,
+  mapThrown: (caught: unknown) => E,
+): (this: This, ...args: Args) => Promise<Result<Awaited<T>, E>> {
+  return function wrappedAsync(
+    this: This,
+    ...args: Args
+  ): Promise<Result<Awaited<T>, E>> {
+    return attemptAsync(() => Reflect.apply(read, this, args), mapThrown);
+  };
+}