schematox 0.0.2 → 0.0.4

package/README.md

@@ -4,19 +4,17 @@ SchmatoX is a lightweight library for creating JSON compatible schemas. The subj
 
 ## Pros
 
-- The statically defined JSON compatible schema is a killer feature:
-  - It has great potential for automation in the context of DB model creation, CRUD backends, documentation, outer interface requirements etc.
-  - One can store schema changes as static JSON and potentially use it for creating coherent DB Model migration logic.
-  - One can check if the defined schema is compatible with our constraints using the "as const satisfies Schema".
-- Programmatically defined schemas are also supported, but as a means of creating statically defined schemas.
-- There is a clear separation of concerns for validating and parsing logic.
-  - The Schematox parser is used for dealing with an outer interface where the data type is not guaranteed.
-  - The Schematox validator is used for dealing with an internal interface where the data type is known.
-- Schematox uses an Ether-style error handling system. It never throws an error on an unsuccessful schema subject check. Instead, our parser/validator always returns an `EitherError` object.
-- We offer first-class support for branded base schema types.
+- The statically defined JSON compatible schema
+- Check defined schema correctness using non generic type `Schema`
+- Programmatically defined schemas supported as mean of creation statically defined schema
+- Clear separation of concerns for validating and parsing logic:
+  - Parser is used for dealing with an outer uknnown interface
+  - Validator is used for dealing with an internal known interface
+- Schematox uses an Ether-style error handling
+- We offer first-class support for branded base schema primitive types
 - We have zero dependencies. The runtime code logic is small and easy to grasp, consisting of just a couple of functions. Most of the library code is tests and types.
 
-Essentially, to define a schema, one doesn't even need to import any functions from our library, only the `Schema` type. This approach does come with a few limitations. The first is `stringUnion` and `numberUnion` schema default values are not constrained by the defined union choices, only the primitive type. We might fix this issue later, but for now, we prioritize this over the case when `default` extends union choice by its definition.
+Essentially, to define a schema, one doesn't need to import any functions from our library, only the `as const satisfies Schema` statement. This approach does come with a few limitations. The first is `stringUnion` and `numberUnion` schema default values are not constrained by the defined union choices, only the primitive type. We might fix this issue later, but for now, we prioritize this over the case when `default` extends union choice by its definition.
 
 A second limitation is the depth of the compound schema data structure. Currently, we support 7 layers of depth. It's easy to increase this number, but because of the exponential nature of stored type variants in memory, we want to determine how much RAM each next layer will use before increasing it.
 
@@ -24,11 +22,13 @@ It's crucial to separate parsing/validation logic from the schema itself. Librar
 
 ## Cons
 
+- The library is not ready for production yet, the version is 0 and public API might be changed
 - Currently we support only 7 layers of compound structure depth but most likely it will be higher soon
 - We do not support records, discriminated unions, object unions, array unions, intersections, functions, NaN, Infinity and other not JSON compatible structures
 - Null value is acceptable by the parser but will be treated as undefined and transformed to undefined
 - Null value is not acceptable by the validator
