@elfedali/moroccan-data 1.0.0

package/README.md

@@ -0,0 +1,144 @@
+# @elfedali/moroccan-data
+
+Generate realistic Moroccan test data for developers.
+
+This is a small, Faker-like Moroccan data provider focused on practicality: names, locations, phone numbers, IDs, and basic internet/company fields.
+
+## Features
+
+- Deterministic output with seeds (great for tests)
+- ESM + CommonJS builds
+- TypeScript types included
+
+## Install
+
+```bash
+npm i @elfedali/moroccan-data
+```
+
+## Usage
+
+### Quick start (ESM)
+
+```ts
+import { morocco, createMoroccanFaker } from '@elfedali/moroccan-data';
+
+console.log(morocco.person.fullName());
+console.log(morocco.location.address());
+console.log(morocco.phone.internationalMobile({ formatted: true }));
+
+const seeded = createMoroccanFaker({ seed: 123 });
+console.log(seeded.id.cin());
+```
+
+### CommonJS
+
+```js
+const { morocco } = require('@elfedali/moroccan-data');
+console.log(morocco.person.fullName());
+```
+
+## Seeding (deterministic data)
+
+```ts
+import { createMoroccanFaker } from '@elfedali/moroccan-data';
+
+const f1 = createMoroccanFaker({ seed: 42 });
+const f2 = createMoroccanFaker({ seed: 42 });
+
+// Same outputs across runs
+console.log(f1.person.fullName());
+console.log(f2.person.fullName());
+```
+
+## API
+
+The default singleton is `morocco`.
+
+You can also create your own instance: `createMoroccanFaker({ seed? })`.
+
+### person
+
+- `morocco.person.firstName(gender?)`
+- `morocco.person.lastName()`
+- `morocco.person.fullName({ gender? })`
+- `morocco.person.jobTitle()`
+
+### location
+
+- `morocco.location.city()` / `region()` / `postalCode()` / `streetAddress()`
+- `morocco.location.latitude()` / `longitude()` / `coordinates()`
+- `morocco.location.address()`
+
+`address()` returns:
+
+```ts
+{
+	street: string;
+	city: string;
+	region: string;
+	postalCode: string;
+	latitude: number;
+	longitude: number;
+	country: 'Morocco';
+	countryCode: 'MA';
+}
+```
+
+### phone
+
+- `morocco.phone.mobile({ formatted? })` / `internationalMobile({ formatted? })`
+
+Examples:
+
+- `mobile()` → `06XXXXXXXX` or `07XXXXXXXX`
+- `mobile({ formatted: true })` → `06 12 34 56 78`
+- `internationalMobile()` → `+2126XXXXXXXX`
+
+### internet
+
+- `morocco.internet.username()` / `email()`
+
+### id
+
+- `morocco.id.cin()` / `ice()`
+
+### company
+
+- `morocco.company.name()`
+
+### date
+
+- `morocco.date.between(from, to)`
+- `morocco.date.isoDate({ from?, to? })` → `YYYY-MM-DD`
+
+### time
+
+- `morocco.time.hhmm()` → `HH:mm`
+- `morocco.time.hhmmss()` → `HH:mm:ss`
+
+### text (real sentences)
+
+- `morocco.text.sentence()`
+- `morocco.text.paragraph({ sentences? })`
+- `morocco.text.text({ sentences? })`
+
+### number
+
+- `morocco.number.int({ min?, max? })`
+- `morocco.number.float({ min?, max?, precision? })`
+
+## Notes
+
+- This library generates *fake* data that looks plausible; it does not guarantee official validation rules for every identifier.
+
+## Dev
+
+- Build: `npm run build`
+- Test: `npm test`
+- Watch: `npm run dev` / `npm run test:watch`
+
+## Help the developer
+
+- PayPal: a.elfedali@gmail.com
+- GitHub: https://github.com/elfedali