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 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
- # Temporary Holding Version
1
+ # Persian Mock Data Factory
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
+ [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)