selaws 0.0.0-stage → 0.1.0

package/docs/laws/variant.md

@@ -0,0 +1,251 @@
+# Variant law
+
+Variant represents one exact closed family of labeled alternatives.
+
+For one family declaration with case names `K` and payload assignment `P`:
+
+```text
+Variant(F) = sum over k in K of P(k)
+```
+
+A unit case has one nullary alternative. A payload case carries one value of its
+declared payload type.
+
+Use Variant when a domain owns a finite alternative vocabulary whose case name
+and payload type must stay correlated.
+
+```ts
+const Message = Variant.define("Message", [
+  ["quit", Variant.unit],
+  ["write", Variant.payload<string>()],
+]);
+
+type Message =
+  Variant.Value<typeof Message>;
+```
+
+## 1. Closed family
+
+One `Variant.define` call owns one finite readonly tuple of
+`[caseName, caseSpec]` entries. That tuple is the complete case universe for
+the family.
+
+The outer tuple and every case-entry pair must be readonly, its length must be
+statically concrete, and every case name must be one concrete string literal.
+Mutable tuples, broad arrays, optional/union entry sets, duplicate names, and
+patterned/broad string names do not define one exact closed family. Empty
+declarations are valid and produce an uninhabited Variant value type.
+
+Declaration order carries no meaning.
+
+The finite readonly tuple is part of the typed boundary. Ordinary record width
+subtyping can hide runtime properties behind a narrower static record type, so
+Variant derives the family from an exact tuple rather than record keys. Directly
+mutable declaration tuples are rejected. A readonly view over separately
+mutable backing data can still be invalidated through TypeScript's unsound
+aliasing and is governed by the trust model in
+[SEMANTICS.md](../SEMANTICS.md).
+
+Adding or removing a case changes the family declaration and therefore the
+family-level exhaustive handling obligation.
+
+## 2. Family identity
+
+A string family name gives package-copy-stable named identity. A bound
+`Symbol` gives declaration-owned identity.
+
+Named family values use the structural phantom key:
+
+```text
+~selaws.variant:<Name>
+```
+
+Declaration-owned families use the caller-owned symbol as the phantom property
+key.
+
+The phantom marker includes the Variant category, closed case-name universe,
+and case signatures. Case-name universes are exact; payload positions retain
+ordinary TypeScript structural variance.
+
+Duplicate compatible Selaws installations therefore agree on an identically
+declared named family, while distinct names and distinct caller-owned symbols
+remain separate families.
+
+## 3. Case formation
+
+`Variant.unit` declares a nullary case.
+
+`Variant.payload<T>()` declares a case carrying one `T`.
+
+These declaration markers are opaque, package-copy-stable sentinels; their
+runtime representation carries no domain payload.
+
+`Variant.define` produces one `make` constructor for every declared case.
+Formation preserves the selected case name and payload:
+
+```ts
+Message.make.quit();
+// { tag: "quit" }
+
+Message.make.write("hello");
+// { tag: "write", value: "hello" }
+```
+
+A unit case and a payload case remain distinct even when the payload type is
+`undefined` or `never`.
+
+## 4. Representation
+
+Variant values are ordinary transparent JavaScript objects.
+
+A unit case has the representation:
+
+```ts
+{ tag: caseName }
+```
+
+A payload case has the representation:
+
+```ts
+{ tag: caseName, value: payload }
+```
+
+The family phantom identity is static TypeScript information. Formation adds no
+runtime brand to the value.
+
+Constructed values are ordinary structural data. The family declaration and
+its `make` namespace are immutable; payload values themselves are not
+deep-frozen by Variant.
+
+## 5. Exhaustive elimination
+
+Variant family `match` conforms to the shared [Match law](./match.md). The
+Variant family owns the branch universe: one branch for every declared case,
+with the payload assignment defined by that family.
+
+Typed family `match` requires one handler for every declared case. The
+complete family declaration, rather than the current narrowing of the input
+value, determines the required handler object.
+
+```ts
+const length = Message.match(
+  Message.make.write("hello"),
+  {
+    quit: () => 0,
+    write: (text) => text.length,
+  },
+);
+```
+
+Exactly the selected own data-property handler runs once and without a
+library-defined `this` receiver. Inherited properties and accessors do not
+satisfy handler availability. Unit handlers receive zero arguments. Payload
+handlers receive exactly the stored payload. Unselected handler properties are
+not read by Match execution.
+
+At runtime, `match` requires the Variant tag to be an own data property.
+Payload cases also require an own data `value` property. Inherited properties
+and accessors therefore cannot supply either part of the Variant
+representation. `match` then validates that the selected tag belongs to the
+family and that the selected handler is an own function property. TypeScript
+owns whole-handler exhaustiveness for honestly typed calls.
+
+Handler return and abrupt completion follow ordinary JavaScript semantics.
+Promise values remain native Promise values.
+
+Normal TypeScript discriminant narrowing remains available when local control
+flow owns the branch:
+
+```ts
+if (message.tag === "write") {
+  message.value;
+  // string
+}
+```
+
+## 6. Generic and recursive families
+
+A generic family can be an ordinary factory:
+
+```ts
+const Remote = <T>() =>
+  Variant.define("Remote", [
+    ["idle", Variant.unit],
+    ["success", Variant.payload<T>()],
+  ]);
+
+type Remote<T> =
+  Variant.Value<ReturnType<typeof Remote<T>>>;
+```
+
+Recursive payloads can refer back to the Variant value through an ordinary
+object or interface boundary:
+
+```ts
+interface AddPayload {
+  readonly left: Expr;
+  readonly right: Expr;
+}
+
+const Expr = Variant.define("Expr", [
+  ["literal", Variant.payload<number>()],
+  ["add", Variant.payload<AddPayload>()],
+]);
+
+type Expr =
+  Variant.Value<typeof Expr>;
+```
+
+Variant does not introduce a separate recursive-data runtime.
+
+## 7. Snapshot stability
+
+`Variant.define` snapshots its case-entry tuple into constructor and
+elimination behavior. Later mutation of caller-owned JavaScript arrays cannot
+change the already-defined family. Typed declarations reject directly mutable outer and inner tuples. A readonly
+view whose backing array is mutated through another alias before definition is
+a TypeScript trust-model escape rather than a guarantee Variant can reify at
+runtime.
+
+The returned family and its `make` namespace are immutable runtime
+declarations. Constructed Variant values remain ordinary structural data.
+
+## 8. Typed boundary
+
+Variant formation consumes already-typed payloads.
+
+Runtime schema decoding, normalization, authorization, mutable freshness, and
+version negotiation belong to application owners that can establish those
+facts.
+
+The runtime declaration boundary recognizes its finite case grammar. `match`
+checks selected case membership and selected handler availability. Payload type
+validity remains a TypeScript guarantee inside the ordinary Selaws trust model.
+
+```ts
+const UserEvent = Variant.define("UserEvent", [
+  ["loaded", Variant.payload<User>()],
+]);
+```
+
+This declaration does not validate unknown JSON as `User`; the decoding
+boundary must do that before constructing `loaded`.
+
+## 9. Owner independence
+
+Variant owns labeled alternative identity, correlated payload formation, and
+the complete case universe used for elimination. Its family `match` conforms
+to the shared Match law; Match does not become a Variant-owned or independent
+carrier.
+
+Protocol owns admissible labeled transitions between application-owned state
+identifiers.
+
+Option owns presence.
+
+Result owns recoverable success or failure.
+
+Validation owns deterministic accumulation of independent issues.
+
+Those owners may use sum-shaped structural data or compose values without
+transferring their domain laws to Variant.

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "selaws",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Independent semantic primitives for TypeScript with explicit laws.",
+  "license": "MIT",
+  "keywords": [
+    "typescript",
+    "semantic",
+    "result",
+    "option",
+    "validation",
+    "nominal-typing",
+    "refinement-types",
+    "domain-modeling"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amatzk/selaws.git"
+  },
+  "homepage": "https://github.com/amatzk/selaws",
+  "bugs": {
+    "url": "https://github.com/amatzk/selaws/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./identity": {
+      "types": "./dist/identity.d.ts",
+      "import": "./dist/identity.js",
+      "default": "./dist/identity.js"
+    },
+    "./evidence": {
+      "types": "./dist/evidence.d.ts",
+      "import": "./dist/evidence.js",
+      "default": "./dist/evidence.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js",
+      "default": "./dist/protocol.js"
+    },
+    "./variant": {
+      "types": "./dist/variant.d.ts",
+      "import": "./dist/variant.js",
+      "default": "./dist/variant.js"
+    },
+    "./result": {
+      "types": "./dist/result/index.d.ts",
+      "import": "./dist/result/index.js",
+      "default": "./dist/result/index.js"
+    },
+    "./option": {
+      "types": "./dist/option.d.ts",
+      "import": "./dist/option.js",
+      "default": "./dist/option.js"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.ts",
+      "import": "./dist/validation.js",
+      "default": "./dist/validation.js"
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "fix": "biome check --write .",
+    "test:types": "tsc -p tsconfig.test.json",
+    "test:runtime": "node --test test/*.test.mjs",
+    "test": "pnpm run build && pnpm run test:types && pnpm run test:runtime",
+    "check": "biome ci . && pnpm run test"
+  }
 }

