liminal 0.1.0-beta.25

package/src/core/Type.ts

@@ -0,0 +1,45 @@
+import type { Annotation } from "./annotations/Annotation.js"
+import type { Param, TemplatePart } from "./annotations/mod.js"
+import type { ReduceDependencies } from "./ReduceDependencies.js"
+
+export interface Type<T, D extends symbol = never> {
+  <A extends Array<Annotation<T>>>(
+    ...annotations: A | Array<Annotation<T>> & { length: never }
+  ): Type<T, ReduceDependencies<D, A>>
+
+  <A extends Array<TemplatePart>>(
+    template: TemplateStringsArray,
+    ...descriptionParts: A
+  ): Type<T, ReduceDependencies<D, A>>
+
+  T: T
+  D: D
+
+  [TypeKey]: true
+  type: "Type"
+  trace: string
+  declaration: TypeDeclaration
+  annotations: Array<Annotation>
+
+  extract: <K extends symbol, V>(param: Param<K, V>) => Array<V>
+}
+
+export type TypeDeclaration = {
+  getAtom: () => PartialType
+  factory?: never
+  args?: never
+} | {
+  getAtom?: never
+  factory: (...args: any) => PartialType
+  args: unknown[]
+}
+
+export type PartialType<T = any> = Type<T, symbol>
+
+export type DerivedType<
+  T,
+  X extends Array<PartialType>,
+  P extends symbol = never,
+> = [Type<T, P | X[number]["D"]>][0]
+
+export const TypeKey: unique symbol = Symbol()

package/src/core/TypeVisitor.ts

@@ -0,0 +1,44 @@
+import type { Expand } from "../util/mod.js"
+import { IntrinsicName, type Intrinsics } from "./intrinsics_util.js"
+import type { PartialType } from "./Type.js"
+
+export type TypeVisitorArms<C, R> = Expand<
+  & {
+    hook?: (
+      next: (ctx: C, type: PartialType) => R,
+      ctx: C,
+      type: PartialType,
+    ) => R
+  }
+  & (
+    | ({ fallback?: never } & TypeVisitorIntrinsicArms<C, R>)
+    | (
+      & { fallback: (ctx: C, type: PartialType, ...args: unknown[]) => R }
+      & Partial<TypeVisitorIntrinsicArms<C, R>>
+    )
+  )
+>
+
+export type TypeVisitorIntrinsicArms<C, R> = {
+  [K in IntrinsicName]: (
+    ctx: C,
+    ...rest: Intrinsics[K] extends PartialType ? [type: Intrinsics[K]]
+      : [type: ReturnType<Intrinsics[K]>, ...args: Parameters<Intrinsics[K]>]
+  ) => R
+}
+
+export function TypeVisitor<C, R>(arms: TypeVisitorArms<C, R>): (ctx: C, type: PartialType) => R {
+  const { hook } = arms
+  if (hook) {
+    return (ctx, type) => hook(next, ctx, type)
+  }
+  return next
+
+  function next(ctx: C, type: PartialType): R {
+    return (arms[IntrinsicName(type)] ?? arms.fallback!)(
+      ctx,
+      type as never,
+      ...type.declaration.factory ? type.declaration.args as never : [],
+    )
+  }
+}

package/src/core/annotations/Annotation.ts

@@ -0,0 +1,14 @@
+import type { Falsy } from "../../deps/jsr.io/@std/assert/1.0.10/mod.js"
+import type { PartialType } from "../Type.js"
+import type { Assertion } from "./Assertion.js"
+import type { Arg, Param } from "./Param.js"
+import type { Template } from "./Template.js"
+
+export type Annotation<T = any> =
+  | Falsy
+  | string
+  | Template
+  | PartialType
+  | Assertion<T>
+  | Param
+  | Arg

package/src/core/annotations/Assertion.ts

@@ -0,0 +1,18 @@
+import type { PromiseOr } from "../../util/mod.js"
+
+export interface Assertion<T = any> {
+  type: "Assertion"
+  description: string
+  f?: (value: T) => PromiseOr<void>
+}
+
+export function Assertion<T>(
+  description: string,
+  f?: (value: T) => PromiseOr<void>,
+): Assertion<T> {
+  return {
+    type: "Assertion",
+    description,
+    f,
+  }
+}

package/src/core/annotations/Description.ts

