@naturalcycles/nodejs-lib 15.127.0 → 15.129.0

package/dist/cache/lruMemoCache.d.ts

@@ -1,4 +1,4 @@
-import type { MemoCache } from '@naturalcycles/js-lib/decorators';
+import type { AsyncMemoCache, MemoCache } from '@naturalcycles/js-lib/decorators';
 import { LRUCache } from 'lru-cache';
 export type LRUMemoCacheOptions<KEY, VALUE> = Partial<LRUCache.Options<KEY, VALUE, any>>;
 /**
@@ -16,3 +16,14 @@ export declare class LRUMemoCache<KEY = any, VALUE = any> implements MemoCache<K
     set(k: any, v: any): void;
     clear(): void;
 }
+/**
+ * Same as LRUMemoCache, but implements AsyncMemoCache interface, for when you need it.
+ */
+export declare class LRUAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache<KEY, VALUE> {
+    constructor(opt: LRUMemoCacheOptions<KEY, VALUE>);
+    private lru;
+    has(k: any): Promise<boolean>;
+    get(k: any): Promise<any>;
+    set(k: any, v: any): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/cache/lruMemoCache.js

@@ -27,3 +27,27 @@ export class LRUMemoCache {
         this.lru.clear();
     }
 }
+/**
+ * Same as LRUMemoCache, but implements AsyncMemoCache interface, for when you need it.
+ */
+export class LRUAsyncMemoCache {
+    constructor(opt) {
+        this.lru = new LRUCache({
+            max: 100,
+            ...opt,
+        });
+    }
+    lru;
+    async has(k) {
+        return this.lru.has(k);
+    }
+    async get(k) {
+        return this.lru.get(k);
+    }
+    async set(k, v) {
+        this.lru.set(k, v);
+    }
+    async clear() {
+        this.lru.clear();
+    }
+}

package/dist/validation/ajv/getAjv.js

@@ -4,6 +4,7 @@ import { _deepCopy, _mapObject, Set2 } from '@naturalcycles/js-lib/object';
 import { _substringAfterLast } from '@naturalcycles/js-lib/string';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import { validTLDs } from '../tlds.js';
+import { jFormats } from './jsonSchemaBuilder.util.js';
 // oxlint-disable unicorn/prefer-code-point
 const AJV_OPTIONS = {
     removeAdditional: true,
@@ -371,6 +372,16 @@ export function createAjv(opt) {
             return false;
         },
     });