package/src/evidence.ts

@@ -0,0 +1,120 @@
+import {
+  isBigint,
+  isBoolean,
+  isNumber,
+  isString,
+  isSymbol,
+  type NarrowSymbolSet,
+  type Scalar,
+  type SingleName,
+  type SingleSymbol,
+  type Token,
+} from "./internal/scalar.js";
+
+export type { Scalar } from "./internal/scalar.js";
+
+type EvidenceMarker = {
+  readonly "~selaws.evidence": true;
+};
+
+/**
+ * A stable fact established about a scalar value.
+ *
+ * Independent fact tokens occupy independent phantom properties, so evidence
+ * composes while preserving existing identity and evidence on the same scalar.
+ */
+export type Evidence<T extends Scalar, Fact extends symbol> = [Fact] extends [never]
+  ? never
+  : [Fact] extends [NarrowSymbolSet<Fact>]
+    ? T & {
+        readonly [Key in Fact]: EvidenceMarker;
+      }
+    : never;
+
+type Establish<T extends Scalar, Fact extends symbol> = <Value extends T>(
+  value: Value,
+) => Evidence<Value, Fact>;
+
+/** Defines an owner-scoped formation boundary for one stable fact. */
+export function defineFact<T extends Scalar>() {
+  return function define<const Fact extends symbol, Api>(
+    token: Fact & SingleSymbol<Fact>,
+    build: (establish: Establish<T, Fact>) => Api,
+  ): Api {
+    void token;
+
+    const establish = <Value extends T>(value: Value): Evidence<Value, Fact> =>
+      value as Evidence<Value, Fact>;
+
+    return build(establish);
+  };
+}
+
+type NamedEvidence<T extends Scalar, Name extends string> = T & {
+  readonly [Key in `~selaws.evidence:${Name}`]: true;
+};
+
+type FactEvidence<
+  T extends Scalar,
+  TokenValue extends Token,
+> = TokenValue extends string
+  ? NamedEvidence<T, TokenValue>
+  : TokenValue extends symbol
+    ? Evidence<T, TokenValue>
+    : never;
+
+type Predicate<T> = (value: T) => boolean;
+
+interface Fact<T extends Scalar, TokenValue extends Token> {
+  <Value extends T>(value: Value): FactEvidence<Value, TokenValue> | undefined;
+  (value: unknown): FactEvidence<T, TokenValue> | undefined;
+}
+
+interface FactFactory<T extends Scalar> {
+  <const Name extends string>(
+    name: Name & SingleName<Name>,
+    predicate: Predicate<T>,
+  ): Fact<T, Name>;
+
+  <const Key extends symbol>(
+    key: Key & SingleSymbol<Key>,
+    predicate: Predicate<T>,
+  ): Fact<T, Key>;
+}
+
+const factFactory = <T extends Scalar>(
+  isCarrier: (value: unknown) => value is T,
+): FactFactory<T> =>
+  ((_token: Token, predicate: Predicate<T>) => (value: unknown) =>
+    isCarrier(value) && predicate(value)
+      ? value
+      : undefined) as unknown as FactFactory<T>;
+
+type EvidenceFacade = Readonly<{
+  bigint: FactFactory<bigint>;
+  boolean: FactFactory<boolean>;
+  define: typeof defineFact;
+  number: FactFactory<number>;
+  string: FactFactory<string>;
+  symbol: FactFactory<symbol>;
+}>;
+
+/** Stable scalar facts with named or declaration-owned evidence. */
+export const evidence: EvidenceFacade = {
+  bigint: factFactory(isBigint),
+  boolean: factFactory(isBoolean),
+  define: defineFact,
+  number: factFactory(isNumber),
+  string: factFactory(isString),
+  symbol: factFactory(isSymbol),
+};
+
+export namespace evidence {
+  /** Applies an evidence declaration's fact type to an existing scalar value. */
+  export type Proven<F, Value extends Scalar> =
+    F extends Fact<infer T, infer TokenValue>
+      ? Value extends T
+        ? FactEvidence<Value, TokenValue>
+        : never
+      : never;
+}