@@ -0,0 +1,16 @@
+import { Param } from "./Param.js"
+
+export const DescriptionParamKey: unique symbol = Symbol()
+
+export interface DescriptionArg {
+  [DescriptionParamKey]: string
+}
+
+export function DescriptionParam<K extends symbol, A = string>(
+  key: K,
+  serialize?: (value: A) => string,
+): Param<K, A, DescriptionArg> {
+  return Param(key, (value) => ({
+    [DescriptionParamKey]: (serialize?.(value) ?? value) as string,
+  }))
+}

package/src/core/annotations/Param.ts

@@ -0,0 +1,30 @@
+export interface Param<K extends symbol = symbol, A = any, T = any> {
+  (arg: A): Arg<K, T>
+  type: "Param"
+  key: K
+}
+
+export type AnyParam<T> = Param<symbol, any, T>
+
+export interface Arg<K extends symbol = symbol, T = any> {
+  type: "Arg"
+  key: K
+  value: T
+}
+
+export function Param<K extends symbol, A, T>(
+  key: K,
+  f: (value: A) => T,
+): Param<K, A, T> {
+  return Object.assign(
+    (value: A): Arg<K> => ({
+      type: "Arg",
+      key,
+      value: f(value),
+    }),
+    {
+      type: "Param" as const,
+      key,
+    },
+  )
+}

package/src/core/annotations/Template.ts

@@ -0,0 +1,11 @@
+import type { PartialType } from "../Type.js"
+import type { DescriptionArg } from "./Description.js"
+import type { AnyParam } from "./Param.js"
+
+export interface Template {
+  type: "Template"
+  template: TemplateStringsArray
+  parts: Array<TemplatePart>
+}
+
+export type TemplatePart = string | PartialType | AnyParam<string | DescriptionArg>

package/src/core/annotations/mod.ts

@@ -0,0 +1,7 @@
+// moderate
+
+export * from "./Annotation.js"
+export * from "./Assertion.js"
+export * from "./Description.js"
+export * from "./Param.js"
+export * from "./Template.js"

package/src/core/assert.ts

@@ -0,0 +1,145 @@
+import * as A from "../deps/jsr.io/@std/assert/1.0.10/mod.js"
+import type { PartialType, Type } from "./Type.js"
+import { TypeVisitor } from "./TypeVisitor.js"
+
+export interface Diagnostic {
+  type: PartialType
+  path: string
+  exception: unknown
+  value: unknown
+}
+
+export namespace Diagnostic {
+  export function toString({ exception, path, value }: Diagnostic): string {
+    return `${
+      exception instanceof Error ? `Error "${exception.name}"` : "Exception"
+    } from value \`${JSON.stringify(value)}\` at \`root${path}\`: ${
+      exception instanceof Error ? exception.message : JSON.stringify(exception)
+    }`
+  }
+}
+
+export async function assert(type: Type<any>, value: unknown): Promise<void> {
+  const ctx = new AssertContext([], [], "root", value)
+  visit(ctx, type)
+  const diagnostics = [
+    ...ctx.structuralDiagnostics,
+    ...await Promise.all(ctx.annotationDiagnostics ?? []).then((v) => v.filter((e) => !!e)),
+  ]
+  if (diagnostics.length) {
+    throw new AggregateError(diagnostics.map(({ exception }) => exception))
+  }
+}
+
+export function matchUnionMember(members: Array<PartialType>, value: unknown): PartialType | void {
+  const queue = [...members]
+  while (queue.length) {
+    const current = queue.pop()!
+    const diagnostics: Array<Diagnostic> = []
+    visit(new AssertContext(diagnostics, undefined, "", value), current)
+    if (diagnostics.length) {
+      continue
+    }
+    return current
+  }
+}
+
+export class AssertContext {
+  constructor(
+    readonly structuralDiagnostics: Array<Diagnostic>,
+    readonly annotationDiagnostics: undefined | Array<Promise<Diagnostic | void>>,
+    readonly path: string,
+    readonly value: unknown,
+    readonly junction?: number | string,
+  ) {}
+
+  descend = (value: unknown, junction?: number | string): AssertContext =>
+    new AssertContext(
+      this.structuralDiagnostics,
+      this.annotationDiagnostics,
+      this.path,
+      value,
+      junction,
+    )
+}
+
+const visit = TypeVisitor<AssertContext, void>({
+  hook(next, ctx, type) {
+    const path = ctx.junction ? ctx.path : `${ctx.path}["${ctx.junction}"]`
+    try {
+      next(ctx, type)
+    } catch (exception: unknown) {
+      ctx.structuralDiagnostics.push({
+        type,
+        path,
+        exception,
+        value: ctx.value,
+      })
+    }
+    const { annotationDiagnostics } = ctx
+    if (annotationDiagnostics) {
+      type.annotations
+        .filter((annotation) => typeof annotation === "object" && annotation?.type === "Assertion")
+        .forEach(({ f }) => {
+          if (f) {
+            annotationDiagnostics.push((async () => {
+              try {
+                await f(ctx.value)
+              } catch (exception: unknown) {
+                return {
+                  type,
+                  path,
+                  exception,
+                  value: ctx.value,
+                }
+              }
+            })())
+          }
+        })
+    }
+  },
+  null({ value }) {
+    A.assert(value === null)
+  },
+  boolean({ value }) {
+    A.assert(typeof value === "boolean")
+  },
+  integer({ value }) {
+    A.assert(Number.isInteger(value))
+  },
+  number({ value }) {
+    A.assert(typeof value === "number")
+  },
+  string({ value }) {
+    A.assert(typeof value === "string")
+  },
+  const({ value }, _1, _2, cmpValue) {
+    A.assertEquals(value, cmpValue)
+  },
+  enum({ value }, _1, ...values) {
+    A.assert(typeof value === "string")
+    A.assertArrayIncludes(values, [value])
+  },
+  array(ctx, _1, element) {
+    A.assert(Array.isArray(ctx.value))
+    ctx.value.forEach((value, i) => visit(ctx.descend(value, i), element))
+  },
+  object(ctx, _1, fields) {
+    const keys = Object.keys(fields).toSorted()
+    const { value } = ctx
+    A.assert(typeof value === "object" && value !== null)
+    A.assertEquals(keys, Object.keys(value).toSorted())
+    keys.forEach((key) => visit(ctx.descend(value[key as never], key), fields[key]!))
+  },
+  transform(ctx, _1, from) {
+    visit(ctx, from)
+  },
+  union(ctx, _1, ...members) {
+    const match = matchUnionMember(members, ctx.value)
+    A.assert(match)
+    visit(ctx, match)
+  },
+  ref(ctx, _1, get) {
+    visit(ctx, get())
+  },
+})