+    // Annotation only (the values are validated by `enum`), registered so strict mode doesn't reject it
+    ajv.addKeyword({
+        keyword: 'enumNames',
+        schemaType: 'array',
+    });
+    // Annotation only (validated by the custom keywords, e.g `IsoDate`).
+    // `true` makes Ajv skip the format check, while unknown formats would throw in strict mode.
+    for (const format of jFormats) {
+        ajv.addFormat(format, true);
+    }
     ajv.addKeyword({
         keyword: 'errorMessages',
         schemaType: 'object',

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

@@ -3,4 +3,5 @@ export * from './ajvValidationError.js';
 export * from './from-data/generateJsonSchemaFromData.js';
 export * from './getAjv.js';
 export * from './jSchema.js';
+export { jFormats, type JFormat } from './jsonSchemaBuilder.util.js';
 export { Ajv };

package/dist/validation/ajv/index.js

@@ -3,4 +3,5 @@ export * from './ajvValidationError.js';
 export * from './from-data/generateJsonSchemaFromData.js';
 export * from './getAjv.js';
 export * from './jSchema.js';
+export { jFormats } from './jsonSchemaBuilder.util.js';
 export { Ajv };

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

@@ -423,7 +423,7 @@ declare class JSet2Builder<OUT, Opt> extends JBuilder<Set2<OUT>, Opt> {
     max(maxItems: number): this;
 }
 export declare class JEnum<OUT extends string | number | boolean | null, Opt extends boolean = false> extends JBuilder<OUT, Opt> {
-    constructor(enumValues: readonly OUT[], baseType: EnumBaseType, opt?: JsonBuilderRuleOpt);
+    constructor(enumValues: readonly OUT[], baseType: EnumBaseType, opt?: JsonBuilderRuleOpt, enumNames?: readonly string[]);
     branded<B extends OUT>(): JEnum<B, Opt>;
 }
 export declare class JTuple<ITEMS extends JSchema<any, any>[]> extends JBuilder<TupleOut<ITEMS>, false> {
@@ -595,6 +595,11 @@ export interface JsonSchema<OUT = unknown> {
     maxItems?: number;
     uniqueItems?: boolean;
     enum?: any;
+    /**
+     * Member names of a NumberEnum, aligned by index with `enum`.
+     * Annotation only (not validated), lets consumers render `1` as e.g `PREVENT`.
+     */
+    enumNames?: readonly string[];
     hasIsOfTypeCheck?: boolean;
     email?: JsonSchemaStringEmailOptions;
     Set2?: JsonSchema;

package/dist/validation/ajv/jSchema.js

@@ -113,6 +113,7 @@ export const j = {
     },
     enum(input, opt) {
         let enumValues;
+        let enumNames;
         let baseType = 'other';
         if (Array.isArray(input)) {
             enumValues = input;
@@ -126,7 +127,11 @@ export const j = {
         else if (typeof input === 'object') {
             const enumType = getEnumType(input);
             if (enumType === 'NumberEnum') {
-                enumValues = _numberEnumValues(input);
+                // Not via _numberEnumKeys: it misses `_enum()` objects (no reverse mapping)
+                // and misaligns with the values when members aren't declared in ascending order
+                const numberEntries = Object.entries(input).filter(([, value]) => typeof value === 'number');
+                enumValues = numberEntries.map(([, value]) => value);
+                enumNames = numberEntries.map(([name]) => name);
                 baseType = 'number';
             }
             else if (enumType === 'StringEnum') {
@@ -135,7 +140,7 @@ export const j = {
             }
         }
         _assert(enumValues, 'Unsupported enum input');
-        return new JEnum(enumValues, baseType, opt);
+        return new JEnum(enumValues, baseType, opt, enumNames);
     },
     /**
      * Use only with primitive values, otherwise this function will throw to avoid bugs.
@@ -601,11 +606,15 @@ export class JString extends JBuilder {
         return new JIsoDate();
     }
     isoDateTime() {
-        return this.cloneAndUpdateSchema({ IsoDateTime: true }).branded();
+        return this.cloneAndUpdateSchema({
+            format: 'IsoDateTime',
+            IsoDateTime: true,
+        }).branded();
     }
     isoMonth() {
         return new JBuilder({
             type: 'string',
+            format: 'IsoMonth',
             IsoMonth: {},
         });
     }
@@ -674,6 +683,7 @@ export class JIsoDate extends JBuilder {
     constructor() {
         super({
             type: 'string',
+            format: 'IsoDate',
             IsoDate: {},
         });
     }
@@ -771,16 +781,18 @@ export class JNumber extends JBuilder {
         return this;
     }
     unixTimestamp() {
-        return this.integer().branded();
+        return this.integer().cloneAndUpdateSchema({ format: 'UnixTimestamp' }).branded();
     }
     unixTimestamp2000() {
-        return this.integer().min(TS_2000).max(TS_2500).branded();
+        return this.unixTimestamp().min(TS_2000).max(TS_2500);
     }
     unixTimestampMillis() {
-        return this.integer().branded();
+        return this.integer()
+            .cloneAndUpdateSchema({ format: 'UnixTimestampMillis' })
+            .branded();
     }
     unixTimestamp2000Millis() {
-        return this.integer().min(TS_2000_MILLIS).max(TS_2500_MILLIS).branded();
+        return this.unixTimestampMillis().min(TS_2000_MILLIS).max(TS_2500_MILLIS);
     }
     utcOffset() {
         return this.integer()
@@ -949,8 +961,10 @@ class JSet2Builder extends JBuilder {
     }
 }
 export class JEnum extends JBuilder {
-    constructor(enumValues, baseType, opt) {
+    constructor(enumValues, baseType, opt, enumNames) {
         const jsonSchema = { enum: enumValues };
+        if (enumNames)
+            jsonSchema.enumNames = enumNames;
         // Specifying the base type helps in cases when we ask Ajv to coerce the types.
         // Having only the `enum` in the schema does not trigger a coercion in Ajv.
         if (baseType === 'string')

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

@@ -10,3 +10,12 @@ export declare function mergeJsonSchemaObjects<T1 extends AnyObject, T2 extends
 export declare function isEveryItemString(arr: any[]): boolean;
 export declare function isEveryItemNumber(arr: any[]): boolean;
 export declare function isEveryItemPrimitive(arr: any[]): boolean;
+/**
+ * Values of the `format` keyword that `j` builders emit, named after the js-lib types they produce.
+ * PascalCase on purpose, to never collide with standard, ajv-formats or OpenAPI formats (all lowercase),
+ * whose semantics differ: e.g `date-time` requires an offset, while `IsoDateTime` doesn't.
+ *
+ * Annotation only: validation is done by the custom keywords (e.g `IsoDate`), not by the format.
+ */
+export declare const jFormats: readonly ['IsoDate', 'IsoDateTime', 'IsoMonth', 'UnixTimestamp', 'UnixTimestampMillis'];
+export type JFormat = (typeof jFormats)[number];

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

@@ -87,3 +87,17 @@ export function isEveryItemPrimitive(arr) {
     }
     return true;
 }
+/**
+ * Values of the `format` keyword that `j` builders emit, named after the js-lib types they produce.
+ * PascalCase on purpose, to never collide with standard, ajv-formats or OpenAPI formats (all lowercase),
+ * whose semantics differ: e.g `date-time` requires an offset, while `IsoDateTime` doesn't.
+ *
+ * Annotation only: validation is done by the custom keywords (e.g `IsoDate`), not by the format.
+ */
+export const jFormats = [
+    'IsoDate',
+    'IsoDateTime',
+    'IsoMonth',
+    'UnixTimestamp',
+    'UnixTimestampMillis',
+];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.127.0",
+  "version": "15.129.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@standard-schema/spec": "^1",

package/src/cache/lruMemoCache.ts

@@ -1,4 +1,4 @@
-import type { MemoCache } from '@naturalcycles/js-lib/decorators'
+import type { AsyncMemoCache, MemoCache } from '@naturalcycles/js-lib/decorators'
 import { LRUCache } from 'lru-cache'
 
 // Partial, to be able to provide default `max`
@@ -37,3 +37,33 @@ export class LRUMemoCache<KEY = any, VALUE = any> implements MemoCache<KEY, VALU
     this.lru.clear()
   }
 }
+
+/**
+ * Same as LRUMemoCache, but implements AsyncMemoCache interface, for when you need it.
+ */
+export class LRUAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache<KEY, VALUE> {
+  constructor(opt: LRUMemoCacheOptions<KEY, VALUE>) {
+    this.lru = new LRUCache<any, any>({
+      max: 100,
+      ...opt,
+    })
+  }
+
+  private lru!: LRUCache<any, any>
+
+  async has(k: any): Promise<boolean> {
+    return this.lru.has(k)
+  }
+
+  async get(k: any): Promise<any> {
+    return this.lru.get(k)
+  }
+
+  async set(k: any, v: any): Promise<void> {
+    this.lru.set(k, v)
+  }
+
+  async clear(): Promise<void> {
+    this.lru.clear()
+  }
+}

package/src/validation/ajv/getAjv.ts

@@ -14,6 +14,7 @@ import type {
   JsonSchemaIsoMonthOptions,
   JsonSchemaStringEmailOptions,
 } from './jSchema.js'
+import { jFormats } from './jsonSchemaBuilder.util.js'
 
 // oxlint-disable unicorn/prefer-code-point
 
@@ -426,6 +427,18 @@ export function createAjv(opt?: Options): Ajv2020 {
     },
   })
 
+  // Annotation only (the values are validated by `enum`), registered so strict mode doesn't reject it
+  ajv.addKeyword({
+    keyword: 'enumNames',
+    schemaType: 'array',
+  })
+
+  // Annotation only (validated by the custom keywords, e.g `IsoDate`).
+  // `true` makes Ajv skip the format check, while unknown formats would throw in strict mode.
+  for (const format of jFormats) {
+    ajv.addFormat(format, true)
+  }
+
   ajv.addKeyword({
     keyword: 'errorMessages',
     schemaType: 'object',

package/src/validation/ajv/index.ts

@@ -4,5 +4,6 @@ export * from './ajvValidationError.js'
 export * from './from-data/generateJsonSchemaFromData.js'
 export * from './getAjv.js'
 export * from './jSchema.js'
+export { jFormats, type JFormat } from './jsonSchemaBuilder.util.js'
 
 export { Ajv }

package/src/validation/ajv/jSchema.ts

@@ -182,6 +182,7 @@ export const j = {
       | { readonly values: readonly (string | number | boolean | null)[] },
   >(input: T, opt?: JsonBuilderRuleOpt): JEnum<T extends readonly (infer U)[] ? U : Enum<T>> {
     let enumValues: readonly (string | number | boolean | null)[] | undefined
+    let enumNames: string[] | undefined
     let baseType: EnumBaseType = 'other'
 
     if (Array.isArray(input)) {
@@ -194,7 +195,11 @@ export const j = {
     } else if (typeof input === 'object') {
       const enumType = getEnumType(input)
       if (enumType === 'NumberEnum') {
-        enumValues = _numberEnumValues(input as NumberEnum)
+        // Not via _numberEnumKeys: it misses `_enum()` objects (no reverse mapping)
+        // and misaligns with the values when members aren't declared in ascending order
+        const numberEntries = Object.entries(input).filter(([, value]) => typeof value === 'number')
+        enumValues = numberEntries.map(([, value]) => value)
+        enumNames = numberEntries.map(([name]) => name)
         baseType = 'number'
       } else if (enumType === 'StringEnum') {
         enumValues = _stringEnumValues(input as StringEnum)
@@ -203,7 +208,7 @@ export const j = {
     }
 
     _assert(enumValues, 'Unsupported enum input')
-    return new JEnum(enumValues as any, baseType, opt)
+    return new JEnum(enumValues as any, baseType, opt, enumNames)
   },
 
   /**
@@ -801,12 +806,16 @@ export class JString<
   }
 
   isoDateTime(): JString<IsoDateTime, Opt> {
-    return this.cloneAndUpdateSchema({ IsoDateTime: true }).branded<IsoDateTime>()
+    return this.cloneAndUpdateSchema({
+      format: 'IsoDateTime',
+      IsoDateTime: true,
+    }).branded<IsoDateTime>()
   }
 
   isoMonth(): JBuilder<IsoMonth, false> {
     return new JBuilder<IsoMonth, false>({
       type: 'string',
+      format: 'IsoMonth',
       IsoMonth: {},
     })
   }
@@ -893,6 +902,7 @@ export class JIsoDate<Opt extends boolean = false> extends JBuilder<IsoDate, Opt
   constructor() {
     super({
       type: 'string',
+      format: 'IsoDate',
       IsoDate: {},
     })
   }
@@ -1027,19 +1037,21 @@ export class JNumber<
   }
 
   unixTimestamp(): JNumber<UnixTimestamp, Opt> {
-    return this.integer().branded<UnixTimestamp>()
+    return this.integer().cloneAndUpdateSchema({ format: 'UnixTimestamp' }).branded<UnixTimestamp>()
   }
 
   unixTimestamp2000(): JNumber<UnixTimestamp, Opt> {
-    return this.integer().min(TS_2000).max(TS_2500).branded<UnixTimestamp>()
+    return this.unixTimestamp().min(TS_2000).max(TS_2500)
   }
 
   unixTimestampMillis(): JNumber<UnixTimestampMillis, Opt> {
-    return this.integer().branded<UnixTimestampMillis>()
+    return this.integer()
+      .cloneAndUpdateSchema({ format: 'UnixTimestampMillis' })
+      .branded<UnixTimestampMillis>()
   }
 
   unixTimestamp2000Millis(): JNumber<UnixTimestampMillis, Opt> {
-    return this.integer().min(TS_2000_MILLIS).max(TS_2500_MILLIS).branded<UnixTimestampMillis>()
+    return this.unixTimestampMillis().min(TS_2000_MILLIS).max(TS_2500_MILLIS)
   }
 
   utcOffset(): this {
@@ -1331,8 +1343,14 @@ export class JEnum<
   OUT extends string | number | boolean | null,
   Opt extends boolean = false,
 > extends JBuilder<OUT, Opt> {
-  constructor(enumValues: readonly OUT[], baseType: EnumBaseType, opt?: JsonBuilderRuleOpt) {
+  constructor(
+    enumValues: readonly OUT[],
+    baseType: EnumBaseType,
+    opt?: JsonBuilderRuleOpt,
+    enumNames?: readonly string[],
+  ) {
     const jsonSchema: JsonSchema = { enum: enumValues }
+    if (enumNames) jsonSchema.enumNames = enumNames
     // Specifying the base type helps in cases when we ask Ajv to coerce the types.
     // Having only the `enum` in the schema does not trigger a coercion in Ajv.
     if (baseType === 'string') jsonSchema.type = 'string'
@@ -2086,6 +2104,11 @@ export interface JsonSchema<OUT = unknown> {
   uniqueItems?: boolean
 
   enum?: any
+  /**
+   * Member names of a NumberEnum, aligned by index with `enum`.
+   * Annotation only (not validated), lets consumers render `1` as e.g `PREVENT`.
+   */
+  enumNames?: readonly string[]
 
   hasIsOfTypeCheck?: boolean
 

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

@@ -101,3 +101,19 @@ export function isEveryItemPrimitive(arr: any[]): boolean {
   }
   return true
 }
+
+/**
+ * Values of the `format` keyword that `j` builders emit, named after the js-lib types they produce.
+ * PascalCase on purpose, to never collide with standard, ajv-formats or OpenAPI formats (all lowercase),
+ * whose semantics differ: e.g `date-time` requires an offset, while `IsoDateTime` doesn't.
+ *
+ * Annotation only: validation is done by the custom keywords (e.g `IsoDate`), not by the format.
+ */
+export const jFormats = [
+  'IsoDate',
+  'IsoDateTime',
+  'IsoMonth',
+  'UnixTimestamp',
+  'UnixTimestampMillis',
+] as const
+export type JFormat = (typeof jFormats)[number]