@naturalcycles/nodejs-lib 15.126.0 → 15.128.0

package/dist/fs/fs2.d.ts

@@ -1,4 +1,4 @@
-import type { RmOptions } from 'node:fs';
+import type { RmOptions, WriteFileOptions } from 'node:fs';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 /**
@@ -22,8 +22,8 @@ declare class FS2 {
     readBufferAsync(filePath: string): Promise<Buffer>;
     readJson<T = unknown>(filePath: string): T;
     readJsonAsync<T = unknown>(filePath: string): Promise<T>;
-    writeFile(filePath: string, data: string | Buffer): void;
-    writeFileAsync(filePath: string, data: string | Buffer): Promise<void>;
+    writeFile(filePath: string, data: string | Buffer, opt?: WriteFileOptions): void;
+    writeFileAsync(filePath: string, data: string | Buffer, opt?: WriteFileOptions): Promise<void>;
     writeJson(filePath: string, data: any, opt?: JsonOptions): void;
     writeJsonAsync(filePath: string, data: any, opt?: JsonOptions): Promise<void>;
     appendFile(filePath: string, data: string | Buffer): void;

package/dist/fs/fs2.js

@@ -55,11 +55,11 @@ class FS2 {
         const str = await fsp.readFile(filePath, 'utf8');
         return _jsonParse(str);
     }
-    writeFile(filePath, data) {
-        fs.writeFileSync(filePath, data);
+    writeFile(filePath, data, opt) {
+        fs.writeFileSync(filePath, data, opt);
     }
-    async writeFileAsync(filePath, data) {
-        await fsp.writeFile(filePath, data);
+    async writeFileAsync(filePath, data, opt) {
+        await fsp.writeFile(filePath, data, opt);
     }
     writeJson(filePath, data, opt) {
         const str = stringify(data, opt);

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.126.0",
+  "version": "15.128.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@standard-schema/spec": "^1",

package/src/fs/fs2.ts

@@ -14,7 +14,7 @@ Credit to: fs-extra (https://github.com/jprichardson/node-fs-extra)
 
  */
 
-import type { RmOptions, Stats } from 'node:fs'
+import type { RmOptions, Stats, WriteFileOptions } from 'node:fs'
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import path from 'node:path'
@@ -65,12 +65,16 @@ class FS2 {
     return _jsonParse(str)
   }
 
-  writeFile(filePath: string, data: string | Buffer): void {
-    fs.writeFileSync(filePath, data)
+  writeFile(filePath: string, data: string | Buffer, opt?: WriteFileOptions): void {
+    fs.writeFileSync(filePath, data, opt)
   }
 
-  async writeFileAsync(filePath: string, data: string | Buffer): Promise<void> {
-    await fsp.writeFile(filePath, data)
+  async writeFileAsync(
+    filePath: string,
+    data: string | Buffer,
+    opt?: WriteFileOptions,
+  ): Promise<void> {
+    await fsp.writeFile(filePath, data, opt)
   }
 
   writeJson(filePath: string, data: any, opt?: JsonOptions): void {

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]