-- We only plan to support custom parser/normalizer integration logic.
+
+Check out [github issues](https://github.com/incerta/schematox/issues) of the project to know what we are planning to support soon.
 
 ## Installation
 
@@ -169,7 +169,6 @@ import {
   string,
   number,
   boolean,
-  buffer,
   stringUnion,
   numberUnion,
 } from 'schematox'
@@ -243,28 +242,6 @@ const programmaticBoolean = boolean()
   .brand('x', 'y')
   .description('y')
 
-// buffer
-// The default value is not supported because Buffer is not compatible with JSON
-
-const staticShortBufferRequired = 'buffer' satisfies Schema
-const staticShortBufferOptional = 'buffer?' satisfies Schema
-
-const staticDetailedBuffer = {
-  type: 'buffer',
-  optional: true,
-  brand: ['x', 'y'],
-  minLength: 1,
-  maxLength: 1,
-  description: 'x',
-} as const satisfies Schema
-
-const programmaticBuffer = buffer()
-  .optional()
-  .minLength(1)
-  .maxLength(1)
-  .brand('x', 'y')
-  .description('y')
-
 // stringUnion
 
 const staticStringUnion = {
@@ -359,41 +336,32 @@ The `result.error` will be:
 
 ## Parse/validate differences
 
-The parser provides a new object/primitive without references to the evaluated subject, except in the case of `Buffer` for better performance. This functionality is responsible for clearing the `array` schema result value from `undefined` optional schema values.
+The parser returns `data` as new object/primitive without references to the parsed subject. Parser manages the `null` value as `undefined` and subsequently replaces it with `undefined`. It also swaps `optional` values with the `default` value from schema. One can infer schema parsed subject type by using `XParsed<typeof schema>` generic.
 
-Moreover, the parser manages the `null` value as `undefined` and subsequently replaces it with `undefined`. It also swaps `optional` values with the `default` value, provided that the default values are explicitly stated in the schema.
+The validator on the other hand returns the evaluated subject itself and not applying any mutation/transformation to it. The validator should be used in exceptional cases when we known subject type but not sure that it actually correct. One can infer schema validated subject type by using `XValidated<typeof schema>` generic.
 
-Particularly for this last function, the parser uses a separate type inference flow. This flow is accessible for the library user via the type generic `XParsed<T extends Schema>`. By leveraging this mechanism, the user can simplify the process and enhance efficiency.
+So the difference between `XParsed` and `XValidated` is just about handling `default` schema value. `XParsed` narrows optional schema subject type with default value in the way that it will not be optional, because optional `undefined` and `null` values will be replaced by the `default`. `XValidated` just ignores `default` schema value.
 
-The validator operates by returning a reference to the original object, rather than applying any form of mutations to it. This is a significant feature because it disregards the schema’s default values.
-
-Furthermore, the validator incorporates a type inference flow distinct from the parser's. Available for utilization through the type generic `XValidated<T extends Schema>`.
-
-Examples of described differences:
+Examples:
 
 ```typescript
 const optionalStrX = x('string?')
 
-/* Parser treats `null` as `undefined` */
-
-expect(optionalStrX.parse(null).data).toBe(undefined)
-expect(optionalStrX.parse(null).error).toBe(undefined)
-
-/* Validator is not */
+/* Parser doesn't check subject type */
 
-// @ts-expect-error 'null' is not assignable to parameter of type 'string | undefined'
-expect(optionalStrX.validate(null).error).toStrictEqual([
+expect(optionalStrX.parse(0).error).toStrictEqual([
   {
     code: 'INVALID_TYPE',
     schema: 'string?',
-    subject: null,
+    subject: 0,
     path: [],
   },
 ])
 
-/* Parser doesn't check subject type */
+/* Validator does */
 
-expect(optionalStrX.parse(0).error).toStrictEqual([
+// @ts-expect-error 'number' is not 'string'
+expect(optionalStrX.validate(0).error).toStrictEqual([
   {
     code: 'INVALID_TYPE',
     schema: 'string?',
@@ -402,14 +370,19 @@ expect(optionalStrX.parse(0).error).toStrictEqual([
   },
 ])
 
-/* Validator does */
+/* Parser treats `null` as `undefined` */
 
-// @ts-expect-error 'number' is not assignable to parameter of type 'string'
-expect(optionalStrX.validate(0).error).toStrictEqual([
+expect(optionalStrX.parse(null).data).toBe(undefined)
+expect(optionalStrX.parse(null).error).toBe(undefined)
+
+/* Validator is not */
+
+// @ts-expect-error 'null' is not 'string | undefined'
+expect(optionalStrX.validate(null).error).toStrictEqual([
   {
     code: 'INVALID_TYPE',
     schema: 'string?',
-    subject: 0,
+    subject: null,
     path: [],
   },
 ])
@@ -425,17 +398,6 @@ expect(defaultedStrX.parse(undefined).data).toBe('y')
 
 expect(defaultedStrX.validate(undefined).data).toBe(undefined)
 
-/* Parser clears subject array from optional undefined */
-
-const arrX = x({ type: 'array', of: 'string?' })
-const subject = [undefined, 'y', undefined, 'z']
-
-expect(arrX.parse(subject).data).toStrictEqual(['y', 'z'])
-
-/* Validator keeps them */
-
-expect(arrX.validate(subject).data).toStrictEqual(subject)
-
 /* Parser returning new object */
 
 expect(arrX.parse(subject).data === subject).toBe(false)

package/dist/base-schema-parser.d.ts

@@ -1,6 +1,5 @@
-/// <reference types="node" />
 import type { EitherError } from './utils/fp';
 import type { BaseSchema, Con_Schema_SubjT_P } from './types/compound-schema-types';
 import type { BaseSchemaParseError } from './error';
-export type BaseSchemaSubjectType = string | number | boolean | Buffer | undefined;
+export type BaseSchemaSubjectType = string | number | boolean | undefined;
 export declare function parseBaseSchemaSubject<T extends BaseSchema>(schema: T, schemaSubject: unknown): EitherError<BaseSchemaParseError, Con_Schema_SubjT_P<T>>;

package/dist/base-schema-parser.js

@@ -68,22 +68,6 @@ function parseBaseSchemaSubject(schema, subject) {
                 }
                 return (0, fp_1.data)(subject);
             }
-            case 'buffer?':
-            case 'buffer': {
-                if (Buffer.isBuffer(subject) === false) {
-                    if (subject === null || subject === undefined) {
-                        if (schema === 'buffer?') {
-                            return (0, fp_1.data)(undefined);
-                        }
-                    }
-                    return (0, fp_1.error)({
-                        code: error_1.PARSE_ERROR_CODE.invalidType,
-                        schema: schema,
-                        subject: subject,
-                    });
-                }
-                return (0, fp_1.data)(subject);
-            }
         }
     }
     switch (schema.type) {
@@ -171,39 +155,6 @@ function parseBaseSchemaSubject(schema, subject) {
             }
             return (0, fp_1.data)(subject);
         }
-        case 'buffer': {
-            if (Buffer.isBuffer(subject) === false) {
-                if (subject === undefined || subject === null) {
-                    if (schema.optional) {
-                        return (0, fp_1.data)(undefined);
-                    }
-                }
-                return (0, fp_1.error)({
-                    code: error_1.PARSE_ERROR_CODE.invalidType,
-                    schema: schema,
-                    subject: subject,
-                });
-            }
-            if (typeof schema.minLength === 'number') {
-                if (subject.length < schema.minLength) {
-                    return (0, fp_1.error)({
-                        code: error_1.PARSE_ERROR_CODE.minRange,
-                        schema: schema,
-                        subject: subject,
-                    });
-                }
-            }
-            if (typeof schema.maxLength === 'number') {
-                if (subject.length > schema.maxLength) {
-                    return (0, fp_1.error)({
-                        code: error_1.PARSE_ERROR_CODE.maxRange,
-                        schema: schema,
-                        subject: subject,
-                    });
-                }
-            }
-            return (0, fp_1.data)(subject);
-        }
         case 'stringUnion': {
             if (typeof subject !== 'string') {
                 if (subject === undefined || subject === null) {

package/dist/base-schema-validator.d.ts

@@ -1,6 +1,5 @@
-/// <reference types="node" />
 import type { EitherError } from './utils/fp';
 import type { BaseSchema, Con_Schema_SubjT_V } from './types/compound-schema-types';
 import type { BaseSchemaValidateError } from './error';
-export type BaseSchemaSubjectType = string | number | boolean | Buffer | undefined;
+export type BaseSchemaSubjectType = string | number | boolean | undefined;
 export declare function validateBaseSchemaSubject<T extends BaseSchema>(schema: T, schemaSubject: unknown): EitherError<BaseSchemaValidateError, Con_Schema_SubjT_V<T>>;

package/dist/base-schema-validator.js

@@ -62,20 +62,6 @@ function validateBaseSchemaSubject(schema, subject) {
                 }
                 return (0, fp_1.data)(subject);
             }
-            case 'buffer?':
-            case 'buffer': {
-                if (Buffer.isBuffer(subject) === false) {
-                    if (subject === undefined && schema === 'buffer?') {
-                        return (0, fp_1.data)(undefined);
-                    }
-                    return (0, fp_1.error)({
-                        code: error_1.VALIDATE_ERROR_CODE.invalidType,
-                        schema: schema,
-                        subject: subject,
-                    });
-                }
-                return (0, fp_1.data)(subject);
-            }
         }
     }
     switch (schema.type) {
@@ -168,37 +154,6 @@ function validateBaseSchemaSubject(schema, subject) {
             }
             return (0, fp_1.data)(subject);
         }
-        case 'buffer': {
-            if (Buffer.isBuffer(subject) === false) {
-                if (subject === undefined && schema.optional) {
-                    return (0, fp_1.data)(undefined);
-                }
-                return (0, fp_1.error)({
-                    code: error_1.VALIDATE_ERROR_CODE.invalidType,
-                    schema: schema,
-                    subject: subject,
-                });
-            }
-            if (typeof schema.minLength === 'number') {
-                if (subject.length < schema.minLength) {
-                    return (0, fp_1.error)({
-                        code: error_1.VALIDATE_ERROR_CODE.minRange,
-                        schema: schema,
-                        subject: subject,
-                    });
-                }
-            }
-            if (typeof schema.maxLength === 'number') {
-                if (subject.length > schema.maxLength) {
-                    return (0, fp_1.error)({
-                        code: error_1.VALIDATE_ERROR_CODE.maxRange,
-                        schema: schema,
-                        subject: subject,
-                    });
-                }
-            }
-            return (0, fp_1.data)(subject);
-        }
         case 'stringUnion': {
             if (typeof subject !== 'string') {
                 if (subject === undefined && schema.optional) {

package/dist/general-schema-parser.js

@@ -45,7 +45,6 @@ function parse(schema, subject) {
         schema.type === 'string' ||
         schema.type === 'number' ||
         schema.type === 'boolean' ||
-        schema.type === 'buffer' ||
         schema.type === 'stringUnion' ||
         schema.type === 'numberUnion') {
         var parsed = (0, base_schema_parser_1.parseBaseSchemaSubject)(schema, subject);
@@ -113,9 +112,7 @@ function parse(schema, subject) {
             parsed.error.forEach(function (err) { return errors.push(err); });
             continue;
         }
-        if (parsed.data !== undefined) {
-            result.push(parsed.data);
-        }
+        result.push(parsed.data);
     }
     if (errors.length) {
         return (0, fp_1.error)(errors);

package/dist/general-schema-validator.js

@@ -45,7 +45,6 @@ function validate(schema, subject) {
         schema.type === 'string' ||
         schema.type === 'number' ||
         schema.type === 'boolean' ||
-        schema.type === 'buffer' ||
         schema.type === 'stringUnion' ||
         schema.type === 'numberUnion') {
         var validated = (0, base_schema_validator_1.validateBaseSchemaSubject)(schema, subject);

package/dist/index.js

@@ -8,7 +8,7 @@
  * but only with a MINOR version update.
  **/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.x = exports.validate = exports.parse = exports.object = exports.array = exports.numberUnion = exports.stringUnion = exports.buffer = exports.boolean = exports.number = exports.string = void 0;
+exports.x = exports.validate = exports.parse = exports.object = exports.array = exports.numberUnion = exports.stringUnion = exports.boolean = exports.number = exports.string = void 0;
 /* Programmatically base schema definition */
 var string_1 = require("./programmatic-schema/string");
 Object.defineProperty(exports, "string", { enumerable: true, get: function () { return string_1.string; } });
@@ -16,8 +16,6 @@ var number_1 = require("./programmatic-schema/number");
 Object.defineProperty(exports, "number", { enumerable: true, get: function () { return number_1.number; } });
 var boolean_1 = require("./programmatic-schema/boolean");
 Object.defineProperty(exports, "boolean", { enumerable: true, get: function () { return boolean_1.boolean; } });
-var buffer_1 = require("./programmatic-schema/buffer");
-Object.defineProperty(exports, "buffer", { enumerable: true, get: function () { return buffer_1.buffer; } });
 var string_union_1 = require("./programmatic-schema/string-union");
 Object.defineProperty(exports, "stringUnion", { enumerable: true, get: function () { return string_union_1.stringUnion; } });
 var number_union_1 = require("./programmatic-schema/number-union");

package/dist/index.ts

@@ -18,7 +18,6 @@ import type {
 export { string } from './programmatic-schema/string'
 export { number } from './programmatic-schema/number'
 export { boolean } from './programmatic-schema/boolean'
-export { buffer } from './programmatic-schema/buffer'
 export { stringUnion } from './programmatic-schema/string-union'
 export { numberUnion } from './programmatic-schema/number-union'
 

package/dist/types/base-detailed-schema-types.ts

@@ -36,17 +36,6 @@ export type BD_Boolean = {
   brand?: BrandSchema
 }
 
-export type BD_Buffer = {
-  type: 'buffer'
-  optional?: boolean
-
-  description?: string
-  brand?: BrandSchema
-
-  minLength?: number /* >= */
-  maxLength?: number /* <= */
-}
-
 export type BD_StringUnion<T extends string = string> = {
   type: 'stringUnion'
   of: Readonly<Array<T>>
@@ -71,7 +60,6 @@ export type BD_Schema =
   | BD_String
   | BD_Number
   | BD_Boolean
-  | BD_Buffer
   | BD_StringUnion
   | BD_NumberUnion
 
@@ -82,13 +70,11 @@ export type Con_BD_Schema_TypeOnly_SubjT<T extends BD_Schema> =
       ? number
       : T extends BD_Boolean
         ? boolean
-        : T extends BD_Buffer
-          ? Buffer
-          : T extends BD_StringUnion<infer U>
-            ? U
-            : T extends BD_NumberUnion<infer V>
-              ? V
-              : never
+        : T extends BD_StringUnion<infer U>
+          ? U
+          : T extends BD_NumberUnion<infer V>
+            ? V
+            : never
 
 export type Con_BrandSchema_SubjT<T extends BrandSchema> = T extends Readonly<
   [infer U, infer V]

package/dist/types/base-short-schema-types.ts

@@ -7,20 +7,9 @@ export type BS_Number_Opt = 'number?'
 export type BS_Boolean_Req = 'boolean'
 export type BS_Boolean_Opt = 'boolean?'
 
-export type BS_Buffer_Req = 'buffer'
-export type BS_Buffer_Opt = 'buffer?'
+export type BS_Schema_Req = BS_String_Req | BS_Number_Req | BS_Boolean_Req
 
-export type BS_Schema_Req =
-  | BS_String_Req
-  | BS_Number_Req
-  | BS_Boolean_Req
-  | BS_Buffer_Req
-
-export type BS_Schema_Opt =
-  | BS_String_Opt
-  | BS_Number_Opt
-  | BS_Boolean_Opt
-  | BS_Buffer_Opt
+export type BS_Schema_Opt = BS_String_Opt | BS_Number_Opt | BS_Boolean_Opt
 
 export type BS_Schema = BS_Schema_Req | BS_Schema_Opt
 
@@ -31,9 +20,7 @@ export type Con_BS_Schema_Req_SubjT<T extends BS_Schema_Req> =
       ? number
       : T extends BS_Boolean_Req
         ? boolean
-        : T extends BS_Buffer_Req
-          ? Buffer
-          : never
+        : never
 
 export type Con_BS_Schema_Opt_SubjT<T extends BS_Schema_Opt> =
   T extends BS_String_Opt
@@ -42,9 +29,7 @@ export type Con_BS_Schema_Opt_SubjT<T extends BS_Schema_Opt> =
       ? number | undefined
       : T extends BS_Boolean_Opt
         ? boolean | undefined
-        : T extends BS_Buffer_Opt
-          ? Buffer | undefined
-          : never
+        : never
 
 export type Con_BS_Schema_SubjT<T extends BS_Schema> = T extends BS_Schema_Req
   ? Con_BS_Schema_Req_SubjT<T>

package/dist/types/compound-schema-types.ts

@@ -63,12 +63,6 @@ export type ExtWith_CompoundSchemaOptionality<
   U,
 > = T extends { optional: true } ? U | undefined : U
 
-// TODO: should work as expected only if we add `& {}`
-//        which is currently forbidden by our linter
-export type Prettify_ObjectSchema_SubjT<T> = {
-  [k in keyof T]: T[k]
-}
-
 /* Construct ArraySchema subject type */
 
 export type Con_ArraySchema_SubjT_P<T extends ArraySchema> =
@@ -76,11 +70,11 @@ export type Con_ArraySchema_SubjT_P<T extends ArraySchema> =
     T,
     T extends { of: infer U }
       ? U extends BaseSchema
-        ? Array<NonNullable<Con_BaseSchema_SubjT_P<U>>>
+        ? Array<Con_BaseSchema_SubjT_P<U>>
         : U extends ArraySchema
-          ? Array<NonNullable<Con_ArraySchema_SubjT_P<U>>>
+          ? Array<Con_ArraySchema_SubjT_P<U>>
           : U extends ObjectSchema
-            ? Array<NonNullable<Con_ObjectSchema_SubjT_P<U>>>
+            ? Array<Con_ObjectSchema_SubjT_P<U>>
             : never
       : never
   >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schematox",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Define JSON compatible schema statically/programmatically and parse/validate its subject with typesafety",
   "author": "Konstantin Mazur",
   "license": "MIT",
@@ -34,7 +34,6 @@
   },
   "devDependencies": {
     "@types/jest": "^29.5.1",
-    "@types/node": "^20.1.4",
     "@typescript-eslint/eslint-plugin": "^5.59.5",
     "@typescript-eslint/parser": "^5.59.5",
     "eslint": "^8.40.0",
@@ -42,7 +41,6 @@
     "jest": "^29.5.0",
     "prettier": "^3.1.1",
     "ts-jest": "^29.1.0",
-    "ts-node": "^10.9.1",
     "typescript": "^5.0.4"
   }
 }