@venn-lang/data 0.1.0

package/src/faker/datetime.ts

@@ -0,0 +1,102 @@
+import { optionalArg } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import type { Rng } from "../rng/index.js";
+import type { FakerSpec } from "./faker.types.js";
+import { intBetween, numArg, pad, pick } from "./primitives.js";
+
+/**
+ * The instant every generated date is measured from.
+ *
+ * Dates hang off a fixed anchor rather than the wall clock: `Date.now()` would
+ * give a different answer on every run and break the seeded replay guarantee.
+ */
+export const ANCHOR: number = Date.UTC(2025, 0, 1);
+
+const DAY = 86_400_000;
+const YEAR = 365 * DAY;
+
+const WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+const MONTHS = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December",
+];
+
+function offsetFrom(args: { rng: Rng; min: number; max: number }): number {
+  return ANCHOR + intBetween({ min: args.min, max: args.max, rng: args.rng });
+}
+
+/** `YYYY-MM-DD` within five years either side of the anchor. */
+function isoDate(rng: Rng): string {
+  const at = offsetFrom({ rng, min: -5 * YEAR, max: 5 * YEAR });
+  return new Date(at).toISOString().slice(0, 10);
+}
+
+function isoDateTime(rng: Rng): string {
+  return new Date(offsetFrom({ rng, min: -5 * YEAR, max: 5 * YEAR })).toISOString();
+}
+
+function pastDate(rng: Rng): string {
+  return new Date(offsetFrom({ rng, min: -5 * YEAR, max: -DAY })).toISOString();
+}
+
+function futureDate(rng: Rng): string {
+  return new Date(offsetFrom({ rng, min: DAY, max: 5 * YEAR })).toISOString();
+}
+
+/** `HH:MM:SS` on a 24-hour clock. */
+function time(rng: Rng): string {
+  const part = (max: number): string => pad(intBetween({ min: 0, max, rng }), 2);
+  return `${part(23)}:${part(59)}:${part(59)}`;
+}
+
+/** Seconds since the epoch, the unit `exp` and `iat` claims use. */
+function timestamp(rng: Rng): number {
+  return Math.floor(offsetFrom({ rng, min: -5 * YEAR, max: 5 * YEAR }) / 1000);
+}
+
+export const datetimeSpecs: readonly FakerSpec[] = [
+  { name: "date", doc: "A date as `YYYY-MM-DD`.", result: t.string, make: isoDate },
+  { name: "dateTime", doc: "An ISO 8601 instant.", result: t.string, make: isoDateTime },
+  {
+    name: "pastDate",
+    doc: "An ISO 8601 instant before the anchor.",
+    result: t.string,
+    make: pastDate,
+  },
+  {
+    name: "futureDate",
+    doc: "An ISO 8601 instant after the anchor.",
+    result: t.string,
+    make: futureDate,
+  },
+  { name: "time", doc: "A time of day as `HH:MM:SS`.", result: t.string, make: time },
+  { name: "timestamp", doc: "Seconds since the Unix epoch.", result: t.number, make: timestamp },
+  {
+    name: "weekday",
+    doc: "A day of the week.",
+    result: t.string,
+    make: (rng) => pick(WEEKDAYS, rng),
+  },
+  { name: "month", doc: "A month name.", result: t.string, make: (rng) => pick(MONTHS, rng) },
+  {
+    name: "year",
+    doc: "A year. `faker.year(2000, 2030)` bounds it.",
+    result: t.number,
+    args: [
+      optionalArg("from", t.number, "The earliest year, included."),
+      optionalArg("to", t.number, "The latest year, included."),
+    ],
+    make: (rng, args) =>
+      intBetween({ min: numArg(args, 0, 1980), max: numArg(args, 1, 2030), rng }),
+  },
+];

package/src/faker/faker.types.ts

