@venn-lang/core 0.1.0

package/src/expr/cell.types.ts

@@ -0,0 +1,25 @@
+import type { EvalEnv } from "./eval-env.types.js";
+
+/**
+ * A binding's storage, addressed once and read many times.
+ *
+ * The language has no assignment, so a name never changes what it holds, but it
+ * can be *filled in* after the function reading it was built. A recursive `fn`
+ * is the plain case: `fib` becomes a value before the name `fib` is bound, so
+ * anything resolved eagerly would capture nothing. The cell is handed out empty
+ * and filled when the binding happens, which is what lets a name be resolved at
+ * compile time and still read the right value.
+ */
+export interface Cell {
+  value: unknown;
+}
+
+/** An environment that can hand out a cell per name: the top of the chain. */
+export interface CellEnv extends EvalEnv {
+  cell(name: string): Cell;
+}
+
+/** Whether this environment addresses its bindings by cell. */
+export function hasCells(env: EvalEnv): env is CellEnv {
+  return typeof (env as CellEnv).cell === "function";
+}

package/src/expr/closure.ts

@@ -0,0 +1,53 @@
+import type { CompiledBody } from "../compile/compile.types.js";
+import { hasCells } from "./cell.types.js";
+import { CLOSURE, type Closure } from "./closure.types.js";
+import type { EvalEnv } from "./eval-env.types.js";
+
+/** Whether this value is a `fn`. The brand distinguishes it from a lookalike map. */
+export function isClosure(value: unknown): value is Closure {
+  return typeof value === "object" && value !== null && CLOSURE in value;
+}
+
+/**
+ * Build a function value from parts the compiler already prepared.
+ *
+ * The free names are addressed here, once, against the environment the function
+ * is being defined in, so the body reads them by index rather than walking the
+ * chain on every call. Only where that environment hands out cells: a function
+ * nested in another reads its parent's frame, which has slots and no cells, and
+ * there the body falls back to asking by name.
+ */
+export function makeClosure(params: readonly string[], body: CompiledBody, env: EvalEnv): Closure {
+  if (body.free.length === 0 || !hasCells(env)) return { [CLOSURE]: true, params, body, env };
+  const up = body.free.map((name) => env.cell(name));
+  return { [CLOSURE]: true, params, body, env, up };
+}
+
+/**
+ * A class, not an object literal holding a closure: one shared prototype method
+ * means the `lookup` call site inside the evaluator sees a single callee.
+ *
+ * `Object.hasOwn`, not `in`: `in` walks the prototype chain, so a Venn binding
+ * named `constructor` or `toString` would resolve to JavaScript's own.
+ */
+class ChildEnv implements EvalEnv {
+  constructor(
+    private readonly parent: EvalEnv,
+    private readonly bindings: Record<string, unknown>,
+  ) {}
+
+  lookup(name: string): unknown {
+    if (Object.hasOwn(this.bindings, name)) return this.bindings[name];
+    return this.parent.lookup(name);
+  }
+}
+
+/**
+ * An environment nested in `parent`, holding the given bindings.
+ *
+ * Only own properties of `bindings` count as bound, so a name such as
+ * `toString` resolves through to the parent rather than to JavaScript's own.
+ */
+export function childEnv(parent: EvalEnv, bindings: Record<string, unknown>): EvalEnv {
+  return new ChildEnv(parent, bindings);
+}

package/src/expr/closure.types.ts

@@ -0,0 +1,31 @@
+import type { CompiledBody } from "../compile/compile.types.js";
+import type { Cell } from "./cell.types.js";
+import type { EvalEnv } from "./eval-env.types.js";
+
+/** The brand that tells a function value apart from a map that happens to look like one. */
+export const CLOSURE: unique symbol = Symbol("venn.closure");
+
+/**
+ * A function value: its parameter names, its compiled body, and the environment
+ * it was defined in.
+ *
+ * Because `fn` is pure (§08), a closure runs entirely in the evaluator, which
+ * is what makes functions first-class and callable from any expression,
+ * interpolation included.
+ *
+ * The body arrives already compiled. A `fn (…) => …` written inside `map` is
+ * evaluated once per call to `map`, so compiling there would put the compiler
+ * back in the hot loop.
+ */
+export interface Closure {
+  readonly [CLOSURE]: true;
+  readonly params: readonly string[];
+  readonly body: CompiledBody;
+  readonly env: EvalEnv;
+  /**
+   * A cell per free name of the body, resolved when this value was made.
+   * Absent when the defining environment does not address bindings by cell: a
+   * function nested inside another, whose free names live in its frame.
+   */
+  readonly up?: readonly Cell[];
+}