package/src/core/declareIntrinsic.ts

@@ -0,0 +1,45 @@
+import { isTemplateStringsArray } from "../util/mod.js"
+import type { Annotation } from "./annotations/Annotation.js"
+import type { TemplatePart } from "./annotations/mod.js"
+import { inspect } from "./inspect.node.js"
+import type { ReduceDependencies } from "./ReduceDependencies.js"
+import { type Type, type TypeDeclaration, TypeKey } from "./Type.js"
+
+export function declare<T, D extends symbol>(
+  declaration: TypeDeclaration,
+  annotations: Array<Annotation> = [],
+): Type<T, D> {
+  return Object.assign(
+    Type,
+    inspect,
+    {
+      [TypeKey]: true,
+      type: "Type",
+      trace: new Error().stack!,
+      declaration,
+      annotations,
+      extract: () => {
+        throw 0
+      },
+    } satisfies Omit<Type<T, D>, "T" | "D"> as never,
+  )
+
+  function Type<A extends Array<TemplatePart>>(
+    template: TemplateStringsArray,
+    ...descriptionParts: A
+  ): Type<T, ReduceDependencies<D, A>>
+  function Type<A extends Array<Annotation>>(...annotations: A): Type<T, ReduceDependencies<D, A>>
+  function Type(
+    maybeTemplate: Annotation | TemplateStringsArray,
+    ...parts: Array<Annotation>
+  ): Type<T, symbol> {
+    if (isTemplateStringsArray(maybeTemplate)) {
+      return declare(declaration, [...annotations, {
+        type: "Template",
+        template: maybeTemplate,
+        parts: parts as Array<TemplatePart>,
+      }])
+    }
+    return declare(declaration, [maybeTemplate, ...annotations, ...parts])
+  }
+}

package/src/core/deserialize.ts

