@naturalcycles/nodejs-lib 15.43.1 → 15.43.2

package/dist/validation/ajv/jsonSchemaBuilder.js

@@ -3,9 +3,9 @@
 import { _isUndefined, _numberEnumValues, _stringEnumValues, getEnumType, } from '@naturalcycles/js-lib';
 import { _uniq } from '@naturalcycles/js-lib/array';
 import { _assert } from '@naturalcycles/js-lib/error';
-import { JSON_SCHEMA_ORDER, mergeJsonSchemaObjects } from '@naturalcycles/js-lib/json-schema';
 import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object';
 import { JWT_REGEX, } from '@naturalcycles/js-lib/types';
+import { JSON_SCHEMA_ORDER, mergeJsonSchemaObjects } from './jsonSchemaBuilder.util.js';
 export const j = {
     string() {
         return new JsonSchemaStringBuilder();

package/dist/validation/ajv/jsonSchemaBuilder.util.d.ts

@@ -0,0 +1,9 @@
+import type { AnyObject } from '@naturalcycles/js-lib/types';
+import type { JsonSchema } from './jsonSchemaBuilder.js';
+export declare const JSON_SCHEMA_ORDER: string[];
+/**
+ * Merges s2 into s1 (mutates s1) and returns s1.
+ * Does not mutate s2.
+ * API similar to Object.assign(s1, s2)
+ */
+export declare function mergeJsonSchemaObjects<T1 extends AnyObject, T2 extends AnyObject>(schema1: JsonSchema<T1>, schema2: JsonSchema<T2>): JsonSchema<T1 & T2>;

package/dist/validation/ajv/jsonSchemaBuilder.util.js

@@ -0,0 +1,65 @@
+import { _uniq } from '@naturalcycles/js-lib/array';
+import { _filterNullishValues } from '@naturalcycles/js-lib/object';
+export const JSON_SCHEMA_ORDER = [
+    '$schema',
+    '$id',
+    'title',
+    'description',
+    'deprecated',
+    'readOnly',
+    'writeOnly',
+    'type',
+    'default',
+    // Object,
+    'properties',
+    'required',
+    'minProperties',
+    'maxProperties',
+    'patternProperties',
+    'propertyNames',
+    // Array
+    'properties',
+    'required',
+    'minProperties',
+    'maxProperties',
+    'patternProperties',
+    'propertyNames',
+    // String
+    'pattern',
+    'minLength',
+    'maxLength',
+    'format',
+    'transform',
+    // Number
+    'format',
+    'multipleOf',
+    'minimum',
+    'exclusiveMinimum',
+    'maximum',
+    'exclusiveMaximum',
+];
+/**
+ * Merges s2 into s1 (mutates s1) and returns s1.
+ * Does not mutate s2.
+ * API similar to Object.assign(s1, s2)
+ */
+export function mergeJsonSchemaObjects(schema1, schema2) {
+    const s1 = schema1;
+    const s2 = schema2;
+    // Merge `properties`
+    Object.entries(s2.properties).forEach(([k, v]) => {
+        s1.properties[k] = v;
+    });
+    // Merge `patternProperties`
+    Object.entries(s2.patternProperties || {}).forEach(([k, v]) => {
+        s1.patternProperties[k] = v;
+    });
+    s1.propertyNames = s2.propertyNames || s1.propertyNames;
+    s1.minProperties = s2.minProperties ?? s1.minProperties;
+    s1.maxProperties = s2.maxProperties ?? s1.maxProperties;
+    // Merge `required`
+    s1.required.push(...s2.required);
+    s1.required = _uniq(s1.required).sort();
+    // `additionalProperties` remains the same
+    return _filterNullishValues(s1, { mutate: true });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.43.1",
+  "version": "15.43.2",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@types/js-yaml": "^4",
@@ -71,7 +71,7 @@
     "directory": "packages/nodejs-lib"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=24.10.0"
   },
   "description": "Standard library for Node.js",
   "author": "Natural Cycles Team",

package/readme.md

@@ -11,10 +11,3 @@
 [![Actions](https://github.com/NaturalCycles/nodejs-lib/workflows/ci/badge.svg)](https://github.com/NaturalCycles/nodejs-lib/actions)
 
 # [Documentation](https://naturalcycles.github.io/nodejs-lib/)
-
-# Packaging
-
-- `engines.node`: Latest Node.js LTS
-- `main: dist/index.js`: commonjs, es2020
-- `types: dist/index.d.ts`: typescript types
-- `/src` folder with source `*.ts` files included

package/src/validation/ajv/j.readme.md

@@ -6,9 +6,112 @@
 
 In this document you can learn about how to use `j`, our new validation library.
 
+A schema speaks louder than a thousand words:
+
+```ts
+const dayInputSchema = j.object<DayInput>({
+  date: j.string().isoDate(),
+  isPeriod: j.boolean().optional(),
+  lhTest: j.enum(TestResult).nullable().optional(),
+  temp: j.integer().branded<CentiCelsius>().optional(),
+})
+```
+
+### How to use `j` for validation?
+
+While the API is very intuitive, there are some tips that can help with quick adoption:
+
+1. When you think of our custom types (e.g. IsoDate, UnixTimestamp or just "email"), first think
+   about its underlying type:
+
+```ts
+const timestamp = j.number().unixTimestamp2000() // start with ".number"
+const email = j.string().email() // start with ".string"
+const date = j.string().isoDate() // start with ".string"
+const dbRow = j.object.dbEntity({}) // start with ".object"
+```
+
+2. Probably the most important: object schemas must have a type
+
+```ts
+const schema1 = j.object({ foo: j.string() }) // ❌ Won't work.
+const schema2 = j.object<SomeType>({ foo: j.string() }) // ✅ Works just fine.
+```
+
+But because we do not always want to create a type or interface for every object schema, in those
+cases it's possible to use inference via `j.object.infer()`:
+
+```ts
+const schema3 = j.object.infer({ foo: j.string() }) // { foo: string } is inferred
+```
+
+⚠️ These inferred schemas cannot be used for validation - only to be passed into other schemas. If
+you forget, there will be an error thrown when the first validation is about to happen.
+
+```ts
+const schema1 = j.object.infer({ foo: j.string() }) // ❌ Using `schema1` in validation would fail
+
+// 💭 What this means is that you cannot use `schema1` to validate an input.
+// But you can use it inside another schema:
+
+const schema2 = j.object<SomeType>({ foo: schema1 }) // ✅ Using `schema1` inside another schema
+
+const schema3 = j.object<SomeType>({
+  foo: j.object.infer({ bar: j.string() }),
+}) // ✅ Using an inferred object inside another schema
+```
+
+This requirement is in place to enforce that we 1) have types for data that we validate, and 2) that
+mismatches between types and schemas become visible as soon as possible.
+
+3. Use `j.object.dbEntity()` for validating an object to be saved in Datastore
+
+```ts
+interface DBRow extends BaseDBEntity {
+  foo: string
+}
+
+const dbSchema = j.object.dbEntity<DBRow>({
+  foo: j.string(),
+})
+
+// 👆 is a shortcut for
+
+const dbSchema = j.object<DBRow>({
+  id: j.string(),
+  created: j.number().unixTimestamp2000(),
+  updated: j.number().unixTimestamp2000(),
+  foo: j.string(),
+})
+```
+
+The `dbEntity` helper also requires you to pass in a type. It will not work without it.
+
+4. Many branded values have no shortcut (on purpose), usually those that come with no actual
+   validation:
+
+```ts
+const accountId = j.string().accountId() // ❌
+const accountId = j.string().branded<AccountId>() // ✅
+```
+
+5. In some cases you can specify a custom error message
+
+When using regex validation, the resulting error message is generally not something we would want
+the user to see. In many case, they are also not very helpful for developers either. So, when
+running a regex validation, you can set a custom error message. This pattern can be extended to
+other validator functions too, as we think it's necessary.
+
+```ts
+const schema = j.object({
+  foo: j.string().regex(/\[a-z]{2,}\d?.+/, { msg: 'not a valid OompaLoompa!' }),
+})
+// will produce an error like "Object.foo is not a valid OompaLoompa!"
+```
+
 ### Why?
 
-Yet another validation library. But why? Main reasons:
+Why go into the trouble? Why not keep the JOI schemas? Well, the main reasons are:
 
 1. Faster validation
 2. Better DX
@@ -39,6 +142,18 @@ const newWay = j.object<SomeType>({
 // ... knowing to import `j`, and the rest is aided by auto-completion.
 ```
 
+Hopefully one welcomed change is how we handle `enum`s:
+
+```ts
+const oldWay1 = numberEnumValueSchema(TestResult)
+const newWay1 = j.enum(TestResult)
+
+const oldWay2 = stringEnumValueSchema(SKU)
+const newWay2 = j.enum(SKU)
+
+const newWay3 = j.enum([1, 2, 'foo', false]) // newWay satisfies 1 | 2 | 'foo' | false
+```
+
 **Stricter type validation** (aka worse DX) means that the schema and the types need to match
 exactly, unlike before where a required property could have had an optional schema.
 
@@ -65,75 +180,6 @@ const schema = j.object.infer({
 })
 ```
 
-### How to use `j` for validation?
-
-While the API is very intuitive, there are some tips that can help with quick adoption:
-
-1. When you want to use a specialized schema, first think about its underlying value:
-
-```ts
-const timestamp = j.number().unixTimestamp2000() // start with ".number"
-const email = j.string().email() // start with ".string"
-const date = j.string().isoDate() // start with ".string"
-const dbRow = j.object.dbEntity({}) // start with ".object"
-```
-
-2. Many branded values have no shortcut (on purpose), usually those that come with no actual
-   validation:
-
-```ts
-const accountId = j.string().accountId() // ❌
-const accountId = j.string().branded<AccountId>() // ✅
-```
-
-3. Probably the most important: object schemas must have a type
-
-```ts
-const schema1 = j.object({ foo: j.string() }) // ❌
-const schema2 = j.object<SomeType>({ bar: j.string(), nested: objectSchema1 }) // ✅
-```
-
-But because we do not always want to create a type or interface for every object schema, in those
-cases it's possible to use inference via `j.object.infer()`:
-
-```ts
-const schema3 = j.object.infer({ foo: j.string() }) // { foo: string } is inferred
-```
-
-But these inferred schemas cannot be used for validation - only to be passed into other schemas. To
-use inferred schemas in validation, you need to call `.ofType<SomeType>()` on them. If you forget,
-there will be an error thrown when the first validation is about to happen.
-
-```ts
-const schema1 = j.object.infer({ foo: j.string() }) // ❌ Using `schema1` in validation would fail
-
-const schema2 = j.object<SomeType>({ nestedProperty: schema1 }) // ✅ Using `schema1` inside another schema
-
-const schema3 = j.object.infer({ foo: j.string() }).isOfType<{ foo: string }>() // ✅ Using `schema3`  for validation
-```
-
-This requirement is in place to enforce that we 1) have types for data that we validate, and 2) that
-mismatches between types and schemas become visible as soon as possible.
-
-If the typing has a mismatch, then the `schema`'s type will become `never`. When using
-`j.object<SomeType>` the type error will be very helpful in identifying the mismatch. When using
-`j.object.infer().isOfType()` the type error will be very unhelpful. Because of this,
-`j.object<SomeType>` is the preferred choice.
-
-4. In some cases you can specify a custom error message
-
-When using regex validation, the resulting error message is generally not something we would want
-the user to see. In many case, they are also not very helpful for developers either. So, when
-running a regex validation, you can set a custom error message. This pattern can be extended to
-other validator functions too, as we think it's necessary.
-
-```ts
-const schema = j.object({
-  foo: j.string().regex(/\[a-z]{2,}\d?.+/, { msg: 'not a valid OompaLoompa! ' }),
-})
-// will produce an error like "Object.foo is not a valid OompaLoompa!"
-```
-
 ### More about `j`
 
 `j` is a JSON Schema builder that is developed in-house.

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -9,7 +9,6 @@ import {
 } from '@naturalcycles/js-lib'
 import { _uniq } from '@naturalcycles/js-lib/array'
 import { _assert } from '@naturalcycles/js-lib/error'
-import { JSON_SCHEMA_ORDER, mergeJsonSchemaObjects } from '@naturalcycles/js-lib/json-schema'
 import type { Set2 } from '@naturalcycles/js-lib/object'
 import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object'
 import {
@@ -23,6 +22,7 @@ import {
   type UnixTimestamp,
   type UnixTimestampMillis,
 } from '@naturalcycles/js-lib/types'
+import { JSON_SCHEMA_ORDER, mergeJsonSchemaObjects } from './jsonSchemaBuilder.util.js'
 
 export const j = {
   string(): JsonSchemaStringBuilder<string, string, false> {

package/src/validation/ajv/jsonSchemaBuilder.util.ts

@@ -0,0 +1,78 @@
+import { _uniq } from '@naturalcycles/js-lib/array'
+import { _filterNullishValues } from '@naturalcycles/js-lib/object'
+import type { AnyObject } from '@naturalcycles/js-lib/types'
+import type { JsonSchema } from './jsonSchemaBuilder.js'
+
+export const JSON_SCHEMA_ORDER = [
+  '$schema',
+  '$id',
+  'title',
+  'description',
+  'deprecated',
+  'readOnly',
+  'writeOnly',
+  'type',
+  'default',
+  // Object,
+  'properties',
+  'required',
+  'minProperties',
+  'maxProperties',
+  'patternProperties',
+  'propertyNames',
+  // Array
+  'properties',
+  'required',
+  'minProperties',
+  'maxProperties',
+  'patternProperties',
+  'propertyNames',
+  // String
+  'pattern',
+  'minLength',
+  'maxLength',
+  'format',
+  'transform',
+  // Number
+  'format',
+  'multipleOf',
+  'minimum',
+  'exclusiveMinimum',
+  'maximum',
+  'exclusiveMaximum',
+]
+
+/**
+ * Merges s2 into s1 (mutates s1) and returns s1.
+ * Does not mutate s2.
+ * API similar to Object.assign(s1, s2)
+ */
+export function mergeJsonSchemaObjects<T1 extends AnyObject, T2 extends AnyObject>(
+  schema1: JsonSchema<T1>,
+  schema2: JsonSchema<T2>,
+): JsonSchema<T1 & T2> {
+  const s1 = schema1 as any
+  const s2 = schema2 as any
+
+  // Merge `properties`
+  Object.entries(s2.properties).forEach(([k, v]) => {
+    s1.properties[k] = v
+  })
+
+  // Merge `patternProperties`
+  Object.entries(s2.patternProperties || {}).forEach(([k, v]) => {
+    s1.patternProperties[k] = v
+  })
+
+  s1.propertyNames = s2.propertyNames || s1.propertyNames
+  s1.minProperties = s2.minProperties ?? s1.minProperties
+  s1.maxProperties = s2.maxProperties ?? s1.maxProperties
+
+  // Merge `required`
+  s1.required.push(...s2.required)
+  s1.required = _uniq(s1.required).sort()
+
+  // `additionalProperties` remains the same
+
+  return _filterNullishValues(s1, { mutate: true })
+}