persian-mock-data 0.0.0-stage → 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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ali Shahnoushi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md ADDED
@@ -0,0 +1,146 @@
1
+ # Persian Mock Data Factory
2
+
3
+ [مستندات فارسی](./README.md)
4
+
5
+ A framework-agnostic TypeScript library for deterministic Iranian mock data,
6
+ named invalid scenarios, and frontend form edge-case testing.
7
+
8
+ > The library creates data that satisfies its **documented format and
9
+ > algorithm rules**. It does not assert that a person exists, a phone is
10
+ > reachable, a national ID is officially assigned, or a postal code is
11
+ > deliverable.
12
+
13
+ ## Project status
14
+
15
+ The `0.1.0` core is implemented, but the package has not been published to npm.
16
+ For local development:
17
+
18
+ ```bash
19
+ git clone https://github.com/Ali-Shahnoushi/persian-mock-data.git
20
+ cd persian-mock-data
21
+ npm install
22
+ npm run build
23
+ ```
24
+
25
+ The build produces ESM, CommonJS, and TypeScript declarations without a UI
26
+ framework dependency.
27
+
28
+ ## Quick start
29
+
30
+ ```ts
31
+ import { persianMock } from "persian-mock-data";
32
+
33
+ const user = persianMock.generate(
34
+ {
35
+ fullName: { type: "person.fullName" },
36
+ mobile: { type: "phone.mobile" },
37
+ landline: { type: "phone.landline" },
38
+ nationalId: { type: "identity.nationalId" },
39
+ postalCode: { type: "address.postalCode" },
40
+ },
41
+ { seed: 1405 },
42
+ );
43
+ ```
44
+
45
+ The same schema and seed always produce the same object. A schema uses one
46
+ shared random stream, so the entire fixture is reproducible.
47
+
48
+ ### Target one validation rule
49
+
50
+ ```ts
51
+ const invalidId = persianMock.field("identity.nationalId", {
52
+ mode: "invalid",
53
+ scenario: "wrong-checksum",
54
+ seed: 1405,
55
+ });
56
+
57
+ const explained = persianMock.case("phone.mobile", {
58
+ mode: "invalid",
59
+ scenario: "persian-digits",
60
+ seed: 1405,
61
+ });
62
+
63
+ const allPostalCases = persianMock.edgeCases("address.postalCode", 1405);
64
+ ```
65
+
66
+ `field()` returns the raw string. `case()` and `edgeCases()` also return
67
+ `expectedValid`, the scenario name, and a human-readable `violatedRule`.
68
+
69
+ ## Public API
70
+
71
+ | API | Purpose |
72
+ | --- | --- |
73
+ | `persianMock.generate(schema, options)` | Generate form-shaped raw values |
74
+ | `persianMock.field(type, options)` | Generate one raw field value |
75
+ | `persianMock.case(type, options)` | Generate one value with validity metadata |
76
+ | `persianMock.edgeCases(type, seed)` | Generate every invalid scenario for a field |
77
+ | `generateFirstName`, `generateLastName`, `generateFullName` | Generate Persian mock names |
78
+ | `generateMobile`, `generateLandline` | Generate supported phone formats |
79
+ | `generateNationalId`, `generatePostalCode` | Generate identity/address formats |
80
+ | `validateMobile`, `validateLandline` | Validate format and supported prefixes |
81
+ | `validateNationalId`, `validatePostalCode` | Validate documented rules |
82
+ | `createRandom(seed)` | Compose generators with one seeded random source |
83
+
84
+ Supported field types are `person.firstName`, `person.lastName`,
85
+ `person.fullName`, `phone.mobile`, `phone.landline`,
86
+ `identity.nationalId`, and `address.postalCode`.
87
+
88
+ ## Validation contracts
89
+
90
+ ### National ID
91
+
92
+ `validateNationalId` implements the project owner's exact reference behavior:
93
+
94
+ - The input is exactly 10 ASCII digits.
95
+ - `0000000000` and repeated digits from `2222222222` through `9999999999` are
96
+ rejected.
97
+ - The first nine digits use weights 10 through 2.
98
+ - When `weightedSum % 11` is below 2, the check digit equals that remainder;
99
+ otherwise it equals `11 - remainder`.
100
+ - `1111111111` is accepted, matching the reference function. A regression test
101
+ protects this deliberate edge behavior.
102
+
103
+ No undocumented stricter policy is silently applied.
104
+
105
+ ### Mobile and landline
106
+
107
+ A mobile is 11 ASCII digits and starts with an explicitly supported four-digit
108
+ prefix exported as `MOBILE_PREFIXES`. A landline is 11 ASCII digits, starts
109
+ with one of the three-digit areas exported as `LANDLINE_AREAS`, and has an
110
+ eight-digit subscriber number beginning with 2 through 8. `generateLandline`
111
+ returns matching `value`, `areaCode`, and `province` fields.
112
+
113
+ These policies validate the package's supported formats; they do not prove
114
+ that a number is allocated or reachable.
115
+
116
+ ### Postal code
117
+
118
+ The format-level policy is 10 ASCII digits with no `0` or `2` in the first five
119
+ positions. It does not verify official allocation or deliverability.
120
+
121
+ ## Named invalid scenarios
122
+
123
+ | Field | Scenarios |
124
+ | --- | --- |
125
+ | Names | `empty`, `whitespace`, `too-long`, `invisible-character` |
126
+ | Mobile | `missing-leading-zero`, `unsupported-prefix`, `too-short`, `non-numeric`, `persian-digits` |
127
+ | Landline | `missing-leading-zero`, `unsupported-area`, `too-short`, `non-numeric`, `persian-digits` |
128
+ | National ID | `wrong-checksum`, `wrong-length`, `non-numeric`, `persian-digits`, `forbidden-repeated` |
129
+ | Postal code | `wrong-length`, `non-numeric`, `invalid-prefix`, `persian-digits` |
130
+
131
+ TypeScript rejects scenarios that do not belong to a field. Runtime validation
132
+ also throws a `RangeError` for incompatible input.
133
+
134
+ ## Development
135
+
136
+ ```bash
137
+ npm run check
138
+ ```
139
+
140
+ The check runs strict type-checking, the full Vitest suite, and the production
141
+ build. See [the implementation plan](./docs/IMPLEMENTATION_PLAN.md) for the
142
+ phased design and verification approach.
143
+
144
+ ## License
145
+
146
+ [MIT](./LICENSE)
package/README.md CHANGED
@@ -1,3 +1,381 @@
1
- # Temporary Holding Version
1
+ # Persian Mock Data
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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/)
7
+
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.
12
+
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.
17
+
18
+ ## Features
19
+
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:
60
+
61
+ ```bash
62
+ git clone https://github.com/Ali-Shahnoushi/persian-mock-data.git
63
+ cd persian-mock-data
64
+ npm install
65
+ npm run build
66
+ ```
67
+
68
+ ## Quick start
69
+
70
+ ```ts
71
+ import { persianMock } from "persian-mock-data";
72
+
73
+ const user = persianMock.generate(
74
+ {
75
+ fullName: { type: "person.fullName" },
76
+ mobile: { type: "phone.mobile" },
77
+ landline: { type: "phone.landline" },
78
+ nationalId: { type: "identity.nationalId" },
79
+ postalCode: { type: "address.postalCode" },
80
+ },
81
+ { seed: 1405 },
82
+ );
83
+
84
+ console.log(user);
85
+ ```
86
+
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
91
+
92
+ ### ESM and TypeScript
93
+
94
+ ```ts
95
+ import {
96
+ generateMobile,
97
+ persianMock,
98
+ validateMobile,
99
+ } from "persian-mock-data";
100
+ ```
101
+
102
+ ### CommonJS
103
+
104
+ ```js
105
+ const {
106
+ generateMobile,
107
+ persianMock,
108
+ validateMobile,
109
+ } = require("persian-mock-data");
110
+ ```
111
+
112
+ ## Generate individual fields
113
+
114
+ Every generator accepts an optional number seed, string seed, or shared random
115
+ source.
116
+
117
+ ```ts
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
+ // }
141
+ ```
142
+
143
+ You can also generate a raw field value through the unified API:
144
+
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:
166
+
167
+ ```ts
168
+ type FieldType =
169
+ | "person.firstName"
170
+ | "person.lastName"
171
+ | "person.fullName"
172
+ | "phone.mobile"
173
+ | "phone.landline"
174
+ | "identity.nationalId"
175
+ | "address.postalCode";
176
+ ```
177
+
178
+ ## Generate invalid and edge-case data
179
+
180
+ Use named scenarios to target one validation rule at a time:
181
+
182
+ ```ts
183
+ const invalidNationalId = persianMock.field("identity.nationalId", {
184
+ mode: "invalid",
185
+ scenario: "wrong-checksum",
186
+ seed: 1405,
187
+ });
188
+
189
+ const persianDigitMobile = persianMock.field("phone.mobile", {
190
+ mode: "invalid",
191
+ scenario: "persian-digits",
192
+ seed: 1405,
193
+ });
194
+ ```
195
+
196
+ Use `case()` when your test needs metadata explaining the result:
197
+
198
+ ```ts
199
+ const generatedCase = persianMock.case("phone.mobile", {
200
+ mode: "invalid",
201
+ scenario: "unsupported-prefix",
202
+ seed: 1405,
203
+ });
204
+
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
+ ```
213
+
214
+ Generate every supported invalid scenario for a field:
215
+
216
+ ```ts
217
+ const nationalIdCases = persianMock.edgeCases("identity.nationalId", 1405);
218
+ const postalCodeCases = persianMock.edgeCases("address.postalCode", 1405);
219
+ ```
220
+
221
+ Generate a form in invalid mode while selecting scenarios per field:
222
+
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
+ ```
238
+
239
+ ## Invalid scenario reference
240
+
241
+ | Field | Available scenarios |
242
+ | --- | --- |
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
+ ```
269
+
270
+ ### National ID contract
271
+
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
351
+
352
+ ```bash
353
+ git clone https://github.com/Ali-Shahnoushi/persian-mock-data.git
354
+ cd persian-mock-data
355
+ npm install
356
+ npm run check
357
+ ```
358
+
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.
374
+
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)
378
+
379
+ ## License
380
+
381
+ Released under the [MIT License](./LICENSE).