@@ -0,0 +1,36 @@
+import { assert } from "../deps/jsr.io/@std/assert/1.0.10/mod.js"
+import { matchUnionMember } from "./assert.js"
+import type { Type } from "./Type.js"
+import { TypeVisitor } from "./TypeVisitor.js"
+
+export function deserialize<T>(type: Type<T>, jsonText: string): T {
+  return visit(JSON.parse(jsonText), type) as never
+}
+
+const visit = TypeVisitor<unknown, unknown>({
+  hook(next, value, type) {
+    return next(value, type)
+  },
+  array(value, _1, element): unknown {
+    return (value as unknown[]).map((e) => visit(e, element))
+  },
+  object(value, _1, fields): unknown {
+    return Object.fromEntries(
+      Object.entries(fields).map(([k, v]) => [k, visit((value as never)[k], v)]),
+    )
+  },
+  union(value, _1, ...members): unknown {
+    const matched = matchUnionMember(members, value)!
+    assert(matched)
+    return visit(value, matched)
+  },
+  ref(ctx, _1, get): unknown {
+    return visit(ctx, get())
+  },
+  transform(ctx, _1, from, f): unknown {
+    return f(visit(ctx, from))
+  },
+  fallback(value) {
+    return value
+  },
+})

package/src/core/display.ts

@@ -0,0 +1,68 @@
+import { IntrinsicName } from "./intrinsics_util.js"
+import type { PartialType } from "./Type.js"
+import { TypeVisitor } from "./TypeVisitor.js"
+
+export function display(type: PartialType): string {
+  return visit(new DisplayContext(type, false, 0), type)
+}
+
+class DisplayContext {
+  constructor(
+    readonly rootType: PartialType,
+    readonly visitedRoot: boolean,
+    readonly depth: number,
+  ) {}
+
+  indentCtx = () => new DisplayContext(this.rootType, this.visitedRoot, this.depth + 1)
+}
+
+const visit = TypeVisitor<DisplayContext, string>({
+  hook(next, ctx, type): string {
+    if (type === ctx.rootType && ctx.visitedRoot) {
+      return "self"
+    }
+    return next(new DisplayContext(ctx.rootType, true, ctx.depth), type)
+  },
+  const(_0, _1, _2, value): string {
+    if (typeof value === "string") {
+      return `"${escapeDoubleQuotes(value)}"`
+    }
+    return JSON.stringify(value)
+  },
+  array(ctx, _1, element): string {
+    return `array(${visit(ctx, element)})`
+  },
+  object(ctx, _1, fields): string {
+    return `object({\n${
+      Object
+        .entries(fields)
+        .map(([k, v]) =>
+          `${"  ".repeat(ctx.depth + 1)}${escapeDoubleQuotes(k)}: ${visit(ctx.indentCtx(), v)}`
+        )
+        .join(",\n")
+    }\n${"  ".repeat(ctx.depth)}})`
+  },
+  enum(_0, _1, ...values) {
+    return `enum("${values.map(escapeDoubleQuotes).join(`", "`)}")`
+  },
+  union(ctx, _1, ...members): string {
+    return `union(\n${"  ".repeat(ctx.depth + 1)}${
+      members.map((member) => visit(ctx.indentCtx(), member)).join(
+        `,\n${"  ".repeat(ctx.depth + 1)}`,
+      )
+    }\n)`
+  },
+  ref(ctx, _1, get): string {
+    return visit(ctx, get())
+  },
+  transform(ctx, _1, from): string {
+    return `f(${visit(ctx, from)})`
+  },
+  fallback(_0, type) {
+    return IntrinsicName(type)
+  },
+})
+
+function escapeDoubleQuotes(value: string): string {
+  return value.indexOf(`"`) !== -1 ? JSON.stringify(value) : value
+}

package/src/core/inspect.node.ts

@@ -0,0 +1,13 @@
+import { display } from "./display.js"
+import type { PartialType } from "./Type.js"
+
+export const inspect = {
+  [Symbol.for("nodejs.util.inspect.custom")](
+    this: PartialType,
+    _0: unknown,
+    _1: unknown,
+    _inspect_: (value: unknown) => string,
+  ): string {
+    return display(this)
+  },
+}

package/src/core/intrinsics.ts

