@capsuleer/chance

Random data generator for Capsuleer agents. Powered by Chance.js — generate realistic fake people, places, URLs, numbers, IDs, and more. Indispensable for seeding test databases, simulating user behaviour, and making demo data that doesn't look like "John Doe, [email protected], 123 Main St."

capsuleer install chance

API

Identity

await chance.name()                              // → "Lena Castillo"
await chance.name({ full: true, prefix: true })  // → "Dr. Marcus T. Webb"
await chance.email()                             // → "[email protected]"
await chance.email({ domain: "acme.com" })       // → "[email protected]"
await chance.phone()                             // → "(412) 555-0183"
await chance.age()                               // → 34
await chance.age({ type: "senior" })             // → 71
await chance.gender()                            // → "Female"
await chance.birthday()                          // → "1991-07-22"
await chance.birthday({ type: "teen" })          // → "2008-03-14"

Location

await chance.address()       // → "1842 Rokev Drive"
await chance.city()          // → "Gukbozuj"
await chance.country()       // → "NZ"
await chance.country({ full: true }) // → "New Zealand"
await chance.zip()           // → "84115"
await chance.coordinates()   // → { lat: -23.4821, lng: 140.2938 }

Internet

await chance.url()                                   // → "http://dum.gov/utuzpew"
await chance.url({ protocol: "https", domain: "acme.com" }) // → "https://acme.com/bivuv"
await chance.domain()                                // → "wekber.org"
await chance.ip()                                    // → "182.34.7.201"
await chance.ipv6()                                  // → "8cf4:22fb:..."
await chance.avatar()                                // → "https://www.gravatar.com/avatar/..."

Text

await chance.word()                     // → "hiwul"
await chance.sentence()                 // → "Odo wemjez re bop iwuwa tipu."
await chance.sentence({ words: 4 })     // → "Ku bafe nuv zoksi."
await chance.paragraph()                // → "Wifib alo re ..." (5 sentences)
await chance.paragraph({ sentences: 2 })

Numbers & IDs

await chance.integer()                   // → -2847361
await chance.integer({ min: 1, max: 100 }) // → 42
await chance.float({ min: 0, max: 1, fixed: 4 }) // → 0.7342
await chance.guid()   // → "f0d8368d-1234-4cfc-a6d9-bf5e8e5f5c84"
await chance.hash()   // → "b80bb7740288fda1724..."
await chance.hash({ length: 8 }) // → "a3f9b2c1"

Finance

await chance.cc()                  // → "4716184847393"  (Luhn-valid, not a real card)
await chance.cc({ type: "visa" })  // → "4539578763621486"
await chance.currency()            // → { code: "JPY", name: "Japanese Yen" }

Misc

await chance.company()              // → "Rocha, Bates and Nichols"
await chance.profession()           // → "Archaeologist"
await chance.animal()               // → "Impala"
await chance.animal({ type: "ocean" }) // → "Blue Whale"
await chance.color()                // → "#a3f29b"
await chance.color({ format: "rgb" }) // → "rgb(163,242,155)"
await chance.emoji()                // → "🦊"
await chance.timezone()             // → "America/Chicago"

Bulk generation

// Call any method N times and collect results
const names = await chance.n("name", 10)
// → ["Lena Castillo", "Marcus Webb", ...]

const emails = await chance.n("email", 5, { domain: "acme.com" })
// → ["[email protected]", "[email protected]", ...]

n() is the power move — generate a full fake dataset in one call, then pass it straight to sqlite.execute().

Observability

{ "ok": true, "op": "chance.name", "data": { "result": "Lena Castillo" } }
{ "ok": true, "op": "chance.email", "data": { "result": "[email protected]" } }
{ "ok": true, "op": "chance.n", "data": { "method": "name", "count": 10 } }

Policy

const capsule = await Capsule({
  policy: {
    chance: true  // all methods allowed — it's just random data
  }
})

See the policy docs for the full rule syntax.