@naturalcycles/nodejs-lib 15.43.1 → 15.44.0

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

@@ -1,5 +1,5 @@
 import type { Set2 } from '@naturalcycles/js-lib/object';
-import { type AnyObject, type IsoDate, type IsoDateTime, type NumberEnum, type StringEnum, type StringMap, type UnixTimestamp, type UnixTimestampMillis } from '@naturalcycles/js-lib/types';
+import { type AnyObject, type IANATimezone, type IsoDate, type IsoDateTime, type NumberEnum, type StringEnum, type StringMap, type UnixTimestamp, type UnixTimestampMillis } from '@naturalcycles/js-lib/types';
 export declare const j: {
     string(): JsonSchemaStringBuilder<string, string, false>;
     number(): JsonSchemaNumberBuilder<number, number, false>;
@@ -12,7 +12,7 @@ export declare const j: {
     array<IN, OUT, Opt>(itemSchema: JsonSchemaAnyBuilder<IN, OUT, Opt>): JsonSchemaArrayBuilder<IN, OUT, Opt>;
     set<IN, OUT, Opt>(itemSchema: JsonSchemaAnyBuilder<IN, OUT, Opt>): JsonSchemaSet2Builder<IN, OUT, Opt>;
     buffer(): JsonSchemaBufferBuilder;
-    enum<const T extends readonly (string | number | boolean | null)[] | StringEnum | NumberEnum>(input: T): JsonSchemaEnumBuilder<T extends readonly (infer U)[] ? U : T extends StringEnum ? T[keyof T] : T extends NumberEnum ? T[keyof T] : never>;
+    enum<const T extends readonly (string | number | boolean | null)[] | StringEnum | NumberEnum>(input: T, opt?: JsonBuilderRuleOpt): JsonSchemaEnumBuilder<T extends readonly (infer U)[] ? U : T extends StringEnum ? T[keyof T] : T extends NumberEnum ? T[keyof T] : never>;
     oneOf<B extends readonly JsonSchemaAnyBuilder<any, any, boolean>[], IN = BuilderInUnion<B>, OUT = BuilderOutUnion<B>>(items: [...B]): JsonSchemaAnyBuilder<IN, OUT, false>;
 };
 export declare class JsonSchemaAnyBuilder<IN, OUT, Opt> {
@@ -91,6 +91,13 @@ export declare class JsonSchemaStringBuilder<IN extends string = string, OUT = I
     languageTag(): this;
     countryCode(): this;
     currency(): this;
+    /**
+     * Validates that the input is a valid IANATimzone value.
+     *
+     * All previous expectations in the schema chain are dropped - including `.optional()` -
+     * because this call effectively starts a new schema chain as an `enum` validation.
+     */
+    ianaTimezone(): JsonSchemaEnumBuilder<string | IANATimezone, IANATimezone, false>;
 }
 export interface JsonSchemaStringEmailOptions {
     checkTLD: boolean;
@@ -177,7 +184,8 @@ export declare class JsonSchemaBufferBuilder extends JsonSchemaAnyBuilder<string
     constructor();
 }
 export declare class JsonSchemaEnumBuilder<IN extends string | number | boolean | null, OUT extends IN = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
-    constructor(enumValues: readonly IN[]);
+    constructor(enumValues: readonly IN[], opt?: JsonBuilderRuleOpt);
+    branded<B extends IN>(): JsonSchemaEnumBuilder<B | IN, B, Opt>;
 }
 export interface JsonSchema<IN = unknown, OUT = IN> {
     readonly in?: IN;

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();
@@ -32,7 +32,7 @@ export const j = {
     buffer() {
         return new JsonSchemaBufferBuilder();
     },
-    enum(input) {
+    enum(input, opt) {
         let enumValues;
         if (Array.isArray(input)) {
             enumValues = input;
@@ -47,7 +47,7 @@ export const j = {
             }
         }
         _assert(enumValues, 'Unsupported enum input');
-        return new JsonSchemaEnumBuilder(enumValues);
+        return new JsonSchemaEnumBuilder(enumValues, opt);
     },
     oneOf(items) {
         const schemas = items.map(b => b.build());
@@ -275,6 +275,18 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
         const regex = /^[A-Z]{3}$/;
         return this.regex(regex, { msg: 'is not a valid currency format' });
     }
+    /**
+     * Validates that the input is a valid IANATimzone value.
+     *
+     * All previous expectations in the schema chain are dropped - including `.optional()` -
+     * because this call effectively starts a new schema chain as an `enum` validation.
+     */
+    ianaTimezone() {
+        // UTC is added to assist unit-testing, which uses UTC by default (not technically a valid Iana timezone identifier)
+        return j
+            .enum([...Intl.supportedValuesOf('timeZone'), 'UTC'], { msg: 'is an invalid IANA timezone' })
+            .branded();
+    }
 }
 export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
     constructor() {
@@ -520,8 +532,13 @@ export class JsonSchemaBufferBuilder extends JsonSchemaAnyBuilder {
     }
 }
 export class JsonSchemaEnumBuilder extends JsonSchemaAnyBuilder {
-    constructor(enumValues) {
+    constructor(enumValues, opt) {
         super({ enum: enumValues });
+        if (opt?.msg)
+            this.setErrorMessage('enum', opt.msg);
+    }
+    branded() {
+        return this;
     }
 }
 function object(props) {

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.44.0",
   "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,11 +9,11 @@ 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 {
   type AnyObject,
+  type IANATimezone,
   type IsoDate,
   type IsoDateTime,
   JWT_REGEX,
@@ -23,6 +23,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> {
@@ -63,6 +64,7 @@ export const j = {
 
   enum<const T extends readonly (string | number | boolean | null)[] | StringEnum | NumberEnum>(
     input: T,
+    opt?: JsonBuilderRuleOpt,
   ): JsonSchemaEnumBuilder<
     T extends readonly (infer U)[]
       ? U
@@ -86,7 +88,7 @@ export const j = {
     }
 
     _assert(enumValues, 'Unsupported enum input')
-    return new JsonSchemaEnumBuilder(enumValues as any)
+    return new JsonSchemaEnumBuilder(enumValues as any, opt)
   },
 
   oneOf<
@@ -369,6 +371,19 @@ export class JsonSchemaStringBuilder<
     const regex = /^[A-Z]{3}$/
     return this.regex(regex, { msg: 'is not a valid currency format' })
   }
+
+  /**
+   * Validates that the input is a valid IANATimzone value.
+   *
+   * All previous expectations in the schema chain are dropped - including `.optional()` -
+   * because this call effectively starts a new schema chain as an `enum` validation.
+   */
+  ianaTimezone(): JsonSchemaEnumBuilder<string | IANATimezone, IANATimezone, false> {
+    // UTC is added to assist unit-testing, which uses UTC by default (not technically a valid Iana timezone identifier)
+    return j
+      .enum([...Intl.supportedValuesOf('timeZone'), 'UTC'], { msg: 'is an invalid IANA timezone' })
+      .branded<IANATimezone>()
+  }
 }
 
 export interface JsonSchemaStringEmailOptions {
@@ -750,8 +765,14 @@ export class JsonSchemaEnumBuilder<
   OUT extends IN = IN,
   Opt extends boolean = false,
 > extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
-  constructor(enumValues: readonly IN[]) {
+  constructor(enumValues: readonly IN[], opt?: JsonBuilderRuleOpt) {
     super({ enum: enumValues })
+
+    if (opt?.msg) this.setErrorMessage('enum', opt.msg)
+  }
+
+  branded<B extends IN>(): JsonSchemaEnumBuilder<B | IN, B, Opt> {
+    return this as unknown as JsonSchemaEnumBuilder<B | IN, B, Opt>
   }
 }
 

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 })
+}