package/src/expr/eval-env.types.ts

@@ -0,0 +1,9 @@
+/**
+ * The scope the evaluator reads from: `let`/`const`, captures, parameters.
+ *
+ * Actions and matchers are deliberately absent. They belong to the runtime
+ * registry, which keeps the evaluator pure and free of protocol execution.
+ */
+export interface EvalEnv {
+  lookup(name: string): unknown;
+}

package/src/expr/evaluate.ts

@@ -0,0 +1,18 @@
+import { compileExpr } from "../compile/index.js";
+import type { Expr } from "../generated/ast.js";
+import type { EvalEnv } from "./eval-env.types.js";
+
+/**
+ * Evaluate a kernel expression against an injected environment.
+ *
+ * Compilation happens once per node and is remembered, so calling this in a
+ * loop pays for the tree only on the first pass.
+ *
+ * @returns The value, or a promise for it when the expression reached something
+ * that has not arrived yet.
+ * @throws ProblemError When the expression fails: a unit mismatch, a value that
+ * is not callable, or a placeholder that does not parse.
+ */
+export function evaluate(expr: Expr, env: EvalEnv): unknown {
+  return compileExpr(expr)(env);
+}

package/src/expr/frame.ts

@@ -0,0 +1,60 @@
+import type { Closure } from "./closure.types.js";
+import type { EvalEnv } from "./eval-env.types.js";
+
+/** Past this many names a function keeps the rest in an array. */
+export const INLINE_SLOTS = 3;
+
+/**
+ * A function call's own storage: one slot per name it binds.
+ *
+ * The compiler knows every name a function introduces, so a reference to one
+ * becomes a field read instead of a search. A name it does *not* introduce (a
+ * top-level binding, a namespace, the prelude) is a cell the closure resolved
+ * when it was built, which is an index into `up`.
+ *
+ * The first three slots are fields rather than an array because almost every
+ * function binds three names or fewer, and a frame plus an array is two
+ * allocations per call. Beyond three, `rest` holds the remainder.
+ *
+ * `lookup` stays because a name can still arrive as text: an expression inside
+ * `"${…}"` is compiled apart from the body that holds it, so it asks by name.
+ * Scanning a handful of parameters beats walking a chain of maps.
+ */
+export class Frame implements EvalEnv {
+  s0: unknown;
+  s1: unknown;
+  s2: unknown;
+  rest: unknown[] | undefined;
+  /** The cells this function's free names resolved to, in compile order. */
+  readonly up: readonly { value: unknown }[] | undefined;
+
+  constructor(readonly closure: Closure) {
+    const body = closure.body;
+    this.s0 = undefined;
+    this.s1 = undefined;
+    this.s2 = undefined;
+    this.rest = body.extra === 0 ? undefined : new Array<unknown>(body.extra);
+    this.up = closure.up;
+  }
+
+  lookup(name: string): unknown {
+    const at = this.closure.body.names.indexOf(name);
+    return at === -1 ? this.closure.env.lookup(name) : readSlot(this, at);
+  }
+}
+
+/** The slot at `at`, wherever it is held. */
+export function readSlot(frame: Frame, at: number): unknown {
+  if (at === 0) return frame.s0;
+  if (at === 1) return frame.s1;
+  if (at === 2) return frame.s2;
+  return (frame.rest as unknown[])[at - INLINE_SLOTS];
+}
+
+/** Write the slot at `at`. Used for the parameters and the body's locals. */
+export function writeSlot(frame: Frame, at: number, value: unknown): void {
+  if (at === 0) frame.s0 = value;
+  else if (at === 1) frame.s1 = value;
+  else if (at === 2) frame.s2 = value;
+  else (frame.rest as unknown[])[at - INLINE_SLOTS] = value;
+}

package/src/expr/index.ts

