persian-mock-data 0.0.0-stage → 0.1.0
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 +21 -0
- package/README.en.md +146 -0
- package/README.md +161 -2
- package/dist/index.cjs +606 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +203 -0
- package/dist/index.d.ts +203 -0
- package/dist/index.js +557 -0
- package/dist/index.js.map +1 -0
- package/package.json +52 -4
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,162 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Persian Mock Data Factory
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[English documentation](./README.en.md)
|
|
4
|
+
|
|
5
|
+
کتابخانهای مستقل از فریمورک و نوشتهشده با TypeScript برای تولید دادههای
|
|
6
|
+
آزمایشی ایرانی، سناریوهای نامعتبر نامگذاریشده و دادههای قابل بازتولید با
|
|
7
|
+
`seed`.
|
|
8
|
+
|
|
9
|
+
> این پروژه دادههایی تولید میکند که از **قواعد قالب و الگوریتم مستندشده**
|
|
10
|
+
> عبور میکنند. خروجی به معنای وجود شخص واقعی، فعال بودن شماره تلفن، ثبت رسمی
|
|
11
|
+
> کد ملی یا قابل تحویل بودن نشانی و کد پستی نیست.
|
|
12
|
+
|
|
13
|
+
## وضعیت پروژه
|
|
14
|
+
|
|
15
|
+
هسته نسخه `0.1.0` پیادهسازی شده است، اما پکیج هنوز در npm منتشر نشده. برای
|
|
16
|
+
استفاده در توسعه:
|
|
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
|
+
خروجی build شامل ESM، CommonJS و فایلهای type declaration است و به React،
|
|
26
|
+
Vue، Angular، Next.js یا فریمورک دیگری وابستگی ندارد.
|
|
27
|
+
|
|
28
|
+
## شروع سریع
|
|
29
|
+
|
|
30
|
+
### تولید یک فرم معتبر و قابل بازتولید
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
import { persianMock } from "persian-mock-data";
|
|
34
|
+
|
|
35
|
+
const user = persianMock.generate(
|
|
36
|
+
{
|
|
37
|
+
fullName: { type: "person.fullName" },
|
|
38
|
+
mobile: { type: "phone.mobile" },
|
|
39
|
+
landline: { type: "phone.landline" },
|
|
40
|
+
nationalId: { type: "identity.nationalId" },
|
|
41
|
+
postalCode: { type: "address.postalCode" },
|
|
42
|
+
},
|
|
43
|
+
{ seed: 1405 },
|
|
44
|
+
);
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
همان schema با همان `seed` همیشه همان خروجی را تولید میکند. تمام فیلدهای یک
|
|
48
|
+
schema از یک جریان تصادفی مشترک استفاده میکنند.
|
|
49
|
+
|
|
50
|
+
### تولید داده نامعتبر هدفمند
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
const invalidId = persianMock.field("identity.nationalId", {
|
|
54
|
+
mode: "invalid",
|
|
55
|
+
scenario: "wrong-checksum",
|
|
56
|
+
seed: 1405,
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
const explained = persianMock.case("phone.mobile", {
|
|
60
|
+
mode: "invalid",
|
|
61
|
+
scenario: "persian-digits",
|
|
62
|
+
seed: 1405,
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`field` مقدار خام و `case` مقدار همراه با `expectedValid`، نام سناریو و
|
|
67
|
+
`violatedRule` را برمیگرداند. برای تمام حالتهای مرزی یک فیلد:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
const cases = persianMock.edgeCases("address.postalCode", 1405);
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## API عمومی
|
|
74
|
+
|
|
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
|
+
نوعهای فیلد پشتیبانیشده:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
type FieldType =
|
|
92
|
+
| "person.firstName"
|
|
93
|
+
| "person.lastName"
|
|
94
|
+
| "person.fullName"
|
|
95
|
+
| "phone.mobile"
|
|
96
|
+
| "phone.landline"
|
|
97
|
+
| "identity.nationalId"
|
|
98
|
+
| "address.postalCode";
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## قراردادهای اعتبارسنجی
|
|
102
|
+
|
|
103
|
+
### کد ملی
|
|
104
|
+
|
|
105
|
+
تابع `validateNationalId` دقیقاً قرارداد مرجع صاحب پروژه را اجرا میکند:
|
|
106
|
+
|
|
107
|
+
- ورودی باید دقیقاً ۱۰ رقم ASCII باشد.
|
|
108
|
+
- `0000000000` و ارقام تکراری `2222222222` تا `9999999999` رد میشوند.
|
|
109
|
+
- ۹ رقم اول با وزنهای ۱۰ تا ۲ جمع میشوند.
|
|
110
|
+
- اگر `weightedSum % 11` کمتر از ۲ باشد، رقم کنترل همان باقیمانده است؛ در غیر
|
|
111
|
+
این صورت رقم کنترل `11 - remainder` است.
|
|
112
|
+
- مقدار `1111111111` مطابق تابع مرجع **پذیرفته میشود** و برای این رفتار تست
|
|
113
|
+
رگرسیون وجود دارد.
|
|
114
|
+
|
|
115
|
+
این کتابخانه عمداً سیاست سختگیرانه دیگری را بهصورت بیصدا اعمال نمیکند.
|
|
116
|
+
|
|
117
|
+
### موبایل
|
|
118
|
+
|
|
119
|
+
شماره داخلی ۱۱ رقمی با ارقام ASCII و یکی از پیششمارههای موجود در
|
|
120
|
+
`MOBILE_PREFIXES` پذیرفته میشود. فهرست صریح export شده تا سیاست پشتیبانی قابل
|
|
121
|
+
مشاهده و قابل بهروزرسانی باشد.
|
|
122
|
+
|
|
123
|
+
### تلفن ثابت
|
|
124
|
+
|
|
125
|
+
قالب داخلی ۱۱ رقمی شامل کد منطقه سهرقمی پشتیبانیشده و شماره مشترک هشترقمی
|
|
126
|
+
است. رقم اول شماره مشترک بین ۲ تا ۸ است. `generateLandline` علاوه بر `value`،
|
|
127
|
+
`areaCode` و `province` سازگار با آن را برمیگرداند.
|
|
128
|
+
|
|
129
|
+
### کد پستی
|
|
130
|
+
|
|
131
|
+
سیاست format-level کتابخانه ده رقم ASCII است و در پنج رقم اول `0` و `2`
|
|
132
|
+
پذیرفته نمیشود. این بررسی تخصیص رسمی یا قابل تحویل بودن کد را ثابت نمیکند.
|
|
133
|
+
|
|
134
|
+
## سناریوهای نامعتبر
|
|
135
|
+
|
|
136
|
+
| فیلد | سناریوها |
|
|
137
|
+
| --- | --- |
|
|
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` |
|
|
143
|
+
|
|
144
|
+
TypeScript انتخاب scenario ناسازگار با نوع فیلد را هنگام توسعه رد میکند؛ API
|
|
145
|
+
در runtime نیز ورودی ناسازگار را با `RangeError` متوقف میکند.
|
|
146
|
+
|
|
147
|
+
## توسعه و بررسی
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
npm run check
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
این دستور type-check، تمام تستها و build نهایی را اجرا میکند. تستها رفتار
|
|
154
|
+
مرزی `1111111111`، رد ارقام فارسی در فیلدهای ASCII، تمام سناریوهای نامعتبر و
|
|
155
|
+
ثبات خروجی seed شده را پوشش میدهند.
|
|
156
|
+
|
|
157
|
+
برنامه مرحلهای در [docs/IMPLEMENTATION_PLAN.md](./docs/IMPLEMENTATION_PLAN.md)
|
|
158
|
+
ثبت شده است.
|
|
159
|
+
|
|
160
|
+
## مجوز
|
|
161
|
+
|
|
162
|
+
[MIT](./LICENSE)
|