@naturalcycles/nodejs-lib 15.135.1 → 15.137.0

package/dist/fs/fs2.d.ts

@@ -45,8 +45,18 @@ declare class FS2 {
     ensureFileAsync(filePath: string): Promise<void>;
     removePath(fileOrDirPath: string, opt?: RmOptions): void;
     removePathAsync(fileOrDirPath: string, opt?: RmOptions): Promise<void>;
-    emptyDir(dirPath: string): void;
-    emptyDirAsync(dirPath: string): Promise<void>;
+    /**
+     * Ensures that the directory exists and is empty.
+     * Creates it (recursively) if it doesn't exist, otherwise deletes all its contents.
+     * The directory itself is not deleted.
+     */
+    ensureEmptyDir(dirPath: string): void;
+    /**
+     * Ensures that the directory exists and is empty.
+     * Creates it (recursively) if it doesn't exist, otherwise deletes all its contents.
+     * The directory itself is not deleted.
+     */
+    ensureEmptyDirAsync(dirPath: string): Promise<void>;
     /**
      * Cautious, underlying Node function is currently Experimental.
      */

package/dist/fs/fs2.js

@@ -196,12 +196,19 @@ class FS2 {
     async removePathAsync(fileOrDirPath, opt) {
         await fsp.rm(fileOrDirPath, { recursive: true, force: true, ...opt });
     }
-    emptyDir(dirPath) {
+    /**
+     * Ensures that the directory exists and is empty.
+     * Creates it (recursively) if it doesn't exist, otherwise deletes all its contents.
+     * The directory itself is not deleted.
+     */
+    ensureEmptyDir(dirPath) {
         let items;
         try {
             items = fs.readdirSync(dirPath);
         }
-        catch {
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                throw err;
             this.ensureDir(dirPath);
             return;
         }
@@ -209,12 +216,19 @@ class FS2 {
             this.removePath(path.join(dirPath, item));
         }
     }
-    async emptyDirAsync(dirPath) {
+    /**
+     * Ensures that the directory exists and is empty.
+     * Creates it (recursively) if it doesn't exist, otherwise deletes all its contents.
+     * The directory itself is not deleted.
+     */
+    async ensureEmptyDirAsync(dirPath) {
         let items;
         try {
             items = await fsp.readdir(dirPath);
         }
-        catch {
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                throw err;
             return await this.ensureDirAsync(dirPath);
         }
         await Promise.all(items.map(item => this.removePathAsync(path.join(dirPath, item))));

package/dist/validation/ajv/getAjv.js

@@ -372,6 +372,25 @@ export function createAjv(opt) {
             return false;
         },
     });
+    ajv.addKeyword({
+        keyword: 'UtcOffset',
+        type: 'string',
+        modifying: false,
+        errors: true,
+        schemaType: 'object',
+        validate: function validate(opt, data, _schema, ctx) {
+            const isValid = data === 'Z' ? opt.allowZ : data !== '' && isIsoTimezoneValid(data);
+            if (isValid)
+                return true;
+            validate.errors = [
+                {
+                    instancePath: ctx?.instancePath ?? '',
+                    message: `is an invalid UtcOffset`,
+                },
+            ];
+            return false;
+        },
+    });
     // Annotation only (the values are validated by `enum`), registered so strict mode doesn't reject it
     ajv.addKeyword({
         keyword: 'enumNames',

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

@@ -264,6 +264,7 @@ export declare class JString<OUT extends string | undefined = string, Opt extend
     isoDate(): JIsoDate;
     isoDateTime(): JString<IsoDateTime, Opt>;
     isoMonth(): JBuilder<IsoMonth, false>;
+    utcOffset(opt?: Partial<JsonSchemaUtcOffsetOptions>): this;
     /**
      * Validates the string format to be JWT.
      * Expects the JWT to be signed!
@@ -315,6 +316,9 @@ export interface JsonSchemaIsoDateOptions {
 }
 export interface JsonSchemaIsoMonthOptions {
 }
+export interface JsonSchemaUtcOffsetOptions {
+    allowZ: boolean;
+}
 export declare class JNumber<OUT extends number | undefined = number, Opt extends boolean = false> extends JBuilder<OUT, Opt> {
     constructor();
     integer(): this;
@@ -611,6 +615,7 @@ export interface JsonSchema<OUT = unknown> {
     IsoDate?: JsonSchemaIsoDateOptions;
     IsoDateTime?: true;
     IsoMonth?: JsonSchemaIsoMonthOptions;
+    UtcOffset?: JsonSchemaUtcOffsetOptions;
     instanceof?: string | string[];
     transform?: {
         trim?: true;

package/dist/validation/ajv/jSchema.js

@@ -618,6 +618,13 @@ export class JString extends JBuilder {
             IsoMonth: {},
         });
     }
+    utcOffset(opt) {
+        const defaultOptions = { allowZ: false };
+        return this.cloneAndUpdateSchema({
+            format: 'UtcOffset',
+            UtcOffset: { ...defaultOptions, ...opt },
+        });
+    }
     /**
      * Validates the string format to be JWT.
      * Expects the JWT to be signed!

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

@@ -17,5 +17,5 @@ export declare function isEveryItemPrimitive(arr: readonly any[]): boolean;
  *
  * 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 declare const jFormats: readonly ['IsoDate', 'IsoDateTime', 'IsoMonth', 'UnixTimestamp', 'UnixTimestampMillis', 'UtcOffset'];
 export type JFormat = (typeof jFormats)[number];

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

@@ -100,4 +100,5 @@ export const jFormats = [
     'IsoMonth',
     'UnixTimestamp',
     'UnixTimestampMillis',
+    'UtcOffset',
 ];

package/package.json

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

package/src/fs/fs2.ts

@@ -230,11 +230,17 @@ class FS2 {
     await fsp.rm(fileOrDirPath, { recursive: true, force: true, ...opt })
   }
 
-  emptyDir(dirPath: string): void {
+  /**
+   * Ensures that the directory exists and is empty.
+   * Creates it (recursively) if it doesn't exist, otherwise deletes all its contents.
+   * The directory itself is not deleted.
+   */
+  ensureEmptyDir(dirPath: string): void {
     let items: string[]
     try {
       items = fs.readdirSync(dirPath)
-    } catch {
+    } catch (err) {
+      if ((err as any)?.code !== 'ENOENT') throw err
       this.ensureDir(dirPath)
       return
     }
@@ -244,11 +250,17 @@ class FS2 {
     }
   }
 
-  async emptyDirAsync(dirPath: string): Promise<void> {
+  /**
+   * Ensures that the directory exists and is empty.
+   * Creates it (recursively) if it doesn't exist, otherwise deletes all its contents.
+   * The directory itself is not deleted.
+   */
+  async ensureEmptyDirAsync(dirPath: string): Promise<void> {
     let items: string[]
     try {
       items = await fsp.readdir(dirPath)
-    } catch {
+    } catch (err) {
+      if ((err as any)?.code !== 'ENOENT') throw err
       return await this.ensureDirAsync(dirPath)
     }
 

package/src/validation/ajv/getAjv.ts

@@ -13,6 +13,7 @@ import type {
   JsonSchemaIsoDateOptions,
   JsonSchemaIsoMonthOptions,
   JsonSchemaStringEmailOptions,
+  JsonSchemaUtcOffsetOptions,
 } from './jSchema.js'
 import { jFormats } from './jsonSchemaBuilder.util.js'
 
@@ -427,6 +428,25 @@ export function createAjv(opt?: Options): Ajv2020 {
     },
   })
 
+  ajv.addKeyword({
+    keyword: 'UtcOffset',
+    type: 'string',
+    modifying: false,
+    errors: true,
+    schemaType: 'object',
+    validate: function validate(opt: JsonSchemaUtcOffsetOptions, data: string, _schema, ctx) {
+      const isValid = data === 'Z' ? opt.allowZ : data !== '' && isIsoTimezoneValid(data)
+      if (isValid) return true
+      ;(validate as any).errors = [
+        {
+          instancePath: ctx?.instancePath ?? '',
+          message: `is an invalid UtcOffset`,
+        },
+      ]
+      return false
+    },
+  })
+
   // Annotation only (the values are validated by `enum`), registered so strict mode doesn't reject it
   ajv.addKeyword({
     keyword: 'enumNames',

package/src/validation/ajv/jSchema.ts

@@ -821,6 +821,14 @@ export class JString<
     })
   }
 
+  utcOffset(opt?: Partial<JsonSchemaUtcOffsetOptions>): this {
+    const defaultOptions: JsonSchemaUtcOffsetOptions = { allowZ: false }
+    return this.cloneAndUpdateSchema({
+      format: 'UtcOffset',
+      UtcOffset: { ...defaultOptions, ...opt },
+    })
+  }
+
   /**
    * Validates the string format to be JWT.
    * Expects the JWT to be signed!
@@ -946,6 +954,10 @@ export interface JsonSchemaIsoDateOptions {
 
 export interface JsonSchemaIsoMonthOptions {}
 
+export interface JsonSchemaUtcOffsetOptions {
+  allowZ: boolean
+}
+
 export class JNumber<
   OUT extends number | undefined = number,
   Opt extends boolean = false,
@@ -2128,6 +2140,7 @@ export interface JsonSchema<OUT = unknown> {
   IsoDate?: JsonSchemaIsoDateOptions
   IsoDateTime?: true
   IsoMonth?: JsonSchemaIsoMonthOptions
+  UtcOffset?: JsonSchemaUtcOffsetOptions
   instanceof?: string | string[]
   transform?: { trim?: true; toLowerCase?: true; toUpperCase?: true; truncate?: number }
   errorMessages?: StringMap<string>

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

@@ -115,5 +115,6 @@ export const jFormats = [
   'IsoMonth',
   'UnixTimestamp',
   'UnixTimestampMillis',
+  'UtcOffset',
 ] as const
 export type JFormat = (typeof jFormats)[number]