@@ -0,0 +1,14 @@
+export type { Cell, CellEnv } from "./cell.types.js";
+export { hasCells } from "./cell.types.js";
+export { childEnv, isClosure, makeClosure } from "./closure.js";
+export type { Closure } from "./closure.types.js";
+export type { EvalEnv } from "./eval-env.types.js";
+export { evaluate } from "./evaluate.js";
+export { callClosure, invoke, invoke1, isCallable } from "./invoke.js";
+export { memberValue } from "./member-value.js";
+export { isNamespaceValue, namespaceValue } from "./namespace.js";
+export { isNativeFn, type NativeFn, nativeFn } from "./native.types.js";
+export { applyBinary, negate, PLAIN } from "./operators.js";
+export { isWaiting, whenAllReady, whenBothReady, whenReady } from "./pending.js";
+export { display, PRELUDE_VALUES, typeName } from "./prelude.js";
+export { isTask, startTask, type Task } from "./task.js";

package/src/expr/invoke.ts

@@ -0,0 +1,140 @@
+import { buildProblem, CODES } from "../codes/index.js";
+import { ProblemError } from "../problem/index.js";
+import { isClosure } from "./closure.js";
+import type { Closure } from "./closure.types.js";
+import { Frame, writeSlot } from "./frame.js";
+import { type Invoke, isNativeFn } from "./native.types.js";
+
+const NO_SPAN = { uri: "", offset: 0, length: 0, line: 1, column: 1 };
+
+/**
+ * Call any Venn callable, a `fn` closure or a built-in method, with values.
+ *
+ * A callee declaring fewer parameters than it is handed ignores the rest.
+ *
+ * @throws ProblemError VN3013 when the value is not callable.
+ */
+export function invoke(callee: unknown, values: readonly unknown[]): unknown {
+  if (isClosure(callee)) return callClosure(callee, values);
+  if (isNativeFn(callee)) return callee.call(values);
+  throw notCallable(callee);
+}
+
+/** Whether {@link invoke} can call this, asked before committing to a call. */
+export function isCallable(value: unknown): boolean {
+  return isClosure(value) || isNativeFn(value);
+}
+
+/** The invoker handed to the built-in methods, fixed arities included. */
+export const INVOKE: Invoke = Object.assign(invoke, {
+  one: invoke1,
+  two: invoke2,
+  three: invoke3,
+});
+
+/**
+ * Call with a single value, without building an argument list for it.
+ *
+ * One argument is what most calls carry, and the array holding it would live
+ * exactly as long as the call takes to read it out again.
+ *
+ * @throws ProblemError VN3013 when the value is not callable.
+ */
+export function invoke1(callee: unknown, arg: unknown): unknown {
+  if (isClosure(callee)) return callClosure1(callee, arg);
+  if (isNativeFn(callee)) return callee.call([arg]);
+  throw notCallable(callee);
+}
+
+/**
+ * The same for two and three values, which is what the list methods hand over.
+ *
+ * `xs.map(fn (x) => …)` calls its function once per element, so an argument
+ * list would be one array per element built only to be taken apart again.
+ */
+export function invoke2(callee: unknown, a: unknown, b: unknown): unknown {
+  if (isClosure(callee)) return callClosure2(callee, a, b);
+  if (isNativeFn(callee)) return callee.call([a, b]);
+  throw notCallable(callee);
+}
+
+export function invoke3(callee: unknown, a: unknown, b: unknown, c: unknown): unknown {
+  if (isClosure(callee)) return callClosure3(callee, a, b, c);
+  if (isNativeFn(callee)) return callee.call([a, b, c]);
+  throw notCallable(callee);
+}
+
+/**
+ * Run a closure's compiled body against the given argument values.
+ *
+ * One allocation for the call: the frame itself. The names, the body and every
+ * expression in it were settled when the function was compiled.
+ *
+ * @returns The body's result, or a promise for it when the body reached
+ * something that has not arrived yet.
+ */
+export function callClosure(closure: Closure, values: readonly unknown[]): unknown {
+  if (closure.body.bare) return closure.body.result(values[0] as never);
+  const frame = new Frame(closure);
+  const arity = closure.params.length;
+  for (let at = 0; at < arity; at += 1) writeSlot(frame, at, values[at]);
+  return runBody(closure, frame);
+}
+
+/**
+ * The one-argument call.
+ *
+ * A body the compiler found needs no environment gets the value itself as one:
+ * its single name reads as `env`, so the call is the body running on the
+ * argument, with nothing allocated. That is most of what `map`, `filter` and
+ * `sortBy` call.
+ */
+function callClosure1(closure: Closure, value: unknown): unknown {
+  const body = closure.body;
+  if (body.bare) return body.result(value as never);
+  const frame = new Frame(closure);
+  if (closure.params.length > 0) frame.s0 = value;
+  return runBody(closure, frame);
+}
+
+// A function declaring fewer parameters than it is handed ignores the rest:
+// `xs.map(fn (x) => x)` never asks for the index it is offered.
+function callClosure2(closure: Closure, a: unknown, b: unknown): unknown {
+  if (closure.body.bare) return closure.body.result(a as never);
+  const frame = new Frame(closure);
+  const arity = closure.params.length;
+  if (arity > 0) frame.s0 = a;
+  if (arity > 1) frame.s1 = b;
+  return runBody(closure, frame);
+}
+
+function callClosure3(closure: Closure, a: unknown, b: unknown, c: unknown): unknown {
+  if (closure.body.bare) return closure.body.result(a as never);
+  const frame = new Frame(closure);
+  const arity = closure.params.length;
+  if (arity > 0) frame.s0 = a;
+  if (arity > 1) frame.s1 = b;
+  if (arity > 2) frame.s2 = c;
+  return runBody(closure, frame);
+}
+
+/** Fill the body's locals in order, then answer with its result. */
+function runBody(closure: Closure, frame: Frame): unknown {
+  const body = closure.body;
+  const locals = body.locals;
+  for (let at = 0; at < locals.length; at += 1) {
+    const local = locals[at] as (typeof locals)[number];
+    writeSlot(frame, local.slot, local.value(frame));
+  }
+  return body.result(frame);
+}
+
+function notCallable(value: unknown): ProblemError {
+  return new ProblemError(
+    buildProblem({
+      spec: CODES.VN3013_NOT_CALLABLE,
+      span: NO_SPAN,
+      title: `This value is not a function, so it cannot be called: ${typeof value}.`,
+    }),
+  );
+}

