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.
- package/README.md +306 -87
- package/package.json +1 -1
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).
|