loredata 0.2.0 → 0.4.1

package/README.md

@@ -1,15 +1,63 @@
-# loredata
+<p align="center">
+  <img src="https://raw.githubusercontent.com/orchidfiles/loredata/main/apps/web/static/logo.png" alt="LoreData" width="80" />
+</p>
 
-[![npm version](https://img.shields.io/npm/v/loredata)](https://www.npmjs.com/package/loredata)
-[![npm downloads per month](https://img.shields.io/npm/dm/loredata)](https://www.npmjs.com/package/loredata)
-[![node version](https://img.shields.io/node/v/loredata)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/loredata)](./LICENSE)
-[![last commit](https://img.shields.io/github/last-commit/orchidfiles/loredata)](https://github.com/orchidfiles/loredata)
+<h3 align="center">LoreData</h3>
 
-Generate fake personas using real characters from pop culture universes. Every field — name, email, address, profession, quote — comes from the same fictional world.
+<p align="center">
+  Generate coherent personas from pop culture universes.<br/>
+  Each persona comes from one fictional world with no cross-universe mixing.<br/>
+  Built for demos, mockups, screenshots, and seed fixtures where recognizable context matters.<br/>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/loredata"><img src="https://img.shields.io/npm/v/loredata" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/loredata"><img src="https://img.shields.io/npm/dm/loredata" alt="npm downloads per month" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/loredata" alt="node version" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/loredata" alt="license" /></a>
+  <a href="https://github.com/orchidfiles/loredata"><img src="https://img.shields.io/github/last-commit/orchidfiles/loredata" alt="last commit" /></a>
+</p>
+
+<img src="https://raw.githubusercontent.com/orchidfiles/loredata/main/apps/web/static/screen.png" alt="LoreData screenshot" />
 
 **Demo:** [loredata.orchidfiles.com](https://loredata.orchidfiles.com)
 
+## Why LoreData
+
+- Generic demo users like John Doe, Jane Smith, and `test@example.com` work for smoke tests but feel flat in real product demos
+- LoreData generates recognizable personas from a single fictional universe, so fields stay coherent by design
+- Deterministic output via seed keeps fixtures stable across runs
+- Works in Node.js, browser, and as a CLI tool with no network requests
+
+## Who this is for
+
+- developers filling a local database or Storybook stories with recognizable personas
+- designers building mockups who do not want to use John Doe again
+- QA engineers creating more expressive test accounts with different profiles
+- tutorial and conference talk authors who want screenshots that feel less generic
+
+## Features
+
+- [x] 29 universes
+- [x] Single persona and group generation
+- [x] Filter characters by interest, name, universe
+- [x] Deterministic output via seed
+- [x] Browser-safe entry point
+- [x] CLI tool
+- [x] Character symbol and color fields
+
+## Install
+
+```sh
+# library
+npm install loredata
+
+# CLI
+npm install -g loredata
+```
+
+## Usage example
+
 ```ts
 import { person, group } from 'loredata';
 
@@ -20,7 +68,7 @@ const p = person({ universe: 'breaking-bad' });
 //   username: 'heisenberg',
 //   email: 'blue_sky_cook@lospollos.com',
 //   quote: "I am the one who knocks.",
-//   profession: 'chemistry teacher',
+//   profession: 'Chemistry teacher',
 //   interests: ['chemistry', 'cooking', 'family'],
 //   address: { street: '308 Negra Arroyo Lane', city: 'Albuquerque', state: 'NM' },
 //   symbol: '☢️',
@@ -30,28 +78,10 @@ const p = person({ universe: 'breaking-bad' });
 // }
 
 const team = group({ universe: 'game-of-thrones', size: 3 });
-```
-
-Works in Node.js, browser, and as a CLI tool.
-
-## Install
-
-```sh
-npm install loredata
-```
-
-## Universes
-
-Available out of the box: `breaking-bad`, `friends`, `game-of-thrones`, `harry-potter`, `house-md`, `lost`, `fast-and-furious`, `matrix`, `peaky-blinders`, `sherlock`, `the-office`
-
-```ts
-import { universes } from 'loredata';
-
-universes();
 // [
-//   { id: 'sherlock', name: 'Sherlock', genre: ['crime', 'drama', 'mystery'], description: '...' },
-//   { id: 'game-of-thrones', name: 'Game of Thrones', genre: ['fantasy', 'drama', 'action'], description: '...' },
-//   ...
+//   { firstName: 'Jon', lastName: 'Snow', username: 'lord_commander', ... },
+//   { firstName: 'Daenerys', lastName: 'Targaryen', username: 'mother_of_dragons', ... },
+//   { firstName: 'Tyrion', lastName: 'Lannister', username: 'halfman', ... },
 // ]
 ```
 
@@ -60,21 +90,26 @@ universes();
 Each `Person` includes:
 
 - `firstName`, `lastName`
-- `username`, `email`, `password`, `phone`
+- `username`, `email`
 - `address`, `profession`, `interests`
 - `quote`, `symbol`, `color`
 - `universe`, `universeName`
 
 ## Deterministic output
 
-Pass a `seed` for reproducible results:
+If you need reproducible results, for example for test fixtures, just pass a `seed`:
 
 ```ts
 const p = person({ universe: 'matrix', seed: 42 });
+const team = group({ universe: 'matrix', size: 3, seed: 42 });
 ```
 
+Given the same `seed`, you always get the same persona or the same group.
+
 ## Browser
 
+The library also supports browser environments through a separate entry point with no dependency on `fs` or `path`:
+
 ```ts
 import { loadUniverse, personFromData } from 'loredata/browser';
 
@@ -82,60 +117,86 @@ const universe = await loadUniverse('breaking-bad');
 const p = personFromData(universe);
 ```
 
-No `fs` or `path` — safe for Vite, webpack, and any browser bundler.
+It works with Vite, webpack, and any browser bundler.
 
 ## CLI
 
 ```sh
-npx loredata person --universe breaking-bad
-npx loredata person --universe breaking-bad --format json
-npx loredata person --interests chemistry,cooking
-npx loredata person --name walter
-npx loredata group --universe friends --size 5
-npx loredata universes
+loredata person --universe breaking-bad
+loredata person --universe breaking-bad --format json
+loredata person --interests chemistry,cooking
+loredata person --interests chemistry,cooking --interests-mode and
+loredata person --name walter
+loredata group --universe friends --size 5
+loredata universes
 ```
 
-## Features
+## Universes
 
-- [x] 11 universes with characters, addresses, domains
-- [x] Single persona and group generation
-- [x] Filter characters by interest, name, universe
-- [x] Deterministic output via seed
-- [x] Browser-safe entry point
-- [x] CLI tool
-- [x] Character symbol and color fields
+```ts
+import { universes } from 'loredata';
+
+universes();
+// [
+//   { id: 'sherlock', name: 'Sherlock', genre: ['crime', 'drama', 'mystery'], description: '...' },
+//   { id: 'game-of-thrones', name: 'Game of Thrones', genre: ['fantasy', 'drama', 'action'], description: '...' },
+//   ...
+// ]
+```
+
+For API/CLI usage, use universe IDs such as `the-office` and `game-of-thrones`.
+
+29 universes available out of the box:
+
+- Avengers
+- Better Call Saul
+- Big Bang Theory
+- Breaking Bad
+- Crown
+- Fast and Furious
+- Friends
+- Game of Thrones
+- Guardians of the Galaxy
+- Harry Potter
+- House MD
+- Lost
+- Matrix
+- Office
+- Peaky Blinders
+- Prison Break
+- Sherlock
+- Simpsons
+- Sopranos
+- South Park
+- Spider-Man
+- Star Wars
+- Stranger Things
+- Supernatural
+- Walking Dead
+- Witcher
+- Vikings
+- Westworld
+- X-Men
 
 ## Development
 
 ```sh
+# clone repo and install dependencies
 git clone https://github.com/orchidfiles/loredata.git
 cd loredata
 pnpm install
-```
-
-Build dev-kit (needed once, before other builds):
 
-```sh
+# build in watch mode
 pnpm --filter @loredata/dev-kit build
-```
-
-Build the library:
+pnpm --filter loredata build:watch
 
-```sh
-pnpm run package:build
+# start web app
+pnpm --filter @loredata/web dev
 ```
 
-Run the demo app:
-
-```sh
-pnpm run demo:dev
-```
-
-## Why
-
-Faker.js generates random names and emails. They are internally consistent but meaningless. No shared context, no character identity.
+## Disclaimer
 
-`loredata` generates personas from real fictional characters. Each persona is recognizable and internally consistent, which makes it useful for demos, screenshots, and seed files where the content matters.
+LoreData is an unofficial fan tool and is not affiliated with the rights holders of these universes, studios, or streaming platforms.
 
 ## License
 

package/data/avengers/addresses.json

@@ -0,0 +1,27 @@
+[
+  {
+    "street": "200 Park Avenue",
+    "city": "New York",
+    "state": "NY",
+    "zip": "10166",
+    "country": "US"
+  },
+  {
+    "city": "Upstate New York",
+    "state": "NY",
+    "country": "US"
+  },
+  {
+    "street": "1327 F Street NW",
+    "city": "Washington",
+    "state": "DC",
+    "zip": "20004",
+    "country": "US"
+  },
+  {
+    "city": "Wakanda"
+  },
+  {
+    "city": "Asgard"
+  }
+]

package/data/avengers/characters.json

@@ -0,0 +1,305 @@
+[
+	{
+		"id": "tony-stark",
+		"firstName": "Tony",
+		"lastName": "Stark",
+		"usernames": [
+			"iron_man",
+			"genius_billionaire",
+			"jarvis_take_the_wheel",
+			"arc_reactor",
+			"proof_that_tony_stark_has_a_heart"
+		],
+		"profession": "Inventor",
+		"interests": [
+			"robotics",
+			"racing",
+			"classic cars",
+			"family",
+			"AI",
+			"parties"
+		],
+		"quotes": [
+			"I am Iron Man.",
+			"And I... am... Iron Man.",
+			"I love you three thousand.",
+			"Genius, billionaire, playboy, philanthropist.",
+			"Part of the journey is the end."
+		],
+		"gender": "male",
+		"birthYear": 1970,
+		"address": {
+			"street": "200 Park Avenue",
+			"city": "New York",
+			"state": "NY",
+			"country": "US"
+		},
+		"symbol": "⚙️",
+		"color": "#7f1d1d",
+		"emailDomains": [
+			"stark-industries.com",
+			"ironmail.net"
+		]
+	},
+	{
+		"id": "steve-rogers",
+		"firstName": "Steve",
+		"lastName": "Rogers",
+		"usernames": [
+			"i_can_do_this_all_day",
+			"first_avenger",
+			"man_out_of_time"
+		],
+		"profession": "Soldier",
+		"interests": [
+			"art",
+			"history",
+			"fitness",
+			"leadership"
+		],
+		"quotes": [
+			"I can do this all day.",
+			"Avengers, assemble.",
+			"I'm with you till the end of the line.",
+			"I don't want to kill anyone. I don't like bullies; I don't care where they're from.",
+			"The price of freedom is high. It always has been.",
+			"Whatever it takes."
+		],
+		"gender": "male",
+		"birthYear": 1918,
+		"symbol": "🛡️",
+		"color": "#1e3a5f",
+		"emailDomains": [
+			"shield.gov",
+			"avengers-hq.net"
+		]
+	},
+	{
+		"id": "thor",
+		"firstName": "Thor",
+		"lastName": "Odinson",
+		"usernames": [
+			"god_of_thunder",
+			"son_of_odin",
+			"point_break",
+			"strongest_avenger",
+			"another"
+		],
+		"profession": "King of Asgard",
+		"interests": [
+			"combat",
+			"mead",
+			"feasting",
+			"adventure",
+			"storytelling"
+		],
+		"quotes": [
+			"Bring me Thanos!",
+			"I'm still worthy!",
+			"Another!",
+			"I went for the head.",
+			"He's a friend from work!"
+		],
+		"gender": "male",
+		"symbol": "⚡",
+		"color": "#166534",
+		"emailDomains": [
+			"asgard-mail.net",
+			"avengers-hq.net"
+		]
+	},
+	{
+		"id": "bruce-banner",
+		"firstName": "Bruce",
+		"lastName": "Banner",
+		"usernames": [
+			"always_angry",
+			"other_guy",
+			"sun_is_getting_real_low",
+			"science_bro"
+		],
+		"profession": "Physicist",
+		"interests": [
+			"meditation",
+			"gamma radiation",
+			"biology",
+			"science",
+			"time travel"
+		],
+		"quotes": [
+			"That's my secret, Captain. I'm always angry.",
+			"I put a bullet in my mouth and the other guy spit it out.",
+			"I don't know how to fly one of these."
+		],
+		"gender": "male",
+		"symbol": "💥",
+		"color": "#4c1d95",
+		"emailDomains": [
+			"shield.gov",
+			"gamma-labs.net"
+		]
+	},
+	{
+		"id": "natasha-romanoff",
+		"firstName": "Natasha",
+		"lastName": "Romanoff",
+		"usernames": [
+			"budapest",
+			"red_ledger",
+			"black_widow",
+			"natalie_rushman"
+		],
+		"profession": "Spy",
+		"interests": [
+			"martial arts",
+			"languages",
+			"undercover work",
+			"strategy",
+			"ballet"
+		],
+		"quotes": [
+			"I've got red in my ledger. I'd like to wipe it out.",
+			"We don't wanna kill you. But we will.",
+			"Whatever it takes."
+		],
+		"gender": "female",
+		"symbol": "🕷️",
+		"color": "#7f1d1d",
+		"emailDomains": [
+			"shield.gov",
+			"red-room.net"
+		]
+	},
+	{
+		"id": "clint-barton",
+		"firstName": "Clint",
+		"lastName": "Barton",
+		"usernames": [
+			"ronin_blade",
+			"the_guy_with_the_bow",
+			"end_of_the_line",
+			"hawkeye"
+		],
+		"profession": "Archer",
+		"interests": [
+			"farming",
+			"family",
+			"woodworking",
+			"target practice",
+			"grilling"
+		],
+		"quotes": [
+			"The city is flying, we're fighting an army of robots, and I have a bow and arrow. None of this makes sense.",
+			"You step out that door, you're an Avenger.",
+			"I retire for, what, like five minutes, and it all goes to shit.",
+			"Nobody would know. Nobody. Last I saw him, an Ultron was sitting on him.",
+			"Don't give me hope."
+		],
+		"gender": "male",
+		"symbol": "🏹",
+		"color": "#4a1942",
+		"emailDomains": [
+			"shield.gov",
+			"avengers-hq.net"
+		]
+	},
+	{
+		"id": "loki",
+		"firstName": "Loki",
+		"lastName": "Laufeyson",
+		"usernames": [
+			"god_of_mischief",
+			"burdened_with_purpose",
+			"puny_god",
+			"glorious_purpose"
+		],
+		"profession": "Trickster",
+		"interests": [
+			"illusion magic",
+			"theater",
+			"daggers",
+			"conquest",
+			"shape-shifting"
+		],
+		"quotes": [
+			"I am Loki, of Asgard, and I am burdened with glorious purpose.",
+			"If it's all the same to you, I'll have that drink now.",
+			"Is not this simpler? Is this not your natural state?",
+			"You... will never be... a god.",
+			"I assure you, brother, the sun will shine on us again."
+		],
+		"gender": "male",
+		"symbol": "🐍",
+		"color": "#1e3a5f",
+		"emailDomains": [
+			"asgard-mail.net",
+			"tva-nexus.org"
+		]
+	},
+	{
+		"id": "nick-fury",
+		"firstName": "Nick",
+		"lastName": "Fury",
+		"usernames": [
+			"trust_no_one",
+			"helicarrier",
+			"avengers_initiative",
+			"director_fury"
+		],
+		"profession": "Spy director",
+		"interests": [
+			"surveillance",
+			"strategy",
+			"flying",
+			"cats",
+			"intel briefings"
+		],
+		"quotes": [
+			"I still believe in heroes.",
+			"I recognize the council has made a decision, but given that it's a stupid-ass decision, I've elected to ignore it.",
+			"There was an idea to bring together a group of remarkable people.",
+			"Last time I trusted someone, I lost an eye."
+		],
+		"gender": "male",
+		"symbol": "🛰️",
+		"color": "#134e4a",
+		"emailDomains": [
+			"shield.gov",
+			"espionage-net.org"
+		]
+	},
+	{
+		"id": "thanos",
+		"firstName": "Thanos",
+		"lastName": "",
+		"usernames": [
+			"mad_titan",
+			"inevitable_one",
+			"balanced_universe",
+			"inevitable"
+		],
+		"profession": "Warlord",
+		"interests": [
+			"philosophy",
+			"conquest",
+			"gardening",
+			"farming",
+			"resource scarcity"
+		],
+		"quotes": [
+			"I am inevitable.",
+			"Reality is often disappointing.",
+			"The hardest choices require the strongest wills.",
+			"You should have gone for the head.",
+			"Dread it. Run from it. Destiny arrives all the same.",
+			"A small price to pay for salvation."
+		],
+		"gender": "male",
+		"symbol": "🧤",
+		"color": "#854d0e",
+		"emailDomains": [
+			"titan-post.net",
+			"infinity-order.org"
+		]
+	}
+]

package/data/avengers/meta.json

@@ -0,0 +1,13 @@
+{
+  "id": "avengers",
+  "name": "The Avengers",
+  "genre": ["action", "sci-fi", "adventure"],
+  "description": "Earth's mightiest heroes assemble to fight global threats no single hero can face alone.",
+  "tmdbId": 24428,
+  "mediaType": "movie",
+  "year": 2012,
+  "rating": 8,
+  "networks": ["Marvel Studios"],
+  "posterPath": "/RYMX2wcKCBAr24UyPD7xwmjaTn.jpg",
+  "backdropPath": "/9BBTo63ANSmhC4e6r62OJFuK2GL.jpg"
+}

package/data/better-call-saul/addresses.json

@@ -0,0 +1,37 @@
+[
+  {
+    "street": "9800 Montgomery Blvd NE",
+    "city": "Albuquerque",
+    "state": "NM",
+    "zip": "87111",
+    "country": "US"
+  },
+  {
+    "street": "4257 Isleta Blvd SW",
+    "city": "Albuquerque",
+    "state": "NM",
+    "zip": "87105",
+    "country": "US"
+  },
+  {
+    "street": "160 Juan Tabo Blvd NE",
+    "city": "Albuquerque",
+    "state": "NM",
+    "zip": "87123",
+    "country": "US"
+  },
+  {
+    "street": "6501 Montgomery Blvd NE",
+    "city": "Albuquerque",
+    "state": "NM",
+    "zip": "87109",
+    "country": "US"
+  },
+  {
+    "street": "2727 Rio Grande Blvd NW",
+    "city": "Albuquerque",
+    "state": "NM",
+    "zip": "87104",
+    "country": "US"
+  }
+]