package/src/expr/member-value.ts

@@ -0,0 +1,91 @@
+import { isUnitValue } from "../units/index.js";
+import { INVOKE } from "./invoke.js";
+import { builtinMember, NO_METHOD } from "./methods/index.js";
+import { nativeFn } from "./native.types.js";
+import { isWaiting } from "./pending.js";
+import { isTask } from "./task.js";
+
+/**
+ * One member of a value: `xs.len`, `m.user`, `target.wrap`.
+ *
+ * A map's own data wins; a list or a string only ever has built-in members.
+ * Lives here rather than in the compiler because the compiler is not the only
+ * reader: a decorator body reaches a handle's verbs by the same rule, and two
+ * spellings of "what does `.x` mean" would drift apart.
+ *
+ * @returns The member's value, undefined when there is none, or a promise when
+ * the receiver has not arrived yet.
+ */
+export function memberValue(receiver: unknown, member: string): unknown {
+  if (isWaiting(receiver)) return receiver.then((ready) => memberValue(ready, member));
+  // A unit is not a map. Reading it as one would expose how it is stored, with
+  // `300ms.kind` answering "duration", and shadow its own conversions.
+  if (isData(receiver) && Object.hasOwn(receiver as object, member)) {
+    const data = own(receiver, member);
+    if (data !== undefined) return data;
+  }
+  const built = builtinMember(receiver, member, INVOKE);
+  if (built !== NO_METHOD) return built;
+  return isOwned(receiver) ? undefined : own(receiver, member);
+}
+
+/**
+ * Whether the language, not the host, decides what this value answers to.
+ *
+ * A list and a string are the language's own, with a published member set and a
+ * checker that knows it, so they must never fall through to the host: nothing
+ * the runtime happens to store them as is offered by the editor or checked, and
+ * it would stop working the day either value is held differently. A plugin's
+ * handle is the opposite case, being a host object whose published verbs are
+ * exactly what it answers to.
+ */
+const OWNED = new Set(["string", "number", "boolean", "bigint"]);
+
+function isOwned(receiver: unknown): boolean {
+  return (
+    receiver == null ||
+    OWNED.has(typeof receiver) ||
+    Array.isArray(receiver) ||
+    isUnitValue(receiver) ||
+    isTask(receiver) ||
+    isPlainMap(receiver)
+  );
+}
+
+/**
+ * A map the language made, as against an object a plugin handed over.
+ *
+ * Both are objects, so the line is drawn where it can be: a map literal
+ * inherits from nothing but `Object`, while a handle is built by the host and
+ * carries its verbs on its own prototype. Only what a map itself holds is its
+ * data; what every object in the runtime inherits is not.
+ */
+function isPlainMap(receiver: unknown): boolean {
+  if (typeof receiver !== "object" || receiver === null) return false;
+  const proto = Object.getPrototypeOf(receiver);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * A property of a host value, callable if it is a method.
+ *
+ * This is the boundary a plugin's handle crosses to become a value in the
+ * language. The wrapping is required: a bare host function is not a Venn
+ * callable, and the receiver has to be bound or `api.close()` loses its `this`.
+ */
+function own(receiver: unknown, member: string): unknown {
+  const value = (receiver as Record<string, unknown>)[member];
+  if (typeof value !== "function") return value;
+  const method = value as (...args: unknown[]) => unknown;
+  return nativeFn((values) => method.apply(receiver, [...values]));
+}
+
+function isData(receiver: unknown): boolean {
+  return (
+    receiver !== null &&
+    typeof receiver === "object" &&
+    !Array.isArray(receiver) &&
+    !isUnitValue(receiver) &&
+    !isTask(receiver)
+  );
+}

package/src/expr/methods/index.ts

@@ -0,0 +1,65 @@
+import type { Invoke } from "../native.types.js";
+import { isTask, TASK_METHODS } from "../task.js";
+import { LIST_GROUPING } from "./list-grouping.js";
+import { LIST_METHODS } from "./list-methods.js";
+import { LIST_SELECTION } from "./list-selection.js";
+import { MAP_EXTRAS } from "./map-extras.js";
+import { MAP_METHODS } from "./map-methods.js";
+import { NUMBER_METHODS } from "./number-methods.js";
+import { STRING_EXTRAS } from "./string-extras.js";
+import { STRING_METHODS } from "./string-methods.js";
+import { DURATION_METHODS, NUMBER_TO_UNIT, PERCENT_METHODS, SIZE_METHODS } from "./unit-methods.js";
+
+/** Distinguishes "no such method" from a method that legitimately returns undefined. */
+export const NO_METHOD = Symbol("venn.no-method");
+
+const LIST_TABLE = { ...LIST_METHODS, ...LIST_SELECTION, ...LIST_GROUPING };
+const STRING_TABLE = { ...STRING_METHODS, ...STRING_EXTRAS };
+const MAP_TABLE = { ...MAP_METHODS, ...MAP_EXTRAS };
+const NUMBER_TABLE = { ...NUMBER_METHODS, ...NUMBER_TO_UNIT };
+
+/** Every member name a value of this kind answers to. Read by the editor. */
+export const MEMBER_NAMES: Readonly<Record<string, readonly string[]>> = {
+  list: Object.keys(LIST_TABLE),
+  string: Object.keys(STRING_TABLE),
+  map: Object.keys(MAP_TABLE),
+  number: Object.keys(NUMBER_TABLE),
+  task: Object.keys(TASK_METHODS),
+  duration: Object.keys(DURATION_METHODS),
+  size: Object.keys(SIZE_METHODS),
+  percent: Object.keys(PERCENT_METHODS),
+};
+
+/**
+ * The built-in member of a native value: a property like `length` or a callable
+ * like `map`. `NO_METHOD` when the type has no such member, so the caller can
+ * fall back to a map's own data.
+ */
+export function builtinMember(receiver: unknown, member: string, invoke: Invoke): unknown {
+  const table = tableFor(receiver);
+  // These tables are ordinary objects, so a plain lookup would also reach what
+  // every object inherits: `x.toString` would find `Object.prototype.toString`
+  // and answer for a member the language never had. Only what a table declares
+  // is a member.
+  if (!table || !Object.hasOwn(table, member)) return NO_METHOD;
+  const method = table[member];
+  if (!method) return NO_METHOD;
+  return (method as (r: unknown, i: Invoke) => unknown)(receiver, invoke);
+}
+
+const UNIT_TABLES: Record<string, Record<string, unknown>> = {
+  duration: DURATION_METHODS,
+  size: SIZE_METHODS,
+  percent: PERCENT_METHODS,
+};
+
+function tableFor(receiver: unknown): Record<string, unknown> | undefined {
+  if (typeof receiver === "string") return STRING_TABLE;
+  if (typeof receiver === "number") return NUMBER_TABLE;
+  if (Array.isArray(receiver)) return LIST_TABLE;
+  if (receiver === null || typeof receiver !== "object") return undefined;
+  if (isTask(receiver)) return TASK_METHODS;
+  // A unit value carries its kind, and its methods are the way back to a number.
+  const kind = (receiver as { kind?: unknown }).kind;
+  return (typeof kind === "string" ? UNIT_TABLES[kind] : undefined) ?? MAP_TABLE;
+}

package/src/expr/methods/list-grouping.ts

@@ -0,0 +1,107 @@
+import { type Invoke, type Method, nativeFn } from "../native.types.js";
+
+type Dict = Record<string, unknown>;
+
+/**
+ * A grouping key: what `groupBy`, `countBy` and `keyBy` file an item under.
+ *
+ * A number or a boolean converts directly; only a shape is serialised. Passing
+ * scalars through `JSON.stringify` would be both slower and wrong, since it
+ * renders `Infinity` and `NaN` as `null` and would file them alongside items
+ * whose key genuinely is null.
+ */
+function key(value: unknown): string {
+  const kind = typeof value;
+  if (kind === "string") return value as string;
+  if (kind === "number" || kind === "boolean") return String(value);
+  // `JSON.stringify` answers `undefined` (not a string) for undefined and for a
+  // function, so anything it cannot render is named rather than cast.
+  return JSON.stringify(value) ?? String(value);
+}
+
+/**
+ * The operations that are a chore to hand-roll everywhere else: grouping,
+ * partitioning, keying, counting. Each returns a new value and never mutates.
+ */
+export const LIST_GROUPING: Record<string, Method> = {
+  groupBy: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => group(list, (item, i) => key(invoke.two(args[0], item, i)))),
+  countBy: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => counts(list, (item, i) => key(invoke.two(args[0], item, i)))),
+  keyBy: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => keyed(list, (item, i) => key(invoke.two(args[0], item, i)))),
+  partition: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => split(list, (item, i) => Boolean(invoke.two(args[0], item, i)))),
+  chunk: (list: readonly unknown[]) => nativeFn((args) => chunk(list, Number(args[0] ?? 1))),
+  windows: (list: readonly unknown[]) => nativeFn((args) => windows(list, Number(args[0] ?? 2))),
+  pairwise: (list: readonly unknown[]) => windows(list, 2),
+  zip: (list: readonly unknown[]) => nativeFn((args) => zip(list, asList(args[0]))),
+  unzip: (list: readonly unknown[]) => unzip(list),
+};
+
+function group(list: readonly unknown[], keyOf: (item: unknown, i: number) => string): Dict {
+  const out: Dict = {};
+  list.forEach((item, index) => {
+    const name = keyOf(item, index);
+    out[name] = [...((out[name] as unknown[]) ?? []), item];
+  });
+  return out;
+}
+
+function counts(list: readonly unknown[], keyOf: (item: unknown, i: number) => string): Dict {
+  const out: Dict = {};
+  list.forEach((item, index) => {
+    const name = keyOf(item, index);
+    out[name] = Number(out[name] ?? 0) + 1;
+  });
+  return out;
+}
+
+/** Like `groupBy`, but the last item under a key wins: an index, not buckets. */
+function keyed(list: readonly unknown[], keyOf: (item: unknown, i: number) => string): Dict {
+  const out: Dict = {};
+  list.forEach((item, index) => {
+    out[keyOf(item, index)] = item;
+  });
+  return out;
+}
+
+function split(list: readonly unknown[], keep: (item: unknown, i: number) => boolean): unknown[][] {
+  const yes: unknown[] = [];
+  const no: unknown[] = [];
+  list.forEach((item, index) => {
+    (keep(item, index) ? yes : no).push(item);
+  });
+  return [yes, no];
+}
+
+function chunk(list: readonly unknown[], size: number): unknown[][] {
+  const step = Math.max(1, Math.trunc(size));
+  const out: unknown[][] = [];
+  for (let index = 0; index < list.length; index += step) out.push(list.slice(index, index + step));
+  return out;
+}
+
+/** Every consecutive run of `size` items: `[1,2,3].windows(2)` gives `[[1,2],[2,3]]`. */
+function windows(list: readonly unknown[], size: number): unknown[][] {
+  const width = Math.max(1, Math.trunc(size));
+  const out: unknown[][] = [];
+  for (let index = 0; index + width <= list.length; index += 1) {
+    out.push(list.slice(index, index + width));
+  }
+  return out;
+}
+
+function zip(list: readonly unknown[], other: readonly unknown[]): unknown[][] {
+  return list.slice(0, Math.min(list.length, other.length)).map((item, i) => [item, other[i]]);
+}
+
+function unzip(list: readonly unknown[]): unknown[][] {
+  const pairs = list.map((item) => (Array.isArray(item) ? item : [item]));
+  const width = pairs.reduce((most, pair) => Math.max(most, pair.length), 0);
+  return Array.from({ length: width }, (_column, index) => pairs.map((pair) => pair[index]));
+}
+
+function asList(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}

