@naturalcycles/nodejs-lib 15.43.0 → 15.43.2

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

@@ -241,11 +241,14 @@ declare function object<IN extends AnyObject>(props: {
 }): JsonSchemaObjectBuilder<IN, IN, false>;
 declare function objectInfer<P extends Record<string, JsonSchemaAnyBuilder<any, any, any>>>(props: P): JsonSchemaObjectInferringBuilder<P, false>;
 declare function objectDbEntity(props?: AnyObject): never;
-declare function objectDbEntity<IN extends AnyObject>(props?: AnyObject): JsonSchemaObjectBuilder<IN, IN, false>;
+declare function objectDbEntity<IN extends AnyObject>(props?: {
+    [key in keyof PartiallyOptional<IN, 'id' | 'created' | 'updated'>]: JsonSchemaAnyBuilder<any, IN[key], any>;
+}): JsonSchemaObjectBuilder<IN, IN, false>;
 type Expand<T> = T extends infer O ? {
     [K in keyof O]: O[K];
 } : never;
 type ExactMatch<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type PartiallyOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 type BuilderOutUnion<B extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
     [K in keyof B]: B[K] extends JsonSchemaAnyBuilder<any, infer O, any> ? O : never;
 }[number];

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.0",
+  "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

@@ -0,0 +1,190 @@
+# `j`
+
+## and Silent Bob
+
+### validate The Data
+
+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?
+
+Why go into the trouble? Why not keep the JOI schemas? Well, the main reasons are:
+
+1. Faster validation
+2. Better DX
+3. Stricter type validation
+4. New types
+
+**Faster validation** means that we can now start validating data that we used to ignore, because
+validating them were very-very slow. For example: OuraSleepData.
+
+It also means that we are more prepared for the accumulation of data that will happen with our own
+devices like B1 and R1.
+
+**Better DX** comes from the discoverable API, which means that one does not need to remember what
+kind of schemas we usually import or use.
+
+```ts
+const oldWay = objectSchema<SomeType>({
+  unix: unixTimestamp2000Schema(),
+})
+
+// 👆 You needed to know about importing `objectSchema` and `unixTimestamp2000Schema`
+// as opposed to... 👇
+
+const newWay = j.object<SomeType>({
+  unix: j.number().unixTimestamp2000(),
+})
+
+// ... 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.
+
+```ts
+interface Foo {
+  foo: string
+}
+
+const oldWay = objectSchema<Foo>({ foo: stringSchema.optional() }) // ✅ Worked
+const newWay = j.object<Foo>({ foo: j.string().optional() }) // ❌ Does not work anymore
+```
+
+And we also have **new types** in the schema, e.g.: Buffer, Set.
+
+The novelty is that the new types support serialization and de-serialization, i.e. you can use
+`j.set()` and when you know that the incoming data (from Datastore or from a Request) is an array,
+it will convert the incoming data to a Set. And the same for `j.buffer()` - should you ever need
+that.
+
+```ts
+const schema = j.object.infer({
+  set: j.set(j.enum(DataFlags)), // accepts any Iterable input, output is Set<DataFlags> instance
+  buffer: j.buffer(), // accepts any valid input for Buffer, output is a Buffer instance
+})
+```
+
+### More about `j`
+
+`j` is a JSON Schema builder that is developed in-house.
+
+The validation is done by `ajv` which stands for Another JsonSchema Validator, an insanely fast
+validation library.
+
+`ajv` is hidden under the hood, and developers will mostly interact with `j`.

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> {
@@ -840,13 +840,21 @@ function objectInfer<P extends Record<string, JsonSchemaAnyBuilder<any, any, any
 }
 
 function objectDbEntity(props?: AnyObject): never
-function objectDbEntity<IN extends AnyObject>(
-  props?: AnyObject,
-): JsonSchemaObjectBuilder<IN, IN, false>
+function objectDbEntity<IN extends AnyObject>(props?: {
+  [key in keyof PartiallyOptional<IN, 'id' | 'created' | 'updated'>]: JsonSchemaAnyBuilder<
+    any,
+    IN[key],
+    any
+  >
+}): JsonSchemaObjectBuilder<IN, IN, false>
 
-function objectDbEntity<IN extends AnyObject>(
-  props?: AnyObject,
-): JsonSchemaObjectBuilder<IN, IN, false> {
+function objectDbEntity<IN extends AnyObject>(props?: {
+  [key in keyof PartiallyOptional<IN, 'id' | 'created' | 'updated'>]: JsonSchemaAnyBuilder<
+    any,
+    IN[key],
+    any
+  >
+}): JsonSchemaObjectBuilder<IN, IN, false> {
   return j.object({
     id: j.string(),
     created: j.number().unixTimestamp2000(),
@@ -860,6 +868,8 @@ type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never
 type ExactMatch<A, B> =
   (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false
 
+type PartiallyOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
 type BuilderOutUnion<B extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
   [K in keyof B]: B[K] extends JsonSchemaAnyBuilder<any, infer O, any> ? O : never
 }[number]

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