persian-mock-data 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +306 -87
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,19 +1,62 @@
1
- # Persian Mock Data Factory
1
+ # Persian Mock Data
2
2
 
3
- [English documentation](./README.en.md)
3
+ [![npm version](https://img.shields.io/npm/v/persian-mock-data.svg)](https://www.npmjs.com/package/persian-mock-data)
4
+ [![npm downloads](https://img.shields.io/npm/dm/persian-mock-data.svg)](https://www.npmjs.com/package/persian-mock-data)
5
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
6
+ [![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6.svg)](https://www.typescriptlang.org/)
4
7
 
5
- کتابخانه‌ای مستقل از فریم‌ورک و نوشته‌شده با TypeScript برای تولید داده‌های
6
- آزمایشی ایرانی، سناریوهای نامعتبر نام‌گذاری‌شده و داده‌های قابل بازتولید با
7
- `seed`.
8
+ Deterministic, framework-agnostic TypeScript utilities for generating and
9
+ validating Iranian mock data. Use it to create realistic-looking Persian names,
10
+ mobile and landline numbers, national IDs, postal codes, and intentional invalid
11
+ inputs for form and validation testing.
8
12
 
9
- > این پروژه داده‌هایی تولید می‌کند که از **قواعد قالب و الگوریتم مستندشده**
10
- > عبور می‌کنند. خروجی به معنای وجود شخص واقعی، فعال بودن شماره تلفن، ثبت رسمی
11
- > کد ملی یا قابل تحویل بودن نشانی و کد پستی نیست.
13
+ > [!IMPORTANT]
14
+ > This library generates **test data that follows documented format rules**. It
15
+ > does not confirm that a person exists, a national ID is officially assigned,
16
+ > a phone number is reachable, or a postal code is deliverable.
12
17
 
13
- ## وضعیت پروژه
18
+ ## Features
14
19
 
15
- هسته نسخه `0.1.0` پیاده‌سازی شده است، اما پکیج هنوز در npm منتشر نشده. برای
16
- استفاده در توسعه:
20
+ - Framework-independent TypeScript API
21
+ - ESM and CommonJS support
22
+ - Complete TypeScript declarations
23
+ - Reproducible output using number or string seeds
24
+ - Persian first names, last names, and full names
25
+ - Iranian mobile and landline formats
26
+ - Iranian national-ID generation and Mod-11 validation
27
+ - Format-level Iranian postal-code generation and validation
28
+ - Named invalid scenarios for negative tests
29
+ - Explanatory metadata for intentionally invalid values
30
+ - Schema-based generation for complete form fixtures
31
+ - No runtime dependencies
32
+
33
+ ## Requirements
34
+
35
+ - Node.js 18 or newer
36
+
37
+ ## Installation
38
+
39
+ ### npm
40
+
41
+ ```bash
42
+ npm install persian-mock-data
43
+ ```
44
+
45
+ ### pnpm
46
+
47
+ ```bash
48
+ pnpm add persian-mock-data
49
+ ```
50
+
51
+ ### Yarn
52
+
53
+ ```bash
54
+ yarn add persian-mock-data
55
+ ```
56
+
57
+ ### From GitHub
58
+
59
+ Clone the repository when you want to contribute or work with the latest source:
17
60
 
18
61
  ```bash
19
62
  git clone https://github.com/Ali-Shahnoushi/persian-mock-data.git
@@ -22,12 +65,7 @@ npm install
22
65
  npm run build
23
66
  ```
24
67
 
25
- خروجی build شامل ESM، CommonJS و فایل‌های type declaration است و به React،
26
- Vue، Angular، Next.js یا فریم‌ورک دیگری وابستگی ندارد.
27
-
28
- ## شروع سریع
29
-
30
- ### تولید یک فرم معتبر و قابل بازتولید
68
+ ## Quick start
31
69
 
32
70
  ```ts
33
71
  import { persianMock } from "persian-mock-data";
@@ -42,50 +80,89 @@ const user = persianMock.generate(
42
80
  },
43
81
  { seed: 1405 },
44
82
  );
83
+
84
+ console.log(user);
45
85
  ```
46
86
 
47
- همان schema با همان `seed` همیشه همان خروجی را تولید می‌کند. تمام فیلدهای یک
48
- schema از یک جریان تصادفی مشترک استفاده می‌کنند.
87
+ The same schema and seed always produce the same object. All fields in a schema
88
+ share one seeded random stream, so the complete fixture is reproducible.
89
+
90
+ ## Module formats
49
91
 
50
- ### تولید داده نامعتبر هدفمند
92
+ ### ESM and TypeScript
51
93
 
52
94
  ```ts
53
- const invalidId = persianMock.field("identity.nationalId", {
54
- mode: "invalid",
55
- scenario: "wrong-checksum",
56
- seed: 1405,
57
- });
95
+ import {
96
+ generateMobile,
97
+ persianMock,
98
+ validateMobile,
99
+ } from "persian-mock-data";
100
+ ```
58
101
 
59
- const explained = persianMock.case("phone.mobile", {
60
- mode: "invalid",
61
- scenario: "persian-digits",
62
- seed: 1405,
63
- });
102
+ ### CommonJS
103
+
104
+ ```js
105
+ const {
106
+ generateMobile,
107
+ persianMock,
108
+ validateMobile,
109
+ } = require("persian-mock-data");
64
110
  ```
65
111
 
66
- `field` مقدار خام و `case` مقدار همراه با `expectedValid`، نام سناریو و
67
- `violatedRule` را برمی‌گرداند. برای تمام حالت‌های مرزی یک فیلد:
112
+ ## Generate individual fields
113
+
114
+ Every generator accepts an optional number seed, string seed, or shared random
115
+ source.
68
116
 
69
117
  ```ts
70
- const cases = persianMock.edgeCases("address.postalCode", 1405);
118
+ import {
119
+ generateFirstName,
120
+ generateFullName,
121
+ generateLandline,
122
+ generateLastName,
123
+ generateMobile,
124
+ generateNationalId,
125
+ generatePostalCode,
126
+ } from "persian-mock-data";
127
+
128
+ const firstName = generateFirstName(1405);
129
+ const lastName = generateLastName(1405);
130
+ const fullName = generateFullName(1405);
131
+ const mobile = generateMobile(1405);
132
+ const nationalId = generateNationalId(1405);
133
+ const postalCode = generatePostalCode(1405);
134
+
135
+ const landline = generateLandline(1405);
136
+ // {
137
+ // value: "...",
138
+ // areaCode: "...",
139
+ // province: "..."
140
+ // }
71
141
  ```
72
142
 
73
- ## API عمومی
143
+ You can also generate a raw field value through the unified API:
74
144
 
75
- | API | کاربرد |
76
- | --- | --- |
77
- | `persianMock.generate(schema, options)` | تولید object هم‌شکل با فرم |
78
- | `persianMock.field(type, options)` | تولید مقدار خام یک فیلد |
79
- | `persianMock.case(type, options)` | تولید مقدار همراه با فراداده اعتبار |
80
- | `persianMock.edgeCases(type, seed)` | تولید همه سناریوهای نامعتبر یک فیلد |
81
- | `generateFirstName`، `generateLastName`، `generateFullName` | نام‌های فارسی ساختگی |
82
- | `generateMobile`، `generateLandline` | تلفن همراه و ثابت |
83
- | `generateNationalId`، `generatePostalCode` | کد ملی و کد پستی |
84
- | `validateMobile`، `validateLandline` | بررسی قالب و پیش‌شماره پشتیبانی‌شده |
85
- | `validateNationalId`، `validatePostalCode` | بررسی قواعد مستندشده |
86
- | `createRandom(seed)` | منبع تصادفی deterministic برای ترکیب APIها |
87
-
88
- نوع‌های فیلد پشتیبانی‌شده:
145
+ ```ts
146
+ const mobile = persianMock.field("phone.mobile", { seed: "signup-form" });
147
+ const nationalId = persianMock.field("identity.nationalId", { seed: 1405 });
148
+ ```
149
+
150
+ ## Generate complete form data
151
+
152
+ ```ts
153
+ const registrationData = persianMock.generate(
154
+ {
155
+ firstName: { type: "person.firstName" },
156
+ lastName: { type: "person.lastName" },
157
+ mobile: { type: "phone.mobile" },
158
+ nationalId: { type: "identity.nationalId" },
159
+ postalCode: { type: "address.postalCode" },
160
+ },
161
+ { seed: "registration-test-1" },
162
+ );
163
+ ```
164
+
165
+ Supported field types:
89
166
 
90
167
  ```ts
91
168
  type FieldType =
@@ -98,65 +175,207 @@ type FieldType =
98
175
  | "address.postalCode";
99
176
  ```
100
177
 
101
- ## قراردادهای اعتبارسنجی
178
+ ## Generate invalid and edge-case data
102
179
 
103
- ### کد ملی
180
+ Use named scenarios to target one validation rule at a time:
104
181
 
105
- تابع `validateNationalId` دقیقاً قرارداد مرجع صاحب پروژه را اجرا می‌کند:
182
+ ```ts
183
+ const invalidNationalId = persianMock.field("identity.nationalId", {
184
+ mode: "invalid",
185
+ scenario: "wrong-checksum",
186
+ seed: 1405,
187
+ });
106
188
 
107
- - ورودی باید دقیقاً ۱۰ رقم ASCII باشد.
108
- - `0000000000` و ارقام تکراری `2222222222` تا `9999999999` رد می‌شوند.
109
- - ۹ رقم اول با وزن‌های ۱۰ تا ۲ جمع می‌شوند.
110
- - اگر `weightedSum % 11` کمتر از ۲ باشد، رقم کنترل همان باقیمانده است؛ در غیر
111
- این صورت رقم کنترل `11 - remainder` است.
112
- - مقدار `1111111111` مطابق تابع مرجع **پذیرفته می‌شود** و برای این رفتار تست
113
- رگرسیون وجود دارد.
189
+ const persianDigitMobile = persianMock.field("phone.mobile", {
190
+ mode: "invalid",
191
+ scenario: "persian-digits",
192
+ seed: 1405,
193
+ });
194
+ ```
114
195
 
115
- این کتابخانه عمداً سیاست سخت‌گیرانه دیگری را به‌صورت بی‌صدا اعمال نمی‌کند.
196
+ Use `case()` when your test needs metadata explaining the result:
116
197
 
117
- ### موبایل
198
+ ```ts
199
+ const generatedCase = persianMock.case("phone.mobile", {
200
+ mode: "invalid",
201
+ scenario: "unsupported-prefix",
202
+ seed: 1405,
203
+ });
118
204
 
119
- شماره داخلی ۱۱ رقمی با ارقام ASCII و یکی از پیش‌شماره‌های موجود در
120
- `MOBILE_PREFIXES` پذیرفته می‌شود. فهرست صریح export شده تا سیاست پشتیبانی قابل
121
- مشاهده و قابل به‌روزرسانی باشد.
205
+ // {
206
+ // type: "phone.mobile",
207
+ // value: "...",
208
+ // expectedValid: false,
209
+ // scenario: "unsupported-prefix",
210
+ // violatedRule: "Mobile prefix must be in the supported-prefix list."
211
+ // }
212
+ ```
122
213
 
123
- ### تلفن ثابت
214
+ Generate every supported invalid scenario for a field:
124
215
 
125
- قالب داخلی ۱۱ رقمی شامل کد منطقه سه‌رقمی پشتیبانی‌شده و شماره مشترک هشت‌رقمی
126
- است. رقم اول شماره مشترک بین ۲ تا ۸ است. `generateLandline` علاوه بر `value`،
127
- `areaCode` و `province` سازگار با آن را برمی‌گرداند.
216
+ ```ts
217
+ const nationalIdCases = persianMock.edgeCases("identity.nationalId", 1405);
218
+ const postalCodeCases = persianMock.edgeCases("address.postalCode", 1405);
219
+ ```
128
220
 
129
- ### کد پستی
221
+ Generate a form in invalid mode while selecting scenarios per field:
130
222
 
131
- سیاست format-level کتابخانه ده رقم ASCII است و در پنج رقم اول `0` و `2`
132
- پذیرفته نمی‌شود. این بررسی تخصیص رسمی یا قابل تحویل بودن کد را ثابت نمی‌کند.
223
+ ```ts
224
+ const invalidForm = persianMock.generate(
225
+ {
226
+ mobile: {
227
+ type: "phone.mobile",
228
+ scenario: "unsupported-prefix",
229
+ },
230
+ nationalId: {
231
+ type: "identity.nationalId",
232
+ scenario: "forbidden-repeated",
233
+ },
234
+ },
235
+ { mode: "invalid", seed: 1405 },
236
+ );
237
+ ```
133
238
 
134
- ## سناریوهای نامعتبر
239
+ ## Invalid scenario reference
135
240
 
136
- | فیلد | سناریوها |
241
+ | Field | Available scenarios |
137
242
  | --- | --- |
138
- | نام‌ها | `empty`، `whitespace`، `too-long`، `invisible-character` |
139
- | موبایل | `missing-leading-zero`، `unsupported-prefix`، `too-short`، `non-numeric`، `persian-digits` |
140
- | تلفن ثابت | `missing-leading-zero`، `unsupported-area`، `too-short`، `non-numeric`، `persian-digits` |
141
- | کد ملی | `wrong-checksum`، `wrong-length`، `non-numeric`، `persian-digits`، `forbidden-repeated` |
142
- | کد پستی | `wrong-length`، `non-numeric`، `invalid-prefix`، `persian-digits` |
243
+ | Persian names | `empty`, `whitespace`, `too-long`, `invisible-character` |
244
+ | Mobile | `missing-leading-zero`, `unsupported-prefix`, `too-short`, `non-numeric`, `persian-digits` |
245
+ | Landline | `missing-leading-zero`, `unsupported-area`, `too-short`, `non-numeric`, `persian-digits` |
246
+ | National ID | `wrong-checksum`, `wrong-length`, `non-numeric`, `persian-digits`, `forbidden-repeated` |
247
+ | Postal code | `wrong-length`, `non-numeric`, `invalid-prefix`, `persian-digits` |
248
+
249
+ TypeScript prevents selecting a scenario that does not belong to the selected
250
+ field. The runtime API also throws a `RangeError` for incompatible scenarios.
251
+
252
+ ## Validation
253
+
254
+ ```ts
255
+ import {
256
+ validateLandline,
257
+ validateMobile,
258
+ validateNationalId,
259
+ validatePersianName,
260
+ validatePostalCode,
261
+ } from "persian-mock-data";
262
+
263
+ validatePersianName("مریم احمدی");
264
+ validateMobile("09123456789");
265
+ validateLandline("02123456789");
266
+ validateNationalId("1111111111");
267
+ validatePostalCode("1345678901");
268
+ ```
143
269
 
144
- TypeScript انتخاب scenario ناسازگار با نوع فیلد را هنگام توسعه رد می‌کند؛ API
145
- در runtime نیز ورودی ناسازگار را با `RangeError` متوقف می‌کند.
270
+ ### National ID contract
146
271
 
147
- ## توسعه و بررسی
272
+ `validateNationalId()` implements the project owner's reference behavior:
273
+
274
+ 1. The input must contain exactly 10 ASCII digits.
275
+ 2. `0000000000` and repeated values from `2222222222` through `9999999999`
276
+ are rejected.
277
+ 3. The first nine digits are multiplied by weights 10 through 2.
278
+ 4. When `weightedSum % 11` is less than 2, the check digit equals the
279
+ remainder. Otherwise, it equals `11 - remainder`.
280
+ 5. `1111111111` is accepted, matching the reference implementation.
281
+
282
+ The library deliberately does not apply an undocumented stricter policy.
283
+
284
+ ### Mobile contract
285
+
286
+ A mobile value must contain 11 ASCII digits and start with one of the prefixes
287
+ exported through `MOBILE_PREFIXES`. This is a supported-format check, not proof
288
+ that the number is allocated or reachable.
289
+
290
+ ### Landline contract
291
+
292
+ A landline value must contain 11 ASCII digits, begin with an area code exported
293
+ through `LANDLINE_AREAS`, and have an eight-digit subscriber number beginning
294
+ with a digit from 2 through 8.
295
+
296
+ ### Postal-code contract
297
+
298
+ A postal code must contain 10 ASCII digits. The first five positions must not
299
+ contain `0` or `2`. This is a format-level rule and does not prove official
300
+ allocation or deliverability.
301
+
302
+ ## Shared seeded random source
303
+
304
+ Use one random source when composing generators manually:
305
+
306
+ ```ts
307
+ import {
308
+ createRandom,
309
+ generateFullName,
310
+ generateMobile,
311
+ generateNationalId,
312
+ } from "persian-mock-data";
313
+
314
+ const random = createRandom("checkout-fixture");
315
+
316
+ const fixture = {
317
+ fullName: generateFullName(random),
318
+ mobile: generateMobile(random),
319
+ nationalId: generateNationalId(random),
320
+ };
321
+ ```
322
+
323
+ ## API reference
324
+
325
+ | Export | Description |
326
+ | --- | --- |
327
+ | `persianMock.generate()` | Generate raw values matching an object schema |
328
+ | `persianMock.field()` | Generate one raw valid or invalid field value |
329
+ | `persianMock.case()` | Generate one field with validity metadata |
330
+ | `persianMock.edgeCases()` | Generate all invalid scenarios for one field |
331
+ | `createRandom()` | Create a deterministic random source |
332
+ | `generateFirstName()` | Generate a Persian first name |
333
+ | `generateLastName()` | Generate a Persian last name |
334
+ | `generateFullName()` | Generate a Persian full name |
335
+ | `generateMobile()` | Generate a supported Iranian mobile format |
336
+ | `generateLandline()` | Generate a landline with area metadata |
337
+ | `generateNationalId()` | Generate a national ID accepted by the reference validator |
338
+ | `calculateNationalIdCheckDigit()` | Calculate a check digit from nine ASCII digits |
339
+ | `generatePostalCode()` | Generate a format-valid postal code |
340
+ | `validatePersianName()` | Validate the supported Persian-name policy |
341
+ | `validateMobile()` | Validate mobile format and supported prefix |
342
+ | `validateLandline()` | Validate landline format and supported area |
343
+ | `validateNationalId()` | Validate the documented national-ID algorithm |
344
+ | `validatePostalCode()` | Validate the documented postal-code format |
345
+ | `MOBILE_PREFIXES` | Inspect the supported mobile-prefix policy |
346
+ | `LANDLINE_AREAS` | Inspect supported landline areas and provinces |
347
+ | `INVALID_SCENARIOS` | Inspect available invalid scenarios |
348
+ | `VIOLATED_RULES` | Inspect human-readable validation-rule descriptions |
349
+
350
+ ## Development
148
351
 
149
352
  ```bash
353
+ git clone https://github.com/Ali-Shahnoushi/persian-mock-data.git
354
+ cd persian-mock-data
355
+ npm install
150
356
  npm run check
151
357
  ```
152
358
 
153
- این دستور type-check، تمام تست‌ها و build نهایی را اجرا می‌کند. تست‌ها رفتار
154
- مرزی `1111111111`، رد ارقام فارسی در فیلدهای ASCII، تمام سناریوهای نامعتبر و
155
- ثبات خروجی seed شده را پوشش می‌دهند.
359
+ Available commands:
360
+
361
+ ```bash
362
+ npm run typecheck # Strict TypeScript check
363
+ npm test # Run the test suite once
364
+ npm run test:watch # Run tests in watch mode
365
+ npm run build # Build ESM, CommonJS, and declarations
366
+ npm run check # Type-check, test, and build
367
+ ```
368
+
369
+ ## Contributing
370
+
371
+ Issues and pull requests are welcome. When adding or changing a validation
372
+ rule, please include tests and document what the rule verifies—and what it does
373
+ not verify.
156
374
 
157
- برنامه مرحله‌ای در [docs/IMPLEMENTATION_PLAN.md](./docs/IMPLEMENTATION_PLAN.md)
158
- ثبت شده است.
375
+ - [Report an issue](https://github.com/Ali-Shahnoushi/persian-mock-data/issues)
376
+ - [View the source](https://github.com/Ali-Shahnoushi/persian-mock-data)
377
+ - [View the npm package](https://www.npmjs.com/package/persian-mock-data)
159
378
 
160
- ## مجوز
379
+ ## License
161
380
 
162
- [MIT](./LICENSE)
381
+ Released under the [MIT License](./LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "persian-mock-data",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Deterministic, framework-agnostic Iranian mock data generators and validators.",
5
5
  "keywords": [
6
6
  "iran",