@manassandhu/mint 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 Manas Sandhu
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.md CHANGED
@@ -1,3 +1,660 @@
1
- # Temporary Holding Version
1
+ # Mint
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
+ **A lightweight JavaScript schema validation library.**
4
+
5
+ Mint is a schema-based validation library for JavaScript that provides a simple, consistent way to validate, parse, and transform data. It supports primitive values, complex data structures, custom validation, asynchronous validation, and structured validation errors.
6
+
7
+ Define a schema once and use it to validate data wherever your application needs it.
8
+
9
+ ---
10
+
11
+ ## Features
12
+
13
+ - Simple, chainable schema API
14
+ - Validation for primitive types and complex data structures
15
+ - Object schemas with support for optional, partial, pick, omit, extend, and merge operations
16
+ - Array, tuple, record, union, and intersection schemas
17
+ - Set and Map validation
18
+ - Custom validation using refinements
19
+ - Data transformation
20
+ - Synchronous and asynchronous parsing
21
+ - Structured validation errors
22
+ - Safe parsing without throwing on validation failures
23
+ - JavaScript and ESM support
24
+
25
+ ---
26
+
27
+ ## Installation
28
+
29
+ ```bash
30
+ npm install @manas/mint
31
+ ```
32
+
33
+ ## Quick Start
34
+
35
+ ```javascript
36
+ import mint from "@manas/mint";
37
+
38
+ const userSchema = mint.object({
39
+ name: mint.string().min(2),
40
+ age: mint.number().min(18),
41
+ email: mint.string().email(),
42
+ });
43
+
44
+ const result = userSchema.safeParse({
45
+ name: "Manas",
46
+ age: 21,
47
+ email: "manas@example.com",
48
+ });
49
+
50
+ if (result.success) {
51
+ console.log("Valid data:", result.data);
52
+ } else {
53
+ console.log("Validation errors:", result.error.issues);
54
+ }
55
+ ```
56
+
57
+ ---
58
+
59
+ ## Basic Validation
60
+
61
+ Mint provides schemas for common JavaScript data types.
62
+
63
+ ```javascript
64
+ mint.string();
65
+ mint.number();
66
+ mint.boolean();
67
+ mint.bigint();
68
+ mint.date();
69
+
70
+ mint.null();
71
+ mint.undefined();
72
+ mint.void();
73
+
74
+ mint.any();
75
+ mint.unknown();
76
+ mint.never();
77
+ mint.symbol();
78
+ ```
79
+
80
+ ### String Validation
81
+
82
+ ```javascript
83
+ const usernameSchema = mint.string().min(3).max(20);
84
+
85
+ usernameSchema.parse("manas"); // Valid
86
+ usernameSchema.parse("ab"); // Throws validation error
87
+ ```
88
+
89
+ Email validation:
90
+
91
+ ```javascript
92
+ const emailSchema = mint.string().email();
93
+
94
+ emailSchema.safeParse("hello@example.com"); // Success
95
+ emailSchema.safeParse("invalid-email"); // Failure
96
+ ```
97
+
98
+ ### Number Validation
99
+
100
+ ```javascript
101
+ const ageSchema = mint.number().min(18).max(100);
102
+
103
+ ageSchema.safeParse(25); // Success
104
+ ageSchema.safeParse(15); // Failure
105
+ ```
106
+
107
+ ---
108
+
109
+ ## Parsing and Validation
110
+
111
+ Mint provides two primary ways to validate data.
112
+
113
+ ### `parse()`
114
+
115
+ Validates the input and returns the parsed value. Throws a validation error if the input is invalid.
116
+
117
+ ```javascript
118
+ const schema = mint.string();
119
+
120
+ schema.parse("hello"); // "hello"
121
+ schema.parse(123); // Throws MintError
122
+ ```
123
+
124
+ ### `safeParse()`
125
+
126
+ Validates the input without throwing a validation error. Returns a result object.
127
+
128
+ ```javascript
129
+ const schema = mint.number();
130
+
131
+ const result = schema.safeParse("hello");
132
+
133
+ if (result.success) {
134
+ console.log(result.data);
135
+ } else {
136
+ console.log(result.error);
137
+ }
138
+ ```
139
+
140
+ Successful results:
141
+
142
+ ```javascript
143
+ {
144
+ success: true,
145
+ data: 123
146
+ }
147
+ ```
148
+
149
+ Failed results:
150
+
151
+ ```javascript
152
+ {
153
+ success: false,
154
+ error: MintError
155
+ }
156
+ ```
157
+
158
+ ---
159
+
160
+ ## Optional, Nullable, and Default Values
161
+
162
+ ### Optional
163
+
164
+ Allows a value to be `undefined`.
165
+
166
+ ```javascript
167
+ const schema = mint.string().optional();
168
+
169
+ schema.safeParse(undefined); // Success
170
+ schema.safeParse("hello"); // Success
171
+ ```
172
+
173
+ ### Nullable
174
+
175
+ Allows a value to be `null`.
176
+
177
+ ```javascript
178
+ const schema = mint.string().nullable();
179
+
180
+ schema.safeParse(null); // Success
181
+ schema.safeParse("hello"); // Success
182
+ ```
183
+
184
+ ### Nullish
185
+
186
+ Allows both `null` and `undefined`.
187
+
188
+ ```javascript
189
+ const schema = mint.string().nullish();
190
+ ```
191
+
192
+ ### Default Values
193
+
194
+ Provides a default value when the input is `undefined`.
195
+
196
+ ```javascript
197
+ const schema = mint.string().default("Mint");
198
+
199
+ schema.parse(undefined); // "Mint"
200
+ ```
201
+
202
+ ---
203
+
204
+ ## Object Schemas
205
+
206
+ Object schemas validate the structure and values of objects.
207
+
208
+ ```javascript
209
+ const userSchema = mint.object({
210
+ name: mint.string(),
211
+ age: mint.number(),
212
+ active: mint.boolean(),
213
+ });
214
+
215
+ userSchema.safeParse({
216
+ name: "Manas",
217
+ age: 20,
218
+ active: true,
219
+ });
220
+ ```
221
+
222
+ ### Optional Properties
223
+
224
+ ```javascript
225
+ const userSchema = mint.object({
226
+ name: mint.string(),
227
+ email: mint.string().optional(),
228
+ });
229
+ ```
230
+
231
+ ### Partial Objects
232
+
233
+ Makes object properties optional.
234
+
235
+ ```javascript
236
+ const updateUserSchema = mint.object({
237
+ name: mint.string(),
238
+ age: mint.number(),
239
+ }).partial();
240
+ ```
241
+
242
+ ### Pick
243
+
244
+ Select specific properties from an object schema.
245
+
246
+ ```javascript
247
+ const userSchema = mint.object({
248
+ name: mint.string(),
249
+ age: mint.number(),
250
+ email: mint.string(),
251
+ });
252
+
253
+ const nameSchema = userSchema.pick(["name"]);
254
+ ```
255
+
256
+ ### Omit
257
+
258
+ Remove selected properties from an object schema.
259
+
260
+ ```javascript
261
+ const publicUserSchema = mint.object({
262
+ name: mint.string(),
263
+ age: mint.number(),
264
+ password: mint.string(),
265
+ }).omit(["password"]);
266
+ ```
267
+
268
+ ### Extend
269
+
270
+ Add properties to an existing object schema.
271
+
272
+ ```javascript
273
+ const userSchema = mint.object({
274
+ name: mint.string(),
275
+ });
276
+
277
+ const employeeSchema = userSchema.extend({
278
+ department: mint.string(),
279
+ });
280
+ ```
281
+
282
+ ### Merge
283
+
284
+ Combine object schemas.
285
+
286
+ ```javascript
287
+ const profileSchema = mint.object({
288
+ name: mint.string(),
289
+ });
290
+
291
+ const settingsSchema = mint.object({
292
+ active: mint.boolean(),
293
+ });
294
+
295
+ const combinedSchema = profileSchema.merge(settingsSchema);
296
+ ```
297
+
298
+ ---
299
+
300
+ ## Arrays
301
+
302
+ Validate arrays and their elements.
303
+
304
+ ```javascript
305
+ const tagsSchema = mint.array(mint.string());
306
+
307
+ tagsSchema.safeParse(["javascript", "validation", "mint"]);
308
+ ```
309
+
310
+ Array constraints:
311
+
312
+ ```javascript
313
+ const schema = mint.array(mint.number()).min(1).max(5);
314
+ ```
315
+
316
+ ---
317
+
318
+ ## Tuples
319
+
320
+ Validate arrays with position-specific schemas.
321
+
322
+ ```javascript
323
+ const schema = mint.tuple([
324
+ mint.string(),
325
+ mint.number(),
326
+ mint.boolean(),
327
+ ]);
328
+
329
+ schema.safeParse(["hello", 42, true]);
330
+ ```
331
+
332
+ ### Rest Elements
333
+
334
+ ```javascript
335
+ const schema = mint.tuple([
336
+ mint.string(),
337
+ mint.number(),
338
+ ]).rest(mint.boolean());
339
+
340
+ schema.safeParse(["hello", 42, true, false]);
341
+ ```
342
+
343
+ ---
344
+
345
+ ## Records
346
+
347
+ Validate objects whose values share a schema.
348
+
349
+ ```javascript
350
+ const scoresSchema = mint.record(mint.number());
351
+
352
+ scoresSchema.safeParse({
353
+ math: 95,
354
+ science: 88,
355
+ });
356
+ ```
357
+
358
+ Records can also validate keys:
359
+
360
+ ```javascript
361
+ const userRecordSchema = mint.record(
362
+ mint.number(),
363
+ mint.string().min(2),
364
+ );
365
+ ```
366
+
367
+ ---
368
+
369
+ ## Unions
370
+
371
+ Accept data matching at least one schema.
372
+
373
+ ```javascript
374
+ const schema = mint.union([
375
+ mint.string(),
376
+ mint.number(),
377
+ ]);
378
+
379
+ schema.safeParse("hello"); // Success
380
+ schema.safeParse(42); // Success
381
+ schema.safeParse(true); // Failure
382
+ ```
383
+
384
+ ---
385
+
386
+ ## Intersections
387
+
388
+ Combine validation requirements from multiple schemas.
389
+
390
+ ```javascript
391
+ const nameSchema = mint.object({
392
+ name: mint.string(),
393
+ });
394
+
395
+ const ageSchema = mint.object({
396
+ age: mint.number(),
397
+ });
398
+
399
+ const userSchema = mint.intersection(
400
+ nameSchema,
401
+ ageSchema,
402
+ );
403
+
404
+ userSchema.safeParse({
405
+ name: "Manas",
406
+ age: 21,
407
+ });
408
+ ```
409
+
410
+ ---
411
+
412
+ ## Enums and Literals
413
+
414
+ ### Literal
415
+
416
+ Validate an exact value.
417
+
418
+ ```javascript
419
+ const schema = mint.literal("mint");
420
+
421
+ schema.safeParse("mint"); // Success
422
+ schema.safeParse("other"); // Failure
423
+ ```
424
+
425
+ ### Enum
426
+
427
+ Validate against a fixed set of values.
428
+
429
+ ```javascript
430
+ const roleSchema = mint.enum([
431
+ "admin",
432
+ "user",
433
+ "guest",
434
+ ]);
435
+
436
+ roleSchema.safeParse("admin"); // Success
437
+ roleSchema.safeParse("unknown"); // Failure
438
+ ```
439
+
440
+ ---
441
+
442
+ ## Set and Map
443
+
444
+ ### Set
445
+
446
+ ```javascript
447
+ const schema = mint.set(mint.string()).min(1);
448
+
449
+ schema.safeParse(new Set(["mint", "javascript"]));
450
+ ```
451
+
452
+ ### Map
453
+
454
+ ```javascript
455
+ const schema = mint.map(
456
+ mint.string(),
457
+ mint.number(),
458
+ );
459
+
460
+ schema.safeParse(
461
+ new Map([
462
+ ["math", 95],
463
+ ["science", 88],
464
+ ]),
465
+ );
466
+ ```
467
+
468
+ ---
469
+
470
+ ## Custom Validation
471
+
472
+ Use `.refine()` to define custom validation rules.
473
+
474
+ ```javascript
475
+ const passwordSchema = mint.string().refine(
476
+ (password) => password.length >= 8,
477
+ );
478
+
479
+ passwordSchema.safeParse("strongpass"); // Success
480
+ passwordSchema.safeParse("short"); // Failure
481
+ ```
482
+
483
+ Custom validation can also be used inside object schemas.
484
+
485
+ ```javascript
486
+ const userSchema = mint.object({
487
+ username: mint.string().refine(
488
+ (value) => value.length >= 3,
489
+ ),
490
+ });
491
+ ```
492
+
493
+ ---
494
+
495
+ ## Transformations
496
+
497
+ Use `.transform()` to transform successfully parsed data.
498
+
499
+ ```javascript
500
+ const schema = mint.string().transform(
501
+ (value) => value.trim(),
502
+ );
503
+
504
+ schema.parse(" Mint "); // "Mint"
505
+ ```
506
+
507
+ Transforms can be combined with validation.
508
+
509
+ ```javascript
510
+ const schema = mint.string()
511
+ .transform((value) => value.trim())
512
+ .pipe(mint.string().min(1));
513
+ ```
514
+
515
+ ---
516
+
517
+ ## Asynchronous Validation
518
+
519
+ Mint supports asynchronous refinements and parsing.
520
+
521
+ ```javascript
522
+ const usernameSchema = mint.string().refine(
523
+ async (username) => {
524
+ // Example asynchronous check
525
+ return username.length >= 3;
526
+ },
527
+ );
528
+ ```
529
+
530
+ Use asynchronous parsing methods when schemas contain asynchronous validation.
531
+
532
+ ### `parseAsync()`
533
+
534
+ ```javascript
535
+ const result = await usernameSchema.parseAsync("manas");
536
+ ```
537
+
538
+ ### `safeParseAsync()`
539
+
540
+ ```javascript
541
+ const result = await usernameSchema.safeParseAsync("manas");
542
+
543
+ if (result.success) {
544
+ console.log(result.data);
545
+ } else {
546
+ console.log(result.error.issues);
547
+ }
548
+ ```
549
+
550
+ Asynchronous validation is also supported within composite schemas such as objects, arrays, tuples, records, unions, sets, and maps.
551
+
552
+ ---
553
+
554
+ ## Error Handling
555
+
556
+ Mint provides structured validation errors through `MintError`.
557
+
558
+ ```javascript
559
+ const schema = mint.object({
560
+ name: mint.string(),
561
+ age: mint.number(),
562
+ });
563
+
564
+ const result = schema.safeParse({
565
+ name: 123,
566
+ age: "invalid",
567
+ });
568
+
569
+ if (!result.success) {
570
+ console.log(result.error.issues);
571
+ }
572
+ ```
573
+
574
+ Each issue contains information about the validation failure, including its type, message, and location within the input.
575
+
576
+ You can use these issues to build custom error messages, form feedback, or API responses.
577
+
578
+ ---
579
+
580
+ ## Available Schemas
581
+
582
+ | Schema | Description |
583
+ |---|---|
584
+ | `string()` | String validation |
585
+ | `number()` | Number validation |
586
+ | `boolean()` | Boolean validation |
587
+ | `bigint()` | BigInt validation |
588
+ | `date()` | Date validation |
589
+ | `null()` | Null values |
590
+ | `undefined()` | Undefined values |
591
+ | `void()` | Void values |
592
+ | `any()` | Any value |
593
+ | `unknown()` | Unknown values |
594
+ | `never()` | No valid values |
595
+ | `symbol()` | Symbol values |
596
+ | `literal()` | Exact values |
597
+ | `enum()` | Fixed set of values |
598
+ | `array()` | Arrays |
599
+ | `object()` | Objects |
600
+ | `tuple()` | Fixed-position arrays |
601
+ | `record()` | Key-value objects |
602
+ | `union()` | Multiple possible schemas |
603
+ | `intersection()` | Combined schemas |
604
+ | `set()` | Set collections |
605
+ | `map()` | Map collections |
606
+ | `promise()` | Promise validation |
607
+ | `function()` | Function validation |
608
+ | `instance()` | Class instance validation |
609
+
610
+ ---
611
+
612
+ ## Development
613
+
614
+ Clone the repository and install dependencies.
615
+
616
+ ```bash
617
+ npm install
618
+ ```
619
+
620
+ ### Run Tests
621
+
622
+ ```bash
623
+ npm test
624
+ ```
625
+
626
+ ### Watch Tests
627
+
628
+ ```bash
629
+ npm run test:watch
630
+ ```
631
+
632
+ ### Generate Coverage
633
+
634
+ ```bash
635
+ npm run coverage
636
+ ```
637
+
638
+ ### Syntax Check
639
+
640
+ ```bash
641
+ npm run check
642
+ ```
643
+
644
+ ---
645
+
646
+ ## Project Status
647
+
648
+ Mint is currently under active development.
649
+
650
+ Version: **0.1.0**
651
+
652
+ ---
653
+
654
+ ## License
655
+
656
+ Add your chosen license here before publishing the package.
657
+
658
+ ---
659
+
660
+ Built with JavaScript.
package/package.json CHANGED
@@ -1,6 +1,36 @@
1
1
  {
2
2
  "name": "@manassandhu/mint",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Elegant schema validation for JavaScript and TypeScript",
5
+ "main": "./src/index.js",
6
+ "directories": {
7
+ "test": "tests"
8
+ },
9
+ "scripts": {
10
+ "test": "vitest run",
11
+ "test:watch": "vitest",
12
+ "coverage": "vitest run --coverage",
13
+ "check": "node --check src/index.js"
14
+ },
15
+ "keywords": [
16
+ "validation",
17
+ "schema",
18
+ "javascript",
19
+ "typescript",
20
+ "zod"
21
+ ],
22
+ "author": "",
23
+ "license": "MIT",
24
+ "type": "module",
25
+ "devDependencies": {
26
+ "@vitest/coverage-v8": "^5.1.1",
27
+ "vitest": "^5.1.1"
28
+ },
29
+ "exports": "./src/index.js",
30
+ "engines": {
31
+ "node": ">=18"
32
+ },
33
+ "files": [
34
+ "src"
35
+ ]
36
+ }