@ghostry/fabricator-extension-faker-v10 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,22 @@
+<div align="center">
+
+<img src="https://docs.ghostry.dev/fabricator/logo.png" alt="fabricator" width="96" height="96">
+
 # @ghostry/fabricator-extension-faker-v10
 
-[`@faker-js/faker`](https://fakerjs.dev) integration for [`@ghostry/fabricator`](https://www.npmjs.com/package/@ghostry/fabricator). Faker's generators draw from the same seed as every other builder in a schema, so `T.faker.person.fullName()` replays exactly like `T.string` does — no second seed to track, no drift between runs.
+**Seeded faker generators for `@ghostry/fabricator`.**
+
+[![npm](https://img.shields.io/badge/npm-ffffff.svg?style=for-the-badge&color=000000&logo=npm&logoColor=CB3837)](https://www.npmjs.com/package/@ghostry/fabricator-extension-faker-v10)
+[![npmx](https://img.shields.io/badge/npmx-ffffff.svg?style=for-the-badge&color=000000&logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNTMiIGhlaWdodD0iMTUzIiB2ZXJzaW9uPSIxLjEiIHZpZXdCb3g9IjAgMCAxNTMgMTUzIj4KICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxNi43MDQgOS45ODI3KSI+CiAgICA8cGF0aCBkPSJtMC45MzQ3NiA5Ny4yMDVoMjQuMDgxdjIzLjY5M2gtMjQuMDgxeiIgZmlsbD0iI2ZmZiI+PC9wYXRoPgogICAgPHBhdGggZD0ibTEwMy4xMi05LjIzMDctMy42MjExIDEwLjI0Ni00Ni4zMDkgMTMxLTMuNjIxMSAxMC4yNDZoMTUuNTM3bDMuNjIxMS0xMC4yNDYgMTEuNzE3LTMzLjE0OCAzOC4yMTEtMTA4LjF6IiBmaWxsPSIjNTFjOGZjIj48L3BhdGg+CiAgPC9nPgo8L3N2Zz4K&logoColor=51C8FC)](https://npmx.dev/package/@ghostry/fabricator-extension-faker-v10)
+[![jsr](https://img.shields.io/badge/jsr-ffffff?style=for-the-badge&color=000000&logo=jsr&logoColor=F7DF1E)](https://jsr.io/@ghostry/fabricator-extension-faker-v10)
+[![github](https://img.shields.io/badge/github-ffffff?style=for-the-badge&color=000000&logo=github&logoColor=ffffff)](https://github.com/ghostry-dev/fabricator)
+[![typescript](https://img.shields.io/badge/typescript-ffffff?style=for-the-badge&color=000000&logo=typescript&logoColor=3178C6)](#)
+[![bun](https://img.shields.io/badge/bun-ffffff?style=for-the-badge&color=000000&logo=bun&logoColor=FBF0DF)](#)
+[![node](https://img.shields.io/badge/node-ffffff?style=for-the-badge&color=000000&logo=nodedotjs&logoColor=5FA04E)](#)
+
+</div>
+
+[`@faker-js/faker`](https://fakerjs.dev) integration for [`@ghostry/fabricator`](https://www.npmjs.com/package/@ghostry/fabricator). Faker's generators draw from the same stream as every other builder in a schema, so `T.faker.person.fullName()` replays exactly like `T.string` does — nothing additional to track, no drift between runs.
 
 Targets `@faker-js/faker` 10.x specifically — hence the `-v10` suffix, matching the adapter packages' convention. A future faker major is a sibling package with its own peer range, not a version bump of this one.
 
@@ -43,21 +59,21 @@ Faker's relative-date methods resolve against the same instance `clock` that `T.
 
 A faker method could have been wrapped as an opaque producer, and that is the one thing this package refuses to do — an `opaque` schema converts to `Type.Unknown()` in any adapter and is invisible to `combinatorial`/`coverage`. Each builder instead returns the core kind matching the method's own return type:
 
-| faker returns       | builder returns         | via the TypeBox adapter           |
-| ------------------- | ----------------------- | --------------------------------- |
-| `string` (207)      | `T.string`              | `Type.String()`                   |
-| `Date` (7)          | `T.date`                | `Type.Date()`                     |
-| a record shape (7)  | `T.object({ ... })`     | `Type.Object({ ... })`            |
-| a literal union (6) | `T.enum.uniform([...])` | `Type.Union([Type.Literal(), …])` |
-| `number` (6)        | `T.number`              | `Type.Number()`                   |
-| `boolean` (1)       | `T.boolean`             | `Type.Boolean()`                  |
-| `bigint` (1)        | `T.bigint`              | `Type.BigInt()`                   |
-| `number[]` (1)      | `T.array(T.number)`     | `Type.Array(Type.Number())`       |
-| `Date[]` (1)        | `T.array(T.date)`       | `Type.Array(Type.Date())`         |
+| faker returns          | builder returns                 | via the TypeBox adapter                      |
+| ---------------------- | ------------------------------- | -------------------------------------------- |
+| `string` (207)         | `T.string`                      | `Type.String()`                              |
+| `Date` (7)             | `T.date`                        | `Type.Date()`                                |
+| a record shape (7)     | `T.object({ ... })`             | `Type.Object({ ... })`                       |
+| a literal union (6)    | `T.enum.uniform([...])`         | `Type.Union([Type.Literal(), …])`            |
+| `number` (6)           | `T.number`                      | `Type.Number()`                              |
+| `boolean` (1)          | `T.boolean`                     | `Type.Boolean()`                             |
+| `bigint` (1)           | `T.bigint`                      | `Type.BigInt()`                              |
+| `[number, number]` (1) | `T.tuple([T.number, T.number])` | `Type.Tuple([Type.Number(), Type.Number()])` |
+| `Date[]` (1)           | `T.array(T.date)`               | `Type.Array(Type.Date())`                    |
 
 Seventeen string methods whose output satisfies a JSON-Schema format regardless of the options passed additionally carry it — `internet.email()` converts to `Type.String({ format: "email" })`, `database.mongodbObjectId()` to a `pattern`.
 
-The kind table is generated by probing a real `Faker`, and a compile-time assertion checks every entry's value type against faker's own declared return type — so a faker release that changes one fails `tsc` at that entry rather than silently emitting a wrong schema.
+The mirror is hand-written, not generated — one declaration per builder and one implementation, kept in agreement by the compiler. A compile-time assertion checks every entry's value type against faker's own declared return type, so a faker release that changes one fails `tsc` at that entry rather than silently emitting a wrong schema.
 
 ## Three deviations from faker's own API
 
@@ -75,7 +91,7 @@ T.faker.color.rgb.channels({ includeAlpha: true });
 
 The same applies to `cmyk`, `hsl`, `hwb`, `lab`, `lch`, and `colorByCSSColorSpace`. `color`'s other four methods are ordinary builders.
 
-**A method declared as a literal union becomes an `enum`, not a `string`.** `person.sexType()` gives `T.enum.uniform(["female", "generic", "male"])`, so it converts to a union of literals and is enumerable by `combinatorial`/`coverage` rather than an unconstrained string.
+**Where faker's declared return type is narrower than its JS type, the kind narrows with it.** A literal union becomes an `enum`, not a `string`: `person.sexType()` gives `T.enum.uniform(["female", "generic", "male"])`, so it converts to a union of literals and is enumerable by `combinatorial`/`coverage` rather than an unconstrained string. A fixed-arity array becomes a `tuple`, not an `array`: `location.nearbyGPSCoordinate()` gives `T.tuple([T.number, T.number])`, since no option can change its `[latitude, longitude]` arity — unlike the color channels above, which is why those stay `T.array`.
 
 ## `use` — for what the mirror doesn't cover
 
@@ -94,7 +110,7 @@ T.faker.use.opaque((f) => f.helpers.arrayElement(["free", "pro"] as const));
 
 ## Notes
 
-`faker.seed(...)` is inert here, by design: fabricator's seed governs, and a second one competing for control of the same output is the bug this package exists to remove. Pass a different `seed` to `initialize()` instead.
+`faker.seed(...)` is inert here, by design: fabricator's seeding governs, and a second one competing for control of the same output is the bug this package exists to remove. Change the instance's `clock` — or its `salt`, if it has one — instead.
 
 A builder called outside `fabricate()` throws `FakerExtensionError.NoActiveScopeError` — there is no active fabrication to draw from. `FakerExtensionError` extends core's `FabricatorError`, so one `catch` still covers both packages.
 

package/dist/esm/Error.js

@@ -2,14 +2,14 @@ import { FabricatorError } from "@ghostry/fabricator";
 class Error_FakerExtensionError extends FabricatorError {
     constructor(){
         super();
-        this.name = "FakerExtensionError";
+        this.name = "@ghostry/fabricator-extension-faker-v10:FakerExtensionError";
     }
 }
 (function(FakerExtensionError) {
     class NoActiveScopeError extends FakerExtensionError {
         constructor(){
             super();
-            this.name = "NoActiveScopeError";
+            this.name = "@ghostry/fabricator-extension-faker-v10:NoActiveScopeError";
             this.message = "A faker builder was invoked outside of fabricate(). Faker builders only draw randomness while the schema they belong to is being fabricated.";
         }
     }

package/dist/esm/FakerModules/Build.js

@@ -1,7 +1,9 @@
+import { toWords } from "./Words.js";
 function build(T, faker, draw) {
-    const [f, d] = [
+    const [f, d, w] = [
         faker,
-        draw
+        draw,
+        toWords(faker)
     ];
     const string = T.string.as(()=>"");
     return {
@@ -171,7 +173,7 @@ function build(T, faker, draw) {
             collation: (...args)=>T.string.as(d(()=>f.database.collation(...args))),
             column: (...args)=>T.string.as(d(()=>f.database.column(...args))),
             engine: (...args)=>T.string.as(d(()=>f.database.engine(...args))),
-            mongodbObjectId: (...args)=>T.string.as(d(()=>f.database.mongodbObjectId(...args)), {
+            mongodbObjectId: (...args)=>T.string.as(d(()=>f.database.mongodbObjectId(...args))).admits({
                     pattern: "^[0-9a-fA-F]{24}$"
                 }),
             type: (...args)=>T.string.as(d(()=>f.database.type(...args)))
@@ -196,11 +198,11 @@ function build(T, faker, draw) {
             accountName: (...args)=>T.string.as(d(()=>f.finance.accountName(...args))),
             accountNumber: (...args)=>T.string.as(d(()=>f.finance.accountNumber(...args))),
             amount: (...args)=>T.string.as(d(()=>f.finance.amount(...args))),
-            bic: (...args)=>T.string.as(d(()=>f.finance.bic(...args)), {
+            bic: (...args)=>T.string.as(d(()=>f.finance.bic(...args))).admits({
                     pattern: "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$"
                 }),
             bitcoinAddress: (...args)=>T.string.as(d(()=>f.finance.bitcoinAddress(...args))),
-            creditCardCVV: (...args)=>T.string.as(d(()=>f.finance.creditCardCVV(...args)), {
+            creditCardCVV: (...args)=>T.string.as(d(()=>f.finance.creditCardCVV(...args))).admits({
                     pattern: "^[0-9]{3,4}$"
                 }),
             creditCardIssuer: (...args)=>T.string.as(d(()=>f.finance.creditCardIssuer(...args))),
@@ -250,38 +252,38 @@ function build(T, faker, draw) {
             verb: (...args)=>T.string.as(d(()=>f.hacker.verb(...args)))
         },
         image: {
-            avatar: (...args)=>T.string.as(d(()=>f.image.avatar(...args)), {
+            avatar: (...args)=>T.string.as(d(()=>f.image.avatar(...args))).admits({
                     format: "uri"
                 }),
-            avatarGitHub: (...args)=>T.string.as(d(()=>f.image.avatarGitHub(...args)), {
+            avatarGitHub: (...args)=>T.string.as(d(()=>f.image.avatarGitHub(...args))).admits({
                     format: "uri"
                 }),
-            dataUri: (...args)=>T.string.as(d(()=>f.image.dataUri(...args)), {
+            dataUri: (...args)=>T.string.as(d(()=>f.image.dataUri(...args))).admits({
                     format: "uri"
                 }),
-            personPortrait: (...args)=>T.string.as(d(()=>f.image.personPortrait(...args)), {
+            personPortrait: (...args)=>T.string.as(d(()=>f.image.personPortrait(...args))).admits({
                     format: "uri"
                 }),
-            url: (...args)=>T.string.as(d(()=>f.image.url(...args)), {
+            url: (...args)=>T.string.as(d(()=>f.image.url(...args))).admits({
                     format: "uri"
                 }),
             urlLoremFlickr: (...args)=>T.string.as(d(()=>f.image.urlLoremFlickr(...args))),
-            urlPicsumPhotos: (...args)=>T.string.as(d(()=>f.image.urlPicsumPhotos(...args)), {
+            urlPicsumPhotos: (...args)=>T.string.as(d(()=>f.image.urlPicsumPhotos(...args))).admits({
                     format: "uri"
                 })
         },
         internet: {
             displayName: (...args)=>T.string.as(d(()=>f.internet.displayName(...args))),
-            domainName: (...args)=>T.string.as(d(()=>f.internet.domainName(...args)), {
+            domainName: (...args)=>T.string.as(d(()=>f.internet.domainName(...args))).admits({
                     format: "hostname"
                 }),
             domainSuffix: (...args)=>T.string.as(d(()=>f.internet.domainSuffix(...args))),
             domainWord: (...args)=>T.string.as(d(()=>f.internet.domainWord(...args))),
-            email: (...args)=>T.string.as(d(()=>f.internet.email(...args)), {
+            email: (...args)=>T.string.as(d(()=>f.internet.email(...args))).admits({
                     format: "email"
                 }),
             emoji: (...args)=>T.string.as(d(()=>f.internet.emoji(...args))),
-            exampleEmail: (...args)=>T.string.as(d(()=>f.internet.exampleEmail(...args)), {
+            exampleEmail: (...args)=>T.string.as(d(()=>f.internet.exampleEmail(...args))).admits({
                     format: "email"
                 }),
             httpMethod: (...args)=>T.enum.uniform([
@@ -293,10 +295,10 @@ function build(T, faker, draw) {
                 ]).as(d(()=>f.internet.httpMethod(...args))),
             httpStatusCode: (...args)=>T.number.as(d(()=>f.internet.httpStatusCode(...args))),
             ip: (...args)=>T.string.as(d(()=>f.internet.ip(...args))),
-            ipv4: (...args)=>T.string.as(d(()=>f.internet.ipv4(...args)), {
+            ipv4: (...args)=>T.string.as(d(()=>f.internet.ipv4(...args))).admits({
                     format: "ipv4"
                 }),
-            ipv6: (...args)=>T.string.as(d(()=>f.internet.ipv6(...args)), {
+            ipv6: (...args)=>T.string.as(d(()=>f.internet.ipv6(...args))).admits({
                     format: "ipv6"
                 }),
             jwt: (...args)=>T.string.as(d(()=>f.internet.jwt(...args))),
@@ -308,7 +310,7 @@ function build(T, faker, draw) {
                     "http",
                     "https"
                 ]).as(d(()=>f.internet.protocol(...args))),
-            url: (...args)=>T.string.as(d(()=>f.internet.url(...args)), {
+            url: (...args)=>T.string.as(d(()=>f.internet.url(...args))).admits({
                     format: "uri"
                 }),
             userAgent: (...args)=>T.string.as(d(()=>f.internet.userAgent(...args))),
@@ -344,15 +346,15 @@ function build(T, faker, draw) {
             zipCode: (...args)=>T.string.as(d(()=>f.location.zipCode(...args)))
         },
         lorem: {
-            lines: (...args)=>T.string.as(d(()=>f.lorem.lines(...args))),
-            paragraph: (...args)=>T.string.as(d(()=>f.lorem.paragraph(...args))),
-            paragraphs: (...args)=>T.string.as(d(()=>f.lorem.paragraphs(...args))),
-            sentence: (...args)=>T.string.as(d(()=>f.lorem.sentence(...args))),
-            sentences: (...args)=>T.string.as(d(()=>f.lorem.sentences(...args))),
-            slug: (...args)=>T.string.as(d(()=>f.lorem.slug(...args))),
-            text: (...args)=>T.string.as(d(()=>f.lorem.text(...args))),
-            word: (...args)=>T.string.as(d(()=>f.lorem.word(...args))),
-            words: (...args)=>T.string.as(d(()=>f.lorem.words(...args)))
+            lines: (...args)=>T.string.as(d(w.lorem.lines(...args))),
+            paragraph: (...args)=>T.string.as(d(w.lorem.paragraph(...args))),
+            paragraphs: (...args)=>T.string.as(d(w.lorem.paragraphs(...args))),
+            sentence: (...args)=>T.string.as(d(w.lorem.sentence(...args))),
+            sentences: (...args)=>T.string.as(d(w.lorem.sentences(...args))),
+            slug: (...args)=>T.string.as(d(w.lorem.slug(...args))),
+            text: (...args)=>T.string.as(d(w.lorem.text(...args))),
+            word: (...args)=>T.string.as(d(w.lorem.word(...args))),
+            words: (...args)=>T.string.as(d(w.lorem.words(...args)))
         },
         music: {
             album: (...args)=>T.string.as(d(()=>f.music.album(...args))),
@@ -417,7 +419,7 @@ function build(T, faker, draw) {
             sample: (...args)=>T.string.as(d(()=>f.string.sample(...args))),
             symbol: (...args)=>T.string.as(d(()=>f.string.symbol(...args))),
             ulid: (...args)=>T.string.as(d(()=>f.string.ulid(...args))),
-            uuid: (...args)=>T.string.as(d(()=>f.string.uuid(...args)), {
+            uuid: (...args)=>T.string.as(d(()=>f.string.uuid(...args))).admits({
                     format: "uuid"
                 })
         },
@@ -429,7 +431,7 @@ function build(T, faker, draw) {
             directoryPath: (...args)=>T.string.as(d(()=>f.system.directoryPath(...args))),
             fileExt: (...args)=>T.string.as(d(()=>f.system.fileExt(...args))),
             fileName: (...args)=>T.string.as(d(()=>f.system.fileName(...args))),
-            filePath: (...args)=>T.string.as(d(()=>f.system.filePath(...args)), {
+            filePath: (...args)=>T.string.as(d(()=>f.system.filePath(...args))).admits({
                     format: "uri-reference"
                 }),
             fileType: (...args)=>T.string.as(d(()=>f.system.fileType(...args))),
@@ -449,15 +451,15 @@ function build(T, faker, draw) {
             vrm: (...args)=>T.string.as(d(()=>f.vehicle.vrm(...args)))
         },
         word: {
-            adjective: (...args)=>T.string.as(d(()=>f.word.adjective(...args))),
-            adverb: (...args)=>T.string.as(d(()=>f.word.adverb(...args))),
-            conjunction: (...args)=>T.string.as(d(()=>f.word.conjunction(...args))),
-            interjection: (...args)=>T.string.as(d(()=>f.word.interjection(...args))),
-            noun: (...args)=>T.string.as(d(()=>f.word.noun(...args))),
-            preposition: (...args)=>T.string.as(d(()=>f.word.preposition(...args))),
-            sample: (...args)=>T.string.as(d(()=>f.word.sample(...args))),
-            verb: (...args)=>T.string.as(d(()=>f.word.verb(...args))),
-            words: (...args)=>T.string.as(d(()=>f.word.words(...args)))
+            adjective: (...args)=>T.string.as(d(w.word.adjective(...args))),
+            adverb: (...args)=>T.string.as(d(w.word.adverb(...args))),
+            conjunction: (...args)=>T.string.as(d(w.word.conjunction(...args))),
+            interjection: (...args)=>T.string.as(d(w.word.interjection(...args))),
+            noun: (...args)=>T.string.as(d(w.word.noun(...args))),
+            preposition: (...args)=>T.string.as(d(w.word.preposition(...args))),
+            sample: (...args)=>T.string.as(d(w.word.sample(...args))),
+            verb: (...args)=>T.string.as(d(w.word.verb(...args))),
+            words: (...args)=>T.string.as(d(w.word.words(...args)))
         }
     };
 }

package/dist/esm/FakerModules/Words.js

@@ -0,0 +1,151 @@
+import { FakerError } from "@faker-js/faker";
+const categories = [
+    "adjective",
+    "adverb",
+    "conjunction",
+    "interjection",
+    "noun",
+    "preposition",
+    "verb"
+];
+function filterByLength(list, options = {}) {
+    const { length, strategy = "fail" } = "number" == typeof options ? {
+        length: options
+    } : options;
+    if (void 0 === length) {
+        if ("shortest" === strategy || "longest" === strategy) return extreme(list, strategy);
+        return list;
+    }
+    const range = "number" == typeof length ? {
+        min: length,
+        max: length
+    } : length;
+    const matching = list.filter((word)=>word.length >= range.min && word.length <= range.max);
+    if (matching.length > 0) return matching;
+    switch(strategy){
+        case "fail":
+            throw new FakerError("No words found that match the given length.");
+        case "closest":
+            return closest(list, range);
+        case "shortest":
+        case "longest":
+            return extreme(list, strategy);
+        case "any-length":
+            return list;
+    }
+}
+function extreme(list, strategy) {
+    const lengths = list.map((word)=>word.length);
+    const target = "shortest" === strategy ? Math.min(...lengths) : Math.max(...lengths);
+    return list.filter((word)=>word.length === target);
+}
+function closest(list, range) {
+    let below = -1 / 0;
+    let above = 1 / 0;
+    for (const { length } of list){
+        if (length < range.min && length > below) below = length;
+        if (length > range.max && length < above) above = length;
+    }
+    const offset = Math.min(range.min - below, above - range.max);
+    return list.filter(({ length })=>length === range.min - offset || length === range.max + offset);
+}
+function listOf(read, options) {
+    let resolved;
+    return ()=>{
+        if (void 0 === resolved) resolved = filterByLength(read(), options);
+        return resolved;
+    };
+}
+function pick(random, list) {
+    if (0 === list.length) throw new FakerError("Cannot get value from empty dataset.");
+    return list[list.length > 1 ? Math.floor(random.next() * list.length) : 0];
+}
+function toWords(faker) {
+    const repeat = (count, separator, next)=>faker.helpers.multiple(next, {
+            count
+        }).join(separator);
+    const words = (word, count = 3)=>repeat(count, " ", word);
+    const sentence = (word, count = {
+        min: 3,
+        max: 10
+    })=>{
+        const text = words(word, count);
+        return `${text.charAt(0).toUpperCase()}${text.substring(1)}.`;
+    };
+    const sentences = (word, count = {
+        min: 2,
+        max: 6
+    }, separator = " ")=>repeat(count, separator, ()=>sentence(word));
+    const paragraph = (word, count = 3)=>sentences(word, count);
+    const paragraphs = (word, count = 3, separator = "\n")=>repeat(count, separator, ()=>paragraph(word));
+    const lines = (word, count = {
+        min: 1,
+        max: 5
+    })=>sentences(word, count, "\n");
+    const texts = [
+        sentence,
+        sentences,
+        paragraph,
+        paragraphs,
+        lines
+    ];
+    const lorem = (compose)=>{
+        const list = listOf(()=>faker.definitions.lorem.word, void 0);
+        return ({ random })=>compose(()=>pick(random, list()), random);
+    };
+    const category = (name)=>(options)=>{
+            const list = listOf(()=>faker.definitions.word[name], options);
+            return ({ random })=>pick(random, list());
+        };
+    const sampler = (options)=>{
+        const lists = categories.map((name)=>listOf(()=>faker.definitions.word[name], options));
+        return (random)=>{
+            for (const list of faker.helpers.shuffle(lists))try {
+                return pick(random, list());
+            } catch  {
+                continue;
+            }
+            throw new FakerError("No matching word data available for the current locale");
+        };
+    };
+    return {
+        lorem: {
+            lines: (count)=>lorem((word)=>lines(word, count)),
+            paragraph: (count)=>lorem((word)=>paragraph(word, count)),
+            paragraphs: (count, separator)=>lorem((word)=>paragraphs(word, count, separator)),
+            sentence: (count)=>lorem((word)=>sentence(word, count)),
+            sentences: (count, separator)=>lorem((word)=>sentences(word, count, separator)),
+            slug: (count)=>lorem((word)=>faker.helpers.slugify(words(word, count))),
+            text: ()=>lorem((word, random)=>pick(random, texts)(word)),
+            word: (options)=>{
+                const list = listOf(()=>faker.definitions.lorem.word, options);
+                return ({ random })=>pick(random, list());
+            },
+            words: (count)=>lorem((word)=>words(word, count))
+        },
+        word: {
+            adjective: category("adjective"),
+            adverb: category("adverb"),
+            conjunction: category("conjunction"),
+            interjection: category("interjection"),
+            noun: category("noun"),
+            preposition: category("preposition"),
+            sample: (options)=>{
+                const sample = sampler(options);
+                return ({ random })=>sample(random);
+            },
+            verb: category("verb"),
+            words: (options = {})=>{
+                const { count = {
+                    min: 1,
+                    max: 3
+                } } = "number" == typeof options ? {
+                    count: options
+                } : options;
+                const sample = sampler(void 0);
+                return ({ random })=>repeat(count, " ", ()=>sample(random));
+            }
+        }
+    };
+}
+export { toWords };

package/dist/esm/index.js

@@ -27,7 +27,7 @@ function draw(produce) {
         const previous = scope;
         scope = context;
         try {
-            return produce();
+            return produce(context);
         } finally{
             scope = previous;
         }

package/dist/types/Construct.d.ts

@@ -22,4 +22,4 @@ import type { FakerExtension, Registry } from "./Types";
  * runtime floor on the builder count: the type-level guards read the surface
  * alone and cannot see a spread that drops a module.
  */
-export declare function construct(T: Registry, faker: Faker, draw: <$T>(produce: () => $T) => (context: ProduceContext) => $T): FakerExtension;
+export declare function construct(T: Registry, faker: Faker, draw: <$T>(produce: (context: ProduceContext) => $T) => (context: ProduceContext) => $T): FakerExtension;

package/dist/types/Error.d.ts

@@ -3,7 +3,8 @@
  * exports that name, and importing both into one scope would collide. Follows
  * core's `FabricatorError` shape (abstract base plus a merged namespace of
  * subclasses) so `e instanceof FabricatorError` still catches everything either
- * package throws.
+ * package throws. A `name` is prefixed with this package's name, as core's are
+ * with its own.
  */
 import { FabricatorError } from "@ghostry/fabricator";
 export declare abstract class FakerExtensionError extends FabricatorError {

package/dist/types/FakerModules/Build.d.ts

@@ -9,7 +9,7 @@
  * the faker-bump workflow; an entry added or changed here needs the matching
  * edit there, and vice versa.
  *
- * Three shapes before editing:
+ * Shapes before editing:
  *
  * - Every builder spreads faker's `Parameters<...>` rather than taking a single
  *   `options?`. Faker's zero-parameter methods (`animal.bear()`) and its
@@ -24,16 +24,22 @@
  *   producer rather than a length bound.
  * - `color`'s 7 split methods are a `{ text, channels }` pair each rather than
  *   one ambiguous builder, since their return type depends on their arguments;
- *   see the deviation policy in `CLAUDE.md`'s "The faker extension". All 7 name
+ *   see the deviation policy in `AGENTS.md`'s "The faker extension". All 7 name
  *   `format: "decimal"` on `.channels()`, not only `rgb`: bare is right at
  *   runtime for the other 6, but not provable through faker's declarations,
  *   whose _first_ overload takes `format?: StringColorFormat` and returns
  *   `string`. `'decimal'` is `NumberColorFormat`'s sole member, so naming it is
  *   exact.
+ * - `lorem`'s and `word`'s builders never call faker's own method: faker's
+ *   per-word path copies the word list and parses an options object for every
+ *   word drawn, so they draw through `./Words.ts`, which reproduces faker's
+ *   output exactly from the same stream.
  *
  * Every node is a plain object or a bare builder function, never a function
  * carrying properties — the invariant `deepMerge` needs to recurse through an
  * extended registry, guarded by `test/Mergeable.test.ts`.
+ *
+ * @module
  */
 import type { Faker } from "@faker-js/faker";
 import type { ProduceContext } from "@ghostry/fabricator";
@@ -41,9 +47,9 @@ import type { Registry } from "../Types";
 import type { FakerModules } from "./Types";
 /**
  * `src/index.ts`'s `draw`, by type — the save/restore wrapper that binds a
- * producer to the leaf's own `random`/`clock`. Named here rather than imported
- * so this file stays type-only in its dependencies.
+ * producer to the leaf's own `random`/`clock`. Named here rather than imported,
+ * since `src/index.ts` imports this file.
  */
-type Draw = <$T>(produce: () => $T) => (context: ProduceContext) => $T;
+type Draw = <$T>(produce: (context: ProduceContext) => $T) => (context: ProduceContext) => $T;
 export declare function build(T: Registry, faker: Faker, draw: Draw): FakerModules;
 export {};

package/dist/types/FakerModules/Types.d.ts

@@ -41,11 +41,14 @@
  *    union rather than a bare `string`.
  * 4. A reordered overload set changes `Parameters<...>` here, which the matching
  *    builder's `...args` forwarding then fails to accept.
+ * 5. A change to how `lorem` or `word` draws fails `test/Parity.test.ts`, at `bun
+ *    test` rather than `check`: those builders reimplement faker's method
+ *    bodies in `./Words.ts`, which must then be brought back in line.
  *
  * Fix the entry in **both** files; the annotation on `build` fails until they
  * agree.
  *
- * These assertions resolve through built `dist/`, not `src/` (`CLAUDE.md`'s
+ * These assertions resolve through built `dist/`, not `src/` (`AGENTS.md`'s
  * test-import convention), so a `src`-only edit proves nothing about faker
  * drift until you rebuild. A disagreement between this file and `./Build.ts` is
  * caught without one, being internal to `src`.

package/dist/types/FakerModules/Words.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Faker 10's `lorem` and `word` method bodies, minus the word-list copy.
+ *
+ * Faker's per-word path has two costs. With no `length`, its shared
+ * `filterWordListByLength` returns `[...wordList]`, copying a whole locale list
+ * (up to 1,000 entries in `en`) to index one element. That copy is close to
+ * free where the engine shares a literal array's storage on spread (Node 22–26
+ * and Bun 1.4.4 with faker's bundled locales), but costs about a microsecond
+ * per word on Bun 1.2.14, and on any engine when a locale's lists are built at
+ * runtime. Each word then goes through `helpers.arrayElement` → `number.int`,
+ * which parses an options object per draw and is most of what remains where the
+ * copy is free. `lorem.sentence`/`paragraph`/`text` pay both once per word.
+ * Every builder in `./Build.ts`'s `lorem`/`word` modules draws through this
+ * file instead and never calls faker's own method.
+ *
+ * The copy is reported upstream as
+ * https://github.com/faker-js/faker/issues/4242. A faker release that drops it
+ * is the point to weigh calling faker's methods again, not an automatic
+ * removal: the per-draw options parsing and definitions lookup would remain.
+ *
+ * **The output is faker's exactly, not an approximation.** `pick` reads
+ * `random.next()` and indexes with `arrayElement`'s own arithmetic,
+ * `Math.floor(u * length)`, from the same stream faker's randomizer reads
+ * (`src/index.ts`'s `draw` installs one `context` for both). Every draw made
+ * once per group rather than once per word — a `count` resolved through
+ * `rangeToNumber`, `word.sample`'s shuffle, `slug`'s `slugify` — goes through
+ * faker's own helpers, which keeps their semantics (an inverted range's error,
+ * a fractional count's truncation) without restating them, at a cost that is
+ * off the hot path. So a seed's data is unchanged, the surface keeps faker's
+ * `Parameters<...>`, and nothing about this is a deviation in the sense of
+ * `AGENTS.md`'s deviation policy. `test/Parity.test.ts` is the guard: it
+ * compares every builder here against faker's own method on an identical
+ * stream, so a faker release that changes how these draw fails there.
+ *
+ * Each filtered list is resolved once per builder call, lazily on the first
+ * draw, and a throw is never cached: missing locale data (thrown by faker's
+ * definitions proxy) and `strategy: "fail"` still throw from `fabricate()` on
+ * every call, as faker's own methods do, rather than from the builder call.
+ *
+ * @module
+ */
+import type { Faker } from "@faker-js/faker";
+import type { ProduceContext } from "@ghostry/fabricator";
+type Producer = (context: ProduceContext) => string;
+type WordOptions = Parameters<Faker["word"]["noun"]>[0];
+type Count = NonNullable<Parameters<Faker["lorem"]["words"]>[0]>;
+export declare function toWords(faker: Faker): {
+    lorem: {
+        lines: (count?: Count) => Producer;
+        paragraph: (count?: Count) => Producer;
+        paragraphs: (count?: Count, separator?: string) => Producer;
+        sentence: (count?: Count) => Producer;
+        sentences: (count?: Count, separator?: string) => Producer;
+        slug: (count?: Count) => Producer;
+        text: () => Producer;
+        word: (options?: WordOptions) => Producer;
+        words: (count?: Count) => Producer;
+    };
+    word: {
+        adjective: (options?: WordOptions) => Producer;
+        adverb: (options?: WordOptions) => Producer;
+        conjunction: (options?: WordOptions) => Producer;
+        interjection: (options?: WordOptions) => Producer;
+        noun: (options?: WordOptions) => Producer;
+        preposition: (options?: WordOptions) => Producer;
+        sample: (options?: WordOptions) => Producer;
+        verb: (options?: WordOptions) => Producer;
+        words: (options?: Parameters<Faker["word"]["words"]>[0]) => Producer;
+    };
+};
+export {};

package/dist/types/Types.d.ts

@@ -12,7 +12,7 @@ export type Registry = Pick<typeof registry, "array" | "bigint" | "boolean" | "d
  * Every module the mirror covers, intersected with `keyof Faker` so every
  * downstream `Faker[$M]` indexing is sound. `FakerModules/Types.ts` is the
  * source of truth — `helpers` is absent from it deliberately (deviation policy
- * in `CLAUDE.md`'s "The faker extension"), so this type excludes it without
+ * in `AGENTS.md`'s "The faker extension"), so this type excludes it without
  * saying so twice.
  *
  * `test/index.types.test.ts`'s `_ModulesExhaustive` holds this to faker's own
@@ -60,7 +60,7 @@ export type FakerExtension = FakerModules & {
      * (`src/index.ts`'s `draw`).
      *
      * How `helpers` is reached (omitted from the mirror — deviation policy in
-     * `CLAUDE.md`'s "The faker extension"). Kind-tagged forms (`.string`,
+     * `AGENTS.md`'s "The faker extension"). Kind-tagged forms (`.string`,
      * `.number`, `.date`, `.boolean`, `.bigint`) keep adapter compatibility
      * available there too. `.opaque` is the **only** way to get an `opaque`
      * schema out of this package — honest, since it is the one place the caller

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@ export type { FakerExtension as FakerTypes } from "./Types";
  * The mirror's type-level machinery — not needed to _use_ it, but exported so a
  * consumer (or this package's compile-time checks in
  * `test/index.types.test.ts`) can name a module or method without a relative
- * `./Types` path tests otherwise avoid (`CLAUDE.md`: tests resolve through the
+ * `./Types` path tests otherwise avoid (`AGENTS.md`: tests resolve through the
  * package specifier, exercising built `dist/`).
  *
  * `FakerModules` is the surface those checks are made _against_ — every
@@ -29,9 +29,9 @@ export type FakerConfig = ConstructorParameters<typeof Faker>[0]["config"];
  *
  * No `seed` option and no pre-built `Faker`: a pre-built instance's randomizer
  * is fixed at construction, and accepting one would either ignore it silently
- * or let it compete with fabricator's seed. `create` is the honest escape: the
- * caller builds the instance; it still receives this bridge's `randomizer`, so
- * reproducibility survives.
+ * or let it compete with fabricator's seeding. `create` is the honest escape:
+ * the caller builds the instance; it still receives this bridge's `randomizer`,
+ * so reproducibility survives.
  */
 export type Options = {
     locale: LocaleDefinition | LocaleDefinition[];
@@ -63,11 +63,11 @@ export type Options = {
  * `FakerExtension` (`./Types.ts`) is spelled out explicitly rather than
  * inferred. An inferred type would reach into each kind's `Schema` interface —
  * internal to `@ghostry/fabricator`, unreachable from its `.` export — and
- * declaration emission (`tsgo`, not `tsc --noEmit`; see `CLAUDE.md`'s
+ * declaration emission (`tsgo`, not `tsc --noEmit`; see `AGENTS.md`'s
  * declaration-emit trap) refuses to print an anonymous expansion of one. Even
  * where it printed it would be the wrong contract: inference would surface each
- * builder's incidental narrowness (`Schema<{ produce; hints }>`) where the
- * declared surface states `Primitive.string.Schema`.
+ * builder's incidental narrowness (`Schema<{ produce }>`) where the declared
+ * surface states `Primitive.string.Schema`.
  *
  * Every node is a plain object or a leaf builder function, never a function
  * carrying properties: `deepMerge` recurses only where `isPlainObject` holds on

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@ghostry/fabricator-extension-faker-v10",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "license": "MIT",
   "description": "@faker-js/faker integration for @ghostry/fabricator — faker's data generators, seeded and reproducible through the fabricator instance that calls them.",
   "keywords": [
     "factory",
+    "reproducible",
+    "fixtures",
+    "testing",
+    "mock",
+    "schema",
     "faker",
-    "extension"
+    "typescript"
   ],
   "author": {
     "name": "Patrick Rebsch"
@@ -16,9 +21,13 @@
     "url": "git+https://github.com/ghostry-dev/fabricator",
     "directory": "pkg/fabricator-extension-faker-v10"
   },
-  "homepage": "https://github.com/ghostry-dev/fabricator",
+  "homepage": "https://docs.ghostry.dev/fabricator",
   "bugs": "https://github.com/ghostry-dev/fabricator/issues",
   "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "types": "./dist/types/index.d.ts",
   "module": "./dist/esm/index.js",
   "exports": {
@@ -44,20 +53,21 @@
     "check": "tsc --noEmit",
     "check:ts5": "bun --bun ../../node_modules/typescript-5/lib/tsc.js --noEmit",
     "check:jsr": "DENO_BIN_PATH=$PWD/../../node_modules/.bin/deno bunx --no-install jsr publish --dry-run --allow-dirty",
-    "format": "bunx --no-install oxfmt .",
+    "format": "bun fmt",
     "test": "bun run check && bun run check:ts5 && bun run check:jsr && bun test"
   },
   "files": [
     "dist"
   ],
   "peerDependencies": {
-    "@ghostry/fabricator": ">=0.0.1 <0.1.0",
+    "@ghostry/fabricator": ">=0.0.14 <0.1.0",
     "@faker-js/faker": "^10.5.0"
   },
   "devDependencies": {
-    "@ghostry/fabricator": "0.0.1",
-    "@ghostry/fabricator-adapter-typebox-v0": "0.0.1",
-    "@faker-js/faker": "^10.5.0",
+    "@ghostry/fabricator": "0.0.14",
+    "@ghostry/fabricator-adapter-typebox-v0": "0.0.4",
+    "@faker-js/faker": "^10.6.0",
+    "@ghostry/harness": "^0.0.6",
     "@sinclair/typebox": "^0.34.52"
   }
 }