persian-mock-data 0.1.0 → 0.1.2
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/README.md +306 -87
- package/package.json +1 -1
- package/README.en.md +0 -146
package/README.md
CHANGED
|
@@ -1,19 +1,62 @@
|
|
|
1
|
-
# Persian Mock Data
|
|
1
|
+
# Persian Mock Data
|
|
2
2
|
|
|
3
|
-
[
|
|
3
|
+
[](https://www.npmjs.com/package/persian-mock-data)
|
|
4
|
+
[](https://www.npmjs.com/package/persian-mock-data)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
[](https://www.typescriptlang.org/)
|
|
4
7
|
|
|
5
|
-
|
|
6
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
48
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
}
|
|
95
|
+
import {
|
|
96
|
+
generateMobile,
|
|
97
|
+
persianMock,
|
|
98
|
+
validateMobile,
|
|
99
|
+
} from "persian-mock-data";
|
|
100
|
+
```
|
|
58
101
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
102
|
+
### CommonJS
|
|
103
|
+
|
|
104
|
+
```js
|
|
105
|
+
const {
|
|
106
|
+
generateMobile,
|
|
107
|
+
persianMock,
|
|
108
|
+
validateMobile,
|
|
109
|
+
} = require("persian-mock-data");
|
|
64
110
|
```
|
|
65
111
|
|
|
66
|
-
|
|
67
|
-
|
|
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
|
-
|
|
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
|
-
|
|
143
|
+
You can also generate a raw field value through the unified API:
|
|
74
144
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
|
|
182
|
+
```ts
|
|
183
|
+
const invalidNationalId = persianMock.field("identity.nationalId", {
|
|
184
|
+
mode: "invalid",
|
|
185
|
+
scenario: "wrong-checksum",
|
|
186
|
+
seed: 1405,
|
|
187
|
+
});
|
|
106
188
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
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
|
-
|
|
120
|
-
|
|
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
|
-
|
|
127
|
-
|
|
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
|
-
|
|
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
|
-
|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
|
|
|
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
|
-
|
|
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
|
-
|
|
154
|
-
|
|
155
|
-
|
|
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
|
-
|
|
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
package/README.en.md
DELETED
|
@@ -1,146 +0,0 @@
|
|
|
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)
|