@@ -0,0 +1,86 @@
+import { declare } from "./declareIntrinsic.js"
+import type { PartialType, Type } from "./Type.js"
+
+export { null_ as null }
+const null_: Type<null> = declare({
+  getAtom: () => null_,
+})
+
+export const boolean: Type<boolean> = declare({
+  getAtom: () => boolean,
+})
+
+export const integer: Type<number> = declare({
+  getAtom: () => integer,
+})
+
+export const number: Type<number> = declare({
+  getAtom: () => number,
+})
+
+export const string: Type<string> = declare({
+  getAtom: () => string,
+})
+
+export { const_ as const }
+function const_<T, P extends symbol, const A extends T>(
+  type: Type<T, P>,
+  value: A,
+): Type<A, P> {
+  return declare({
+    factory: const_,
+    args: [type, value],
+  })
+}
+Object.defineProperty(const_, "name", { value: "const" })
+
+export function array<T, P extends symbol>(element: Type<T, P>): Type<Array<T>, P> {
+  return declare({
+    factory: array,
+    args: [element],
+  })
+}
+
+export function object<F extends Record<string, PartialType>>(
+  fields: F,
+): Type<{ [K in keyof F]: F[K]["T"] }, F[keyof F]["D"]> {
+  return declare({
+    factory: object,
+    args: [Object.fromEntries(Object.keys(fields).toSorted().map((key) => [key, fields[key]]))],
+  })
+}
+
+export { enum_ as enum }
+function enum_<V extends Array<string>>(...values: V): Type<V[number]> {
+  return declare({
+    factory: enum_,
+    args: values.toSorted(),
+  })
+}
+Object.defineProperty(enum_, "name", { value: "enum" })
+
+export function union<M extends Array<PartialType>>(
+  ...members: M
+): Type<M[number]["T"], M[number]["D"]> {
+  return declare({
+    factory: union,
+    args: members,
+  })
+}
+
+export function ref<T, P extends symbol>(get: () => Type<T, P>): Type<T, P> {
+  return declare({
+    factory: ref,
+    args: [get],
+  }) as never
+}
+
+export function transform<T, P extends symbol, R>(
+  from: Type<T, P>,
+  f: (value: T) => R,
+): Type<R, P> {
+  return declare({
+    factory: transform,
+    args: [from, f],
+  })
+}

package/src/core/intrinsics_util.ts

@@ -0,0 +1,50 @@
+import { unreachable } from "../deps/jsr.io/@std/assert/1.0.10/mod.js"
+import * as I from "./intrinsics.js"
+import type { PartialType } from "./Type.js"
+
+export type Intrinsics = typeof I
+export type IntrinsicName = keyof Intrinsics
+
+export function IntrinsicName(type: PartialType): IntrinsicName {
+  switch (type.declaration.getAtom?.()) {
+    case I.null: {
+      return "null"
+    }
+    case I.boolean: {
+      return "boolean"
+    }
+    case I.number: {
+      return "number"
+    }
+    case I.integer: {
+      return "integer"
+    }
+    case I.string: {
+      return "string"
+    }
+  }
+  switch (type.declaration.factory) {
+    case I.const: {
+      return "const"
+    }
+    case I.array: {
+      return "array"
+    }
+    case I.object: {
+      return "object"
+    }
+    case I.enum: {
+      return "enum"
+    }
+    case I.union: {
+      return "union"
+    }
+    case I.ref: {
+      return "ref"
+    }
+    case I.transform: {
+      return "transform"
+    }
+  }
+  unreachable()
+}

package/src/core/isType.ts

@@ -0,0 +1,20 @@
+import { IntrinsicName } from "./intrinsics_util.js"
+import { type PartialType, TypeKey } from "./Type.js"
+
+export function isType<T>(
+  inQuestion: unknown,
+  ...intrinsicNames: Array<IntrinsicName>
+): inQuestion is PartialType<T> {
+  if (typeof inQuestion === "function" && TypeKey in inQuestion) {
+    if (intrinsicNames.length) {
+      for (const intrinsicName of intrinsicNames) {
+        if (IntrinsicName(inQuestion as never as PartialType) === intrinsicName) {
+          return true
+        }
+      }
+    } else {
+      return true
+    }
+  }
+  return false
+}

package/src/core/mod.ts

@@ -0,0 +1,15 @@
+export * as L from "./L.js"
+
+// moderate --exclude annotations declareIntrinsic.ts inspect.ts L.ts utility
+
+export * from "./assert.js"
+export * from "./DescriptionContext.js"
+export * from "./deserialize.js"
+export * from "./display.js"
+export * from "./intrinsics.js"
+export * from "./intrinsics_util.js"
+export * from "./isType.js"
+export * from "./ReduceDependencies.js"
+export * from "./signature.js"
+export * from "./Type.js"
+export * from "./TypeVisitor.js"