@sleekcms/json-zen 1.4.0 → 1.5.0

package/README.md

@@ -2,6 +2,8 @@
 
 A compact, string-based schema syntax for validating and shaping JSON objects — with far less boilerplate than JSON Schema.
 
+Try it live at **[json-zen.sleekcms.site](https://json-zen.sleekcms.site/)**.
+
 ## Installation
 
 ```bash
@@ -79,11 +81,12 @@ verify([1, 'x', 2, 'y'], '[n,s]');  // true — alternating number/string
 
 ### Optional fields (`?`)
 
-Prefix a type with `?` to make it optional. A missing or `null` value passes validation.
+For object properties, suffix the key with `?` to make it optional (TypeScript-style). For array elements, prefix the type with `?`. A missing or `null` value passes validation.
 
 ```js
-verify({ a: 1 }, '{a:n, b:?s}');    // true — b is missing but optional
-verify({ a: 1, b: null }, '{a:n, b:?s}'); // true
+verify({ a: 1 }, '{a:n, b?:s}');    // true — b is missing but optional
+verify({ a: 1, b: null }, '{a:n, b?:s}'); // true
+verify([1, null, 3], '[?n]');       // true — array elements are optional
 ```
 
 ### Presence-only validation
@@ -198,12 +201,12 @@ shape({ a: {} }, '{a:{x:n, y:s}}');
 
 | Option      | Type      | Description                                                  |
 |-------------|-----------|--------------------------------------------------------------|
-| `_optional` | `boolean` | When `true`, fill optional (`?`) fields with defaults instead of `null` |
+| `fillNulls` | `boolean` | When `true`, fill optional (`?`) fields with defaults instead of `null` |
 | _(key)_     | validator | Inline custom type                                           |
 
 ```js
-shape({}, '{a:?n}');                   // { a: null }
-shape({}, '{a:?n}', { _optional: true }); // { a: 0 }
+shape({}, '{a?:n}');                   // { a: null }
+shape({}, '{a?:n}', { fillNulls: true }); // { a: 0 }
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleekcms/json-zen",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Easify verify and shape JSON objects using a simplified alternative JSON schema",
   "main": "./lib/index.js",
   "module": "./lib/esm/index.js",

package/src/index.ts

@@ -82,6 +82,11 @@ export const typeShape = (schema: string): TypeShape => {
       return sch.split(",").reduce((acc: { [key: string]: TypeShape }, name) => {
         let [k, v] = splitOnce(name, ":");
         if (k.match(RX.DEFAULTS)) k = default_strings[Number(k.slice(1))];
+        // TypeScript-style optional: key? instead of ?type
+        if (k.endsWith('?')) {
+          k = k.slice(0, -1);
+          v = '?' + v;
+        }
         acc[k] = traverse(v);
         return acc;
       }, {});
@@ -136,14 +141,14 @@ export const toSchema = (json: unknown, options: ToSchemaOptions = {}): string =
 };
 
 export interface ShapeOptions {
-  _optional?: boolean;
+  fillNulls?: boolean;
   [key: string]: unknown;
 }
 
 export const shape = <T = unknown>(json: unknown, schema: string, options: ShapeOptions = {}): T => {
   const types = new ZenTypes(options);
 
-  options._optional = options._optional || false;
+  options.fillNulls = options.fillNulls || false;
   let lookups: string[];
   let default_strings: string[];
   [schema, lookups, default_strings] = _flatten(schema);
@@ -177,7 +182,7 @@ export const shape = <T = unknown>(json: unknown, schema: string, options: Shape
     // if lookup, validate further
     if (schema.match(RX.LOOKUP)) return traverse({ value, schema: `${optional ? '?' : ''}${lookups[Number(schema)]}` });
 
-    if ((value === null || value === undefined) && optional && !options._optional) return null;
+    if ((value === null || value === undefined) && optional && !options.fillNulls) return null;
 
     if (schema.match(RX.FLAT_SCALAR)) {
       // if scalar
@@ -212,6 +217,11 @@ export const shape = <T = unknown>(json: unknown, schema: string, options: Shape
         let [k, t, d] = name.split(":");
         if (!t) t = "";
         if (d) t += ":" + d;
+        // TypeScript-style optional: key? instead of ?type
+        if (k.endsWith('?')) {
+          k = k.slice(0, -1);
+          t = '?' + t;
+        }
         if (k === "*") wildcard = t;
         else acc[k] = traverse({ value: obj[k], schema: t });
         return acc;
@@ -304,6 +314,11 @@ export const verify = (json: unknown, schema: string, options: VerifyOptions = {
         const keys = schema.split(",").reduce((acc: Record<string, string>, name) => {
           let [k, t] = name.split(":");
           if (!t) t = "";
+          // TypeScript-style optional: key? instead of ?type
+          if (k.endsWith('?')) {
+            k = k.slice(0, -1);
+            t = '?' + t;
+          }
           if (k === '*') wildcard = t;
           else acc[k] = t;
           return acc;