package/src/expr/methods/list-methods.ts

@@ -0,0 +1,57 @@
+import { truthy } from "../../value/index.js";
+import { type Invoke, type Method, nativeFn } from "../native.types.js";
+
+/** How `sort` orders when given no comparator: numbers by value, else by text. */
+function compare(a: unknown, b: unknown): number {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
+}
+
+const at = (list: readonly unknown[], index: number): unknown => list[index] ?? null;
+
+/** Methods on a list value. Every one is pure and returns a new value. */
+export const LIST_METHODS: Record<string, Method> = {
+  len: (list: readonly unknown[]) => list.length,
+  first: (list: readonly unknown[]) => at(list, 0),
+  last: (list: readonly unknown[]) => at(list, list.length - 1),
+  map: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => list.map((item, i) => invoke.two(args[0], item, i))),
+  filter: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => list.filter((item, i) => truthy(invoke.two(args[0], item, i)))),
+  reduce: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => list.reduce((acc, item, i) => invoke.three(args[0], acc, item, i), args[1])),
+  forEach: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => {
+      list.forEach((item, i) => {
+        invoke.two(args[0], item, i);
+      });
+      return null;
+    }),
+  find: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => list.find((item, i) => truthy(invoke.two(args[0], item, i))) ?? null),
+  some: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => list.some((item, i) => truthy(invoke.two(args[0], item, i)))),
+  every: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) => list.every((item, i) => truthy(invoke.two(args[0], item, i)))),
+  contains: (list: readonly unknown[]) => nativeFn((args) => list.includes(args[0])),
+  indexOf: (list: readonly unknown[]) => nativeFn((args) => list.indexOf(args[0])),
+  reverse: (list: readonly unknown[]) => [...list].reverse(),
+  flatten: (list: readonly unknown[]) => list.flat(),
+  join: (list: readonly unknown[]) =>
+    nativeFn((args) => list.map(String).join(args[0] === undefined ? "," : String(args[0]))),
+  sort: (list: readonly unknown[], invoke: Invoke) =>
+    nativeFn((args) =>
+      args[0]
+        ? [...list].sort((a, b) => Number(invoke.two(args[0], a, b)))
+        : [...list].sort(compare),
+    ),
+  slice: (list: readonly unknown[]) =>
+    nativeFn((args) => list.slice(Number(args[0] ?? 0), end(args[1]))),
+  concat: (list: readonly unknown[]) =>
+    nativeFn((args) => [...list, ...(Array.isArray(args[0]) ? args[0] : [args[0]])]),
+  push: (list: readonly unknown[]) => nativeFn((args) => [...list, ...args]),
+};
+
+function end(value: unknown): number | undefined {
+  return value === undefined ? undefined : Number(value);
+}