package/src/identity.ts

@@ -0,0 +1,129 @@
+import {
+  isBigint,
+  isBoolean,
+  isNumber,
+  isString,
+  isSymbol,
+  type Scalar,
+  type SingleName,
+  type SingleSymbol,
+  type Token,
+} from "./internal/scalar.js";
+
+export type { Scalar } from "./internal/scalar.js";
+
+type IdentityMarker = {
+  readonly "~selaws.identity": true;
+};
+
+/**
+ * A scalar carrying one declaration-owned nominal identity.
+ *
+ * The domain token is the phantom property key itself, so identity belongs to
+ * the declaration that owns the token and remains stable across duplicate
+ * Selaws installations.
+ */
+export type Identity<T extends Scalar, Id extends symbol> = [Id] extends [never]
+  ? never
+  : [Id] extends [SingleSymbol<Id>]
+    ? T & {
+        readonly [Key in Id]: IdentityMarker;
+      }
+    : never;
+
+type Mint<T extends Scalar, Id extends symbol> = <Value extends T>(
+  value: Value,
+) => Identity<Value, Id>;
+
+/** Defines an owner-scoped formation boundary for one nominal identity. */
+export function defineIdentity<T extends Scalar>() {
+  return function define<const Id extends symbol, Api>(
+    token: Id & SingleSymbol<Id>,
+    build: (mint: Mint<T, Id>) => Api,
+  ): Api {
+    void token;
+
+    const mint = <Value extends T>(value: Value): Identity<Value, Id> =>
+      value as Identity<Value, Id>;
+
+    return build(mint);
+  };
+}
+
+type NamedIdentity<T extends Scalar, Name extends string> = T & {
+  readonly [Key in `~selaws.identity:${Name}`]: true;
+};
+
+type DomainIdentity<
+  T extends Scalar,
+  TokenValue extends Token,
+> = TokenValue extends string
+  ? NamedIdentity<T, TokenValue>
+  : TokenValue extends symbol
+    ? Identity<T, TokenValue>
+    : never;
+
+type Predicate<T> = (value: T) => boolean;
+
+interface OpenIdentity<T extends Scalar, TokenValue extends Token> {
+  <Value extends T>(value: Value): DomainIdentity<Value, TokenValue>;
+  (value: unknown): DomainIdentity<T, TokenValue> | undefined;
+}
+
+interface CheckedIdentity<T extends Scalar, TokenValue extends Token> {
+  <Value extends T>(value: Value): DomainIdentity<Value, TokenValue> | undefined;
+  (value: unknown): DomainIdentity<T, TokenValue> | undefined;
+}
+
+interface IdentityFactory<T extends Scalar> {
+  <const Name extends string>(name: Name & SingleName<Name>): OpenIdentity<T, Name>;
+
+  <const Name extends string>(
+    name: Name & SingleName<Name>,
+    predicate: Predicate<T>,
+  ): CheckedIdentity<T, Name>;
+
+  <const Key extends symbol>(key: Key & SingleSymbol<Key>): OpenIdentity<T, Key>;
+
+  <const Key extends symbol>(
+    key: Key & SingleSymbol<Key>,
+    predicate: Predicate<T>,
+  ): CheckedIdentity<T, Key>;
+}
+
+const identityFactory = <T extends Scalar>(
+  isCarrier: (value: unknown) => value is T,
+): IdentityFactory<T> =>
+  ((_token: Token, predicate?: Predicate<T>) => (value: unknown) =>
+    isCarrier(value) && (predicate === undefined || predicate(value))
+      ? value
+      : undefined) as unknown as IdentityFactory<T>;
+
+type IdentityFacade = Readonly<{
+  bigint: IdentityFactory<bigint>;
+  boolean: IdentityFactory<boolean>;
+  define: typeof defineIdentity;
+  number: IdentityFactory<number>;
+  string: IdentityFactory<string>;
+  symbol: IdentityFactory<symbol>;
+}>;
+
+/** Scalar identity formation with named or declaration-owned identity. */
+export const identity: IdentityFacade = {
+  bigint: identityFactory(isBigint),
+  boolean: identityFactory(isBoolean),
+  define: defineIdentity,
+  number: identityFactory(isNumber),
+  string: identityFactory(isString),
+  symbol: identityFactory(isSymbol),
+};
+
+export namespace identity {
+  /** Extracts the scalar identity value type produced by an identity declaration. */
+  export type Value<Domain> =
+    Domain extends OpenIdentity<infer T, infer TokenValue>
+      ? DomainIdentity<T, TokenValue>
+      : Domain extends CheckedIdentity<infer T, infer TokenValue>
+        ? DomainIdentity<T, TokenValue>
+        : never;
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+import { Option as OptionFacade } from "./option.js";
+import { Protocol as ProtocolFacade } from "./protocol.js";
+import { Result as ResultFacade } from "./result/core.js";
+import { Validation as ValidationFacade } from "./validation.js";
+import { Variant as VariantFacade } from "./variant.js";
+
+export { type Evidence, evidence } from "./evidence.js";
+export { type Identity, identity, type Scalar } from "./identity.js";
+
+/** Root-entry Protocol carrier paired with the Protocol facade value. */
+export type Protocol<
+  Transitions extends readonly import("./protocol.js").Transition[],
+> = import("./protocol.js").Protocol<Transitions>;
+/** Root-entry Protocol facade. */
+export const Protocol: typeof ProtocolFacade = ProtocolFacade;
+
+/** Root-entry Variant carrier paired with the Variant facade value. */
+export type Variant<Family> = import("./variant.js").Variant<Family>;
+/** Root-entry Variant facade. */
+export const Variant: typeof VariantFacade = VariantFacade;
+export namespace Variant {
+  /** Extracts the closed value union produced by one Variant family. */
+  export type Value<Family> = import("./variant.js").Variant<Family>;
+}
+
+export type { None, OptionValue, Some } from "./option.js";
+/** Root-entry Option carrier paired with the Option facade value. */
+export type Option<T> = import("./option.js").Option<T>;
+/** Root-entry Option facade. */
+export const Option: typeof OptionFacade = OptionFacade;
+
+export type {
+  Invalid,
+  Valid,
+  ValidationError,
+  ValidationIssues,
+  ValidationValue,
+} from "./validation.js";
+/** Root-entry Validation carrier paired with the Validation facade value. */
+export type Validation<T, E> = import("./validation.js").Validation<T, E>;
+/** Root-entry Validation facade. */
+export const Validation: typeof ValidationFacade = ValidationFacade;
+
+export type {
+  AsyncResult,
+  Err,
+  Ok,
+  ResultError,
+  ResultValue,
+} from "./result/core.js";
+/** Root-entry Result carrier paired with the Result facade value. */
+export type Result<T, E> = import("./result/core.js").Result<T, E>;
+/** Root-entry Result facade. */
+export const Result: typeof ResultFacade = ResultFacade;

package/src/internal/callback.ts

@@ -0,0 +1,54 @@
+type Same<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+    ? (<T>() => T extends B ? 1 : 2) extends <T>() => T extends A ? 1 : 2
+      ? true
+      : false
+    : false;
+
+type UnknownCallback = (this: void, ...args: never[]) => unknown;
+
+type OverloadUnion<
+  Callback,
+  Partial = unknown,
+  Previous = never,
+  Repeated extends boolean = false,
+  Accumulated = never,
+> = Callback extends (this: infer This, ...args: infer Args) => infer Result
+  ? ((this: This, ...args: Args) => Result) extends infer Current
+    ? Same<Current, Previous> extends true
+      ? Repeated extends true
+        ? Accumulated | UnknownCallback
+        : Partial extends Callback
+          ? Accumulated
+          : OverloadUnion<
+              Partial & Callback,
+              Partial & Current,
+              Current,
+              true,
+              Accumulated | Current
+            >
+      : Partial extends Callback
+        ? Accumulated
+        : OverloadUnion<
+            Partial & Callback,
+            Partial & Current,
+            Current,
+            false,
+            Accumulated | Current
+          >
+    : Accumulated
+  : Accumulated;
+
+/**
+ * Extracts a conservative union of callable return types.
+ *
+ * TypeScript exposes overloads as intersections. Generic callable reflection
+ * can repeat one instantiated signature indefinitely; repeated reflection
+ * widens to unknown instead of exhausting compiler instantiation depth.
+ */
+export type CallbackResult<Callback> =
+  OverloadUnion<Callback> extends infer One
+    ? One extends (...args: never[]) => infer Result
+      ? Result
+      : never
+    : never;