@@ -0,0 +1,24 @@
+import type { ArgSpec } from "@venn-lang/sdk";
+import type { TypeSpec } from "@venn-lang/types";
+import type { Rng } from "../rng/index.js";
+
+/**
+ * One `data.faker.*` verb: what it is called, what it means, and how to draw a
+ * value. A spec is plain data, so the action wiring reads the list as it stands
+ * and needs no edit when a category grows.
+ */
+export interface FakerSpec {
+  /** The verb, without the namespace: `email`, `br.cpf`. */
+  name: string;
+  /** One line, in the user's domain. Shown on hover and in completion. */
+  doc: string;
+  /** The type it draws. A `TypeSpec`, not a name, so the checker can act on it. */
+  result: TypeSpec;
+  /**
+   * The positional arguments `make` reads, in order. Most verbs read none and
+   * leave this out. The action wiring turns it into the signature the checker sees.
+   */
+  args?: readonly ArgSpec[];
+  /** Draw a value. `args` carries the call's positional arguments, if any. */
+  make(rng: Rng, args: readonly unknown[]): unknown;
+}

package/src/faker/finance.ts

@@ -0,0 +1,86 @@
+import { t } from "@venn-lang/types";
+import type { Rng } from "../rng/index.js";
+import { ibanCheck, luhnDigit } from "./check-digits.js";
+import { CARD_BRANDS, CURRENCIES } from "./data/index.js";
+import type { FakerSpec } from "./faker.types.js";
+import { chars, digits, floatBetween, intBetween, pad, pick } from "./primitives.js";
+
+/** A 16-digit card number that passes Luhn, grouped `#### #### #### ####`. */
+function creditCard(rng: Rng): string {
+  const [, prefix, length] = pick(CARD_BRANDS, rng);
+  const base = `${prefix}${digits(length - prefix.length - 1, rng)}`;
+  const full = `${base}${luhnDigit(base)}`;
+  return (full.match(/.{1,4}/g) ?? []).join(" ");
+}
+
+function expiryDate(rng: Rng): string {
+  const month = intBetween({ min: 1, max: 12, rng });
+  return `${pad(month, 2)}/${intBetween({ min: 26, max: 34, rng })}`;
+}
+
+/** An IBAN with correct mod-97 check digits. */
+function iban(rng: Rng): string {
+  const country = "DE";
+  const account = digits(18, rng);
+  return `${country}${ibanCheck(country, account)}${account}`;
+}
+
+function bic(rng: Rng): string {
+  const letters = (count: number): string =>
+    chars({ count, alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ", rng });
+  return `${letters(4)}${letters(2)}${letters(2)}`;
+}
+
+export const financeSpecs: readonly FakerSpec[] = [
+  {
+    name: "creditCard",
+    doc: "A 16-digit card number that passes the Luhn check.",
+    result: t.string,
+    make: creditCard,
+  },
+  {
+    name: "cardType",
+    doc: "A card brand, like `Visa`.",
+    result: t.string,
+    make: (rng) => pick(CARD_BRANDS, rng)[0],
+  },
+  {
+    name: "cvv",
+    doc: "A three-digit card security code.",
+    result: t.string,
+    make: (rng) => digits(3, rng),
+  },
+  { name: "expiryDate", doc: "A card expiry as `MM/YY`.", result: t.string, make: expiryDate },
+  { name: "iban", doc: "An IBAN with valid check digits.", result: t.string, make: iban },
+  { name: "bic", doc: "A SWIFT/BIC code.", result: t.string, make: bic },
+  {
+    name: "accountNumber",
+    doc: "A bank account number.",
+    result: t.string,
+    make: (rng) => digits(10, rng),
+  },
+  {
+    name: "currencyCode",
+    doc: "An ISO 4217 currency code, like `BRL`.",
+    result: t.string,
+    make: (rng) => pick(CURRENCIES, rng)[0],
+  },
+  {
+    name: "currencySymbol",
+    doc: "A currency symbol, like `R$`.",
+    result: t.string,
+    make: (rng) => pick(CURRENCIES, rng)[1],
+  },
+  {
+    name: "currencyName",
+    doc: "A currency name, like `Brazilian Real`.",
+    result: t.string,
+    make: (rng) => pick(CURRENCIES, rng)[2],
+  },
+  {
+    name: "amount",
+    doc: "A monetary amount with two decimal places.",
+    result: t.number,
+    make: (rng) => floatBetween({ min: 1, max: 10000, decimals: 2, rng }),
+  },
+];

package/src/faker/ids.ts

@@ -0,0 +1,80 @@
+import { optionalArg } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import type { Rng } from "../rng/index.js";
+import type { FakerSpec } from "./faker.types.js";
+import { ALNUM, chars, digits, floatBetween, HEX, intBetween, numArg } from "./primitives.js";
+
+/** An RFC 4122 v4 UUID. The version and variant bits are stamped, not drawn. */
+export function uuid(rng: Rng): string {
+  const hex = (count: number): string => chars({ count, alphabet: HEX, rng });
+  const variant = "89ab".charAt(Math.floor(rng() * 4));
+  return `${hex(8)}-${hex(4)}-4${hex(3)}-${variant}${hex(3)}-${hex(12)}`;
+}
+
+const NANO_ALPHABET = `${ALNUM}_-`;
+
+export const idSpecs: readonly FakerSpec[] = [
+  { name: "uuid", doc: "A v4 UUID.", result: t.string, make: uuid },
+  {
+    name: "nanoid",
+    doc: "A 21-character NanoID. `faker.nanoid(10)` sets the length.",
+    result: t.string,
+    args: [optionalArg("length", t.number, "How many characters. 21 by default.")],
+    make: (rng, args) => chars({ count: numArg(args, 0, 21), alphabet: NANO_ALPHABET, rng }),
+  },
+  {
+    name: "objectId",
+    doc: "A 24-character MongoDB ObjectId.",
+    result: t.string,
+    make: (rng) => chars({ count: 24, alphabet: HEX, rng }),
+  },
+  {
+    name: "hex",
+    doc: "Hex characters. `faker.hex(32)` sets how many.",
+    result: t.string,
+    args: [optionalArg("length", t.number, "How many characters.")],
+    make: (rng, args) => chars({ count: numArg(args, 0, 16), alphabet: HEX, rng }),
+  },
+  {
+    name: "token",
+    doc: "A 32-character opaque token.",
+    result: t.string,
+    make: (rng) => chars({ count: 32, alphabet: ALNUM, rng }),
+  },
+  {
+    name: "alphanumeric",
+    doc: "Letters and digits. `faker.alphanumeric(8)` sets how many.",
+    result: t.string,
+    args: [optionalArg("length", t.number, "How many characters.")],
+    make: (rng, args) => chars({ count: numArg(args, 0, 8), alphabet: ALNUM, rng }),
+  },
+  {
+    name: "digits",
+    doc: "Decimal digits. `faker.digits(6)` sets how many.",
+    result: t.string,
+    args: [optionalArg("length", t.number, "How many digits.")],
+    make: (rng, args) => digits(numArg(args, 0, 6), rng),
+  },
+  {
+    name: "int",
+    doc: "An integer. `faker.int(1, 10)` bounds it, inclusive.",
+    result: t.number,
+    args: [
+      optionalArg("min", t.number, "The lowest it may be, included."),
+      optionalArg("max", t.number, "The highest it may be, included."),
+    ],
+    make: (rng, args) => intBetween({ min: numArg(args, 0, 0), max: numArg(args, 1, 100), rng }),
+  },
+  {
+    name: "float",
+    doc: "A number with two decimals. `faker.float(0, 1)` bounds it.",
+    result: t.number,
+    args: [
+      optionalArg("min", t.number, "The lowest it may be."),
+      optionalArg("max", t.number, "The highest it may be."),
+    ],
+    make: (rng, args) =>
+      floatBetween({ min: numArg(args, 0, 0), max: numArg(args, 1, 1), decimals: 2, rng }),
+  },
+  { name: "boolean", doc: "`true` or `false`.", result: t.bool, make: (rng) => rng() < 0.5 },
+];

package/src/faker/index.ts

@@ -0,0 +1,8 @@
+export { allFakerSpecs } from "./all-specs.js";
+export { cnpjDigits, cpfDigits } from "./brazil-documents.js";
+export { eanDigit, ibanCheck, luhnDigit } from "./check-digits.js";
+export { ANCHOR } from "./datetime.js";
+export type { FakerSpec } from "./faker.types.js";
+export { uuid } from "./ids.js";
+export { email } from "./internet.js";
+export { firstName, fullName, lastName } from "./person.js";

package/src/faker/internet.ts

@@ -0,0 +1,100 @@
+import { t } from "@venn-lang/types";
+import type { Rng } from "../rng/index.js";
+import {
+  ADJECTIVES,
+  HTTP_METHODS,
+  HTTP_STATUSES,
+  MIME_TYPES,
+  NOUNS,
+  PROTOCOLS,
+  SAFE_DOMAINS,
+  TLDS,
+  USER_AGENTS,
+} from "./data/index.js";
+import type { FakerSpec } from "./faker.types.js";
+import { firstName, lastName } from "./person.js";
+import { ALNUM, chars, digits, HEX, intBetween, pick, slug } from "./primitives.js";
+
+/** An email on a reserved domain, e.g. `"grace.hopper@example.test"`. It reaches nobody. */
+export function email(rng: Rng): string {
+  const local = `${slug(firstName(rng))}.${slug(lastName(rng))}`;
+  return `${local}@${pick(SAFE_DOMAINS, rng)}`;
+}
+
+function username(rng: Rng): string {
+  return `${slug(firstName(rng))}${intBetween({ min: 1, max: 99, rng })}`;
+}
+
+function password(rng: Rng): string {
+  return chars({ count: 14, alphabet: `${ALNUM}!@#$%&*?`, rng });
+}
+
+function domain(rng: Rng): string {
+  return `${pick(ADJECTIVES, rng)}${pick(NOUNS, rng)}.${pick(TLDS, rng)}`;
+}
+
+function url(rng: Rng): string {
+  return `${pick(PROTOCOLS, rng)}://${domain(rng)}/${pick(NOUNS, rng)}`;
+}
+
+function ipv4(rng: Rng): string {
+  const octet = (): number => intBetween({ min: 1, max: 254, rng });
+  return `${octet()}.${octet()}.${octet()}.${octet()}`;
+}
+
+function ipv6(rng: Rng): string {
+  const group = (): string => chars({ count: 4, alphabet: HEX, rng });
+  return Array.from({ length: 8 }, group).join(":");
+}
+
+function mac(rng: Rng): string {
+  const pair = (): string => chars({ count: 2, alphabet: HEX, rng }).toUpperCase();
+  return Array.from({ length: 6 }, pair).join(":");
+}
+
+export const internetSpecs: readonly FakerSpec[] = [
+  { name: "email", doc: "An email address on a reserved domain.", result: t.string, make: email },
+  { name: "username", doc: "A login name.", result: t.string, make: username },
+  { name: "password", doc: "A 14-character password.", result: t.string, make: password },
+  { name: "domain", doc: "A domain name.", result: t.string, make: domain },
+  { name: "url", doc: "An absolute URL.", result: t.string, make: url },
+  { name: "ipv4", doc: "An IPv4 address.", result: t.string, make: ipv4 },
+  { name: "ipv6", doc: "An IPv6 address.", result: t.string, make: ipv6 },
+  { name: "mac", doc: "A MAC address.", result: t.string, make: mac },
+  {
+    name: "port",
+    doc: "An unprivileged TCP port.",
+    result: t.number,
+    make: (rng) => intBetween({ min: 1024, max: 65535, rng }),
+  },
+  {
+    name: "userAgent",
+    doc: "A browser User-Agent string.",
+    result: t.string,
+    make: (rng) => pick(USER_AGENTS, rng),
+  },
+  {
+    name: "slug",
+    doc: "A URL slug, like `bright-harbour-417`.",
+    result: t.string,
+    make: (rng) => `${pick(ADJECTIVES, rng)}-${pick(NOUNS, rng)}-${digits(3, rng)}`,
+  },
+  {
+    name: "httpMethod",
+    doc: "An HTTP verb.",
+    result: t.string,
+    make: (rng) => pick(HTTP_METHODS, rng),
+  },
+  {
+    name: "httpStatus",
+    doc: "An HTTP status code that servers really return.",
+    result: t.number,
+    make: (rng) => pick(HTTP_STATUSES, rng),
+  },
+  {
+    name: "mimeType",
+    doc: "A MIME type.",
+    result: t.string,
+    make: (rng) => pick(MIME_TYPES, rng),
+  },
+];

package/src/faker/person.ts

@@ -0,0 +1,88 @@
+import { t } from "@venn-lang/types";
+import type { Rng } from "../rng/index.js";
+import {
+  FIRST_NAMES,
+  GENDERS,
+  JOB_TITLES,
+  LAST_NAMES,
+  NAME_PREFIXES,
+  NAME_SUFFIXES,
+} from "./data/index.js";
+import type { FakerSpec } from "./faker.types.js";
+import { digits, intBetween, pad, pick } from "./primitives.js";
+
+/** A given name, e.g. `"Grace"`. */
+export function firstName(rng: Rng): string {
+  return pick(FIRST_NAMES, rng);
+}
+
+/** A family name, e.g. `"Hopper"`. */
+export function lastName(rng: Rng): string {
+  return pick(LAST_NAMES, rng);
+}
+
+/** A full name, e.g. `"Grace Hopper"`. */
+export function fullName(rng: Rng): string {
+  return `${firstName(rng)} ${lastName(rng)}`;
+}
+
+function birthDate(rng: Rng): string {
+  const year = intBetween({ min: 1950, max: 2006, rng });
+  const month = intBetween({ min: 1, max: 12, rng });
+  const day = intBetween({ min: 1, max: 28, rng });
+  return `${year}-${pad(month, 2)}-${pad(day, 2)}`;
+}
+
+/** `+1 555 01xx`, the range reserved for fiction, so it can never reach anyone. */
+function phone(rng: Rng): string {
+  return `+1 555 01${digits(2, rng)}`;
+}
+
+export const personSpecs: readonly FakerSpec[] = [
+  { name: "firstName", doc: "A given name.", result: t.string, make: firstName },
+  { name: "lastName", doc: "A family name.", result: t.string, make: lastName },
+  { name: "name", doc: "A full name.", result: t.string, make: fullName },
+  { name: "fullName", doc: "A full name.", result: t.string, make: fullName },
+  {
+    name: "prefix",
+    doc: "An honorific that precedes a name, like `Dra.`.",
+    result: t.string,
+    make: (rng) => pick(NAME_PREFIXES, rng),
+  },
+  {
+    name: "suffix",
+    doc: "A generational suffix that follows a name, like `Neto`.",
+    result: t.string,
+    make: (rng) => pick(NAME_SUFFIXES, rng),
+  },
+  {
+    name: "gender",
+    doc: "A gender value shaped the way most forms model them.",
+    result: t.string,
+    make: (rng) => pick(GENDERS, rng),
+  },
+  {
+    name: "jobTitle",
+    doc: "A job title, like `Site Reliability Engineer`.",
+    result: t.string,
+    make: (rng) => pick(JOB_TITLES, rng),
+  },
+  {
+    name: "age",
+    doc: "An adult age, between 18 and 80.",
+    result: t.number,
+    make: (rng) => intBetween({ min: 18, max: 80, rng }),
+  },
+  {
+    name: "birthDate",
+    doc: "A birth date as `YYYY-MM-DD`.",
+    result: t.string,
+    make: birthDate,
+  },
+  {
+    name: "phone",
+    doc: "An international phone number in the range reserved for fiction.",
+    result: t.string,
+    make: phone,
+  },
+];

package/src/faker/primitives.ts

@@ -0,0 +1,77 @@
+import type { Rng } from "../rng/index.js";
+
+const COMBINING = /[\u0300-\u036f]/g;
+
+export const DIGITS = "0123456789";
+export const HEX = "0123456789abcdef";
+export const LOWER = "abcdefghijklmnopqrstuvwxyz";
+export const ALNUM: string = `${LOWER}${LOWER.toUpperCase()}${DIGITS}`;
+
+/** Pick one item from a list. Drawing from an empty list is a programming error. */
+export function pick<T>(items: readonly T[], rng: Rng): T {
+  const chosen = items[Math.floor(rng() * items.length)];
+  if (chosen === undefined) throw new Error("faker: cannot pick from an empty list");
+  return chosen;
+}
+
+/** An integer in the inclusive range [min, max]. */
+export function intBetween(args: { min: number; max: number; rng: Rng }): number {
+  return args.min + Math.floor(args.rng() * (args.max - args.min + 1));
+}
+
+/** A number in [min, max), rounded to `decimals` places. */
+export function floatBetween(args: {
+  min: number;
+  max: number;
+  decimals: number;
+  rng: Rng;
+}): number {
+  const raw = args.min + args.rng() * (args.max - args.min);
+  return Number(raw.toFixed(args.decimals));
+}
+
+/** `count` characters drawn from `alphabet`. */
+export function chars(args: { count: number; alphabet: string; rng: Rng }): string {
+  let out = "";
+  for (let index = 0; index < args.count; index += 1) {
+    out += args.alphabet.charAt(Math.floor(args.rng() * args.alphabet.length));
+  }
+  return out;
+}
+
+/** `count` decimal digits, e.g. `"40721"`. */
+export function digits(count: number, rng: Rng): string {
+  return chars({ count, alphabet: DIGITS, rng });
+}
+
+/** Upper-case the first character, leaving the rest alone. */
+export function capitalize(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+/** Zero-pad a number to `width` digits. */
+export function pad(value: number, width: number): string {
+  return String(value).padStart(width, "0");
+}
+
+/** Strip diacritics so a name can become an email local part or a URL slug. */
+export function ascii(text: string): string {
+  return text.normalize("NFD").replace(COMBINING, "");
+}
+
+/** ASCII-safe lowercase slug: `"João Gonçalves"` → `"joao-goncalves"`. */
+export function slug(text: string): string {
+  const plain = ascii(text).toLowerCase();
+  return plain.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+/** Read a positional argument as a number, falling back when it is absent. */
+export function numArg(args: readonly unknown[], index: number, fallback: number): number {
+  const raw = Number(args[index]);
+  return args[index] === undefined || Number.isNaN(raw) ? fallback : raw;
+}
+
+/** Build `count` values, each drawn independently. */
+export function times<T>(count: number, make: () => T): T[] {
+  return Array.from({ length: count }, make);
+}

package/src/faker/text.ts

@@ -0,0 +1,56 @@
+import { optionalArg } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import type { Rng } from "../rng/index.js";
+import { ADJECTIVES, LOREM, NOUNS } from "./data/index.js";
+import type { FakerSpec } from "./faker.types.js";
+import { capitalize, intBetween, numArg, pick, times } from "./primitives.js";
+
+function words(rng: Rng, count: number): string {
+  return times(count, () => pick(LOREM, rng)).join(" ");
+}
+
+/** A capitalised sentence of 6 to 14 words, ending in a full stop. */
+function sentence(rng: Rng): string {
+  return `${capitalize(words(rng, intBetween({ min: 6, max: 14, rng })))}.`;
+}
+
+function sentences(rng: Rng, count: number): string {
+  return times(count, () => sentence(rng)).join(" ");
+}
+
+function paragraph(rng: Rng): string {
+  return sentences(rng, intBetween({ min: 3, max: 6, rng }));
+}
+
+/** A headline in title case, e.g. `"Bright Harbour"`. */
+function title(rng: Rng): string {
+  return `${capitalize(pick(ADJECTIVES, rng))} ${capitalize(pick(NOUNS, rng))}`;
+}
+
+export const textSpecs: readonly FakerSpec[] = [
+  { name: "word", doc: "A single word.", result: t.string, make: (rng) => pick(LOREM, rng) },
+  {
+    name: "words",
+    doc: "Several words. `faker.words(5)` sets how many.",
+    result: t.string,
+    args: [optionalArg("count", t.number, "How many words.")],
+    make: (rng, args) => words(rng, numArg(args, 0, 3)),
+  },
+  { name: "sentence", doc: "One sentence.", result: t.string, make: sentence },
+  {
+    name: "sentences",
+    doc: "Several sentences. `faker.sentences(3)` sets how many.",
+    result: t.string,
+    args: [optionalArg("count", t.number, "How many sentences.")],
+    make: (rng, args) => sentences(rng, numArg(args, 0, 3)),
+  },
+  { name: "paragraph", doc: "One paragraph.", result: t.string, make: paragraph },
+  {
+    name: "paragraphs",
+    doc: "Several paragraphs, separated by blank lines. `faker.paragraphs(4)` sets how many.",
+    result: t.string,
+    args: [optionalArg("count", t.number, "How many paragraphs.")],
+    make: (rng, args) => times(numArg(args, 0, 2), () => paragraph(rng)).join("\n\n"),
+  },
+  { name: "title", doc: "A short headline in title case.", result: t.string, make: title },
+];

package/src/index.ts

@@ -0,0 +1,8 @@
+// @venn-lang/data: pure, deterministic test-data generators (faker, oneOf, range,
+// shuffle, csv, json). A module-level mulberry32 PRNG (seed 1) keeps output reproducible.
+
+export { dataActions } from "./actions/index.js";
+export * from "./csv/index.js";
+export * from "./faker/index.js";
+export { dataPlugin, dataPlugin as default } from "./plugin.js";
+export * from "./rng/index.js";

package/src/plugin.ts

@@ -0,0 +1,17 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { dataActions } from "./actions/index.js";
+import { dataTypeDefs } from "./types.js";
+
+/**
+ * The `data` plugin: pure, deterministic test-data generators.
+ *
+ * Every verb draws from a seeded module-level PRNG, so the same script replays the
+ * same values. Nothing here does I/O, so there is no capability and no port to bind.
+ */
+export const dataPlugin: PluginDefinition = definePlugin({
+  name: "venn/data",
+  version: "0.0.0",
+  namespace: "data",
+  actions: dataActions,
+  typeDefs: dataTypeDefs,
+});

package/src/rng/index.ts

@@ -0,0 +1,4 @@
+export { mulberry32 } from "./mulberry32.js";
+export type { Rng } from "./rng.types.js";
+export { resetRng, rng } from "./shared-rng.js";
+export { shuffleWith } from "./shuffle.js";

package/src/rng/mulberry32.ts

@@ -0,0 +1,18 @@
+import type { Rng } from "./rng.types.js";
+
+/**
+ * Mulberry32: a tiny, fast, fully deterministic PRNG.
+ *
+ * @param seed Any number. It is coerced to a uint32, so the same seed always
+ * yields the same stream.
+ * @returns A generator producing the next float in [0, 1) on each call.
+ */
+export function mulberry32(seed: number): Rng {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}

package/src/rng/rng.types.ts

@@ -0,0 +1,2 @@
+/** A deterministic pseudo-random generator: each call yields the next float in [0, 1). */
+export type Rng = () => number;