@naturalcycles/nodejs-lib 15.48.0 → 15.50.0

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

@@ -3,7 +3,7 @@ import { type AnyObject } from '@naturalcycles/js-lib/types';
 import type { ZodType } from '@naturalcycles/js-lib/zod';
 import type { Ajv } from 'ajv';
 import { AjvValidationError } from './ajvValidationError.js';
-import { type JsonSchema, JsonSchemaAnyBuilder } from './jsonSchemaBuilder.js';
+import { type JsonSchema, JsonSchemaTerminal } from './jsonSchemaBuilder.js';
 /**
  * On creation - compiles ajv validation function.
  * Provides convenient methods, error reporting, etc.
@@ -29,7 +29,7 @@ export declare class AjvSchema<IN = unknown, OUT = IN> {
      * @deprecated Use `j` to build schemas, not `z` or `zod`.
      */
     static createFromZod<T extends ZodType<any, any, any>>(schema: T): AjvSchema<T['_input'], T['_output']>;
-    static isJsonSchemaBuilder<IN, OUT>(schema: unknown): schema is JsonSchemaAnyBuilder<IN, OUT, any>;
+    static isJsonSchemaBuilder<IN, OUT>(schema: unknown): schema is JsonSchemaTerminal<IN, OUT, any>;
     readonly cfg: AjvSchemaCfg;
     /**
      * It returns the original object just for convenience.
@@ -94,4 +94,4 @@ export interface AjvSchemaCfg {
      */
     lazy?: boolean;
 }
-export type SchemaHandledByAjv<IN, OUT = IN> = JsonSchemaAnyBuilder<IN, OUT, any> | JsonSchema<IN, OUT> | AjvSchema<IN, OUT>;
+export type SchemaHandledByAjv<IN, OUT = IN> = JsonSchemaTerminal<IN, OUT, any> | JsonSchema<IN, OUT> | AjvSchema<IN, OUT>;

package/dist/validation/ajv/ajvSchema.js

@@ -7,7 +7,7 @@ import { z } from '@naturalcycles/js-lib/zod';
 import { _inspect } from '../../string/inspect.js';
 import { AjvValidationError } from './ajvValidationError.js';
 import { getAjv } from './getAjv.js';
-import { JsonSchemaAnyBuilder } from './jsonSchemaBuilder.js';
+import { JsonSchemaTerminal } from './jsonSchemaBuilder.js';
 /**
  * On creation - compiles ajv validation function.
  * Provides convenient methods, error reporting, etc.
@@ -73,7 +73,7 @@ export class AjvSchema {
         return AjvSchema.create(jsonSchema);
     }
     static isJsonSchemaBuilder(schema) {
-        return schema instanceof JsonSchemaAnyBuilder;
+        return schema instanceof JsonSchemaTerminal;
     }
     cfg;
     /**

package/dist/validation/ajv/from-data/generateJsonSchemaFromData.d.ts

@@ -0,0 +1,8 @@
+import { type AnyObject } from '@naturalcycles/js-lib/types';
+import type { JsonSchema } from '../jsonSchemaBuilder.js';
+/**
+ * Each row must be an object (current limitation).
+ *
+ * `additionalProperties` is set to `true`, cause it's safer.
+ */
+export declare function generateJsonSchemaFromData<T extends AnyObject = AnyObject>(rows: AnyObject[]): JsonSchema<T>;

package/dist/validation/ajv/from-data/generateJsonSchemaFromData.js

@@ -0,0 +1,87 @@
+import { _uniq } from '@naturalcycles/js-lib/array';
+import { _stringMapEntries } from '@naturalcycles/js-lib/types';
+/**
+ * Each row must be an object (current limitation).
+ *
+ * `additionalProperties` is set to `true`, cause it's safer.
+ */
+export function generateJsonSchemaFromData(rows) {
+    return objectToJsonSchema(rows);
+}
+function objectToJsonSchema(rows) {
+    const typesByKey = {};
+    rows.forEach(r => {
+        Object.keys(r).forEach(key => {
+            typesByKey[key] ||= new Set();
+            typesByKey[key].add(getTypeOfValue(r[key]));
+        });
+    });
+    const s = {
+        type: 'object',
+        properties: {},
+        required: [],
+        additionalProperties: true,
+    };
+    _stringMapEntries(typesByKey).forEach(([key, types]) => {
+        const schema = mergeTypes([...types], rows.map(r => r[key]));
+        if (!schema)
+            return;
+        s.properties[key] = schema;
+    });
+    // console.log(typesByKey)
+    return s;
+}
+function mergeTypes(types, samples) {
+    // skip "undefined" types
+    types = types.filter(t => t !== 'undefined');
+    if (!types.length)
+        return undefined;
+    if (types.length > 1) {
+        // oneOf
+        const s = {
+            oneOf: types.map(type => mergeTypes([type], samples)),
+        };
+        return s;
+    }
+    const type = types[0];
+    if (type === 'null') {
+        return {
+            type: 'null',
+        };
+    }
+    if (type === 'boolean') {
+        return {
+            type: 'boolean',
+        };
+    }
+    if (type === 'string') {
+        return {
+            type: 'string',
+        };
+    }
+    if (type === 'number') {
+        return {
+            type: 'number',
+        };
+    }
+    if (type === 'object') {
+        return objectToJsonSchema(samples.filter((r) => r && typeof r === 'object'));
+    }
+    if (type === 'array') {
+        // possible feature: detect if it's a tuple
+        // currently assume no-tuple
+        const items = samples.filter(r => Array.isArray(r)).flat();
+        const itemTypes = _uniq(items.map(i => getTypeOfValue(i)));
+        return {
+            type: 'array',
+            items: mergeTypes(itemTypes, items),
+        };
+    }
+}
+function getTypeOfValue(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}

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

@@ -1,6 +1,7 @@
 import Ajv from 'ajv';
 export * from './ajvSchema.js';
 export * from './ajvValidationError.js';
+export * from './from-data/generateJsonSchemaFromData.js';
 export * from './getAjv.js';
 export * from './jsonSchemaBuilder.js';
 export { Ajv };

package/dist/validation/ajv/index.js

@@ -1,6 +1,7 @@
 import Ajv from 'ajv';
 export * from './ajvSchema.js';
 export * from './ajvValidationError.js';
+export * from './from-data/generateJsonSchemaFromData.js';
 export * from './getAjv.js';
 export * from './jsonSchemaBuilder.js';
 export { Ajv };

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

@@ -15,9 +15,23 @@ export declare const j: {
     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> {
+export declare class JsonSchemaTerminal<IN, OUT, Opt> {
     protected schema: JsonSchema;
     constructor(schema: JsonSchema);
+    getSchema(): JsonSchema;
+    /**
+     * Produces a "clean schema object" without methods.
+     * Same as if it would be JSON.stringified.
+     */
+    build(): JsonSchema<IN, OUT>;
+    clone(): JsonSchemaAnyBuilder<IN, OUT, Opt>;
+    /**
+     * @experimental
+     */
+    in: IN;
+    out: OUT;
+}
+export declare class JsonSchemaAnyBuilder<IN, OUT, Opt> extends JsonSchemaTerminal<IN, OUT, Opt> {
     protected setErrorMessage(ruleName: string, errorMessage: string | undefined): void;
     /**
      * A helper function that takes a type parameter and compares it with the type inferred from the schema.
@@ -33,7 +47,6 @@ export declare class JsonSchemaAnyBuilder<IN, OUT, Opt> {
      * ```
      */
     isOfType<ExpectedType>(): ExactMatch<ExpectedType, OUT> extends true ? this : never;
-    getSchema(): JsonSchema;
     $schema($schema: string): this;
     $schemaDraft7(): this;
     $id($id: string): this;
@@ -45,22 +58,15 @@ export declare class JsonSchemaAnyBuilder<IN, OUT, Opt> {
     instanceof(of: string): this;
     optional(): JsonSchemaAnyBuilder<IN | undefined, OUT | undefined, true>;
     nullable(): JsonSchemaAnyBuilder<IN | null, OUT | null, Opt>;
-    /**
-     * Produces a "clean schema object" without methods.
-     * Same as if it would be JSON.stringified.
-     */
-    build(): JsonSchema<IN, OUT>;
-    clone(): JsonSchemaAnyBuilder<IN, OUT, Opt>;
     /**
      * @deprecated
      * The usage of this function is discouraged as it defeats the purpose of having type-safe validation.
      */
     castAs<T>(): JsonSchemaAnyBuilder<T, T, Opt>;
     /**
-     * @experimental
+     * Locks the given schema chain and no other modification can be done to it.
      */
-    in: IN;
-    out: OUT;
+    final(): JsonSchemaTerminal<IN, OUT, Opt>;
 }
 export declare class JsonSchemaStringBuilder<IN extends string = string, OUT = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
     constructor();

package/dist/validation/ajv/jsonSchemaBuilder.js

@@ -78,11 +78,31 @@ const TS_2000_MILLIS = TS_2000 * 1000;
      which means that the `foo` property would be mandatory, it's just that its value can be `undefined` as well.
      With `Opt`, we can infer it as `{ foo?: string | undefined }`.
 */
-export class JsonSchemaAnyBuilder {
+export class JsonSchemaTerminal {
     schema;
     constructor(schema) {
         this.schema = schema;
     }
+    getSchema() {
+        return this.schema;
+    }
+    /**
+     * Produces a "clean schema object" without methods.
+     * Same as if it would be JSON.stringified.
+     */
+    build() {
+        return _sortObject(JSON.parse(JSON.stringify(this.schema)), JSON_SCHEMA_ORDER);
+    }
+    clone() {
+        return new JsonSchemaAnyBuilder(_deepCopy(this.schema));
+    }
+    /**
+     * @experimental
+     */
+    in;
+    out;
+}
+export class JsonSchemaAnyBuilder extends JsonSchemaTerminal {
     setErrorMessage(ruleName, errorMessage) {
         if (_isUndefined(errorMessage))
             return;
@@ -106,9 +126,6 @@ export class JsonSchemaAnyBuilder {
         _objectAssign(this.schema, { hasIsOfTypeCheck: true });
         return this;
     }
-    getSchema() {
-        return this.schema;
-    }
     $schema($schema) {
         _objectAssign(this.schema, { $schema });
         return this;
@@ -154,16 +171,6 @@ export class JsonSchemaAnyBuilder {
             anyOf: [this.build(), { type: 'null' }],
         });
     }
-    /**
-     * Produces a "clean schema object" without methods.
-     * Same as if it would be JSON.stringified.
-     */
-    build() {
-        return _sortObject(JSON.parse(JSON.stringify(this.schema)), JSON_SCHEMA_ORDER);
-    }
-    clone() {
-        return new JsonSchemaAnyBuilder(_deepCopy(this.schema));
-    }
     /**
      * @deprecated
      * The usage of this function is discouraged as it defeats the purpose of having type-safe validation.
@@ -172,10 +179,11 @@ export class JsonSchemaAnyBuilder {
         return this;
     }
     /**
-     * @experimental
+     * Locks the given schema chain and no other modification can be done to it.
      */
-    in;
-    out;
+    final() {
+        return new JsonSchemaTerminal(this.schema);
+    }
 }
 export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
     constructor() {
@@ -488,7 +496,7 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
     /**
      * Extends the current schema with `id`, `created` and `updated` according to NC DB conventions.
      */
-    // eslint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
+    // oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
     dbEntity() {
         return this.extend({
             id: j.string(),
@@ -550,7 +558,7 @@ export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
     /**
      * Extends the current schema with `id`, `created` and `updated` according to NC DB conventions.
      */
-    // eslint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
+    // oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
     dbEntity() {
         return this.extend({
             id: j.string(),

package/dist/yargs/yargs.util.js

@@ -5,7 +5,7 @@ import { hideBin } from 'yargs/helpers';
  * Quick yargs helper to make it work in esm.
  * It also allows to not have yargs and `@types/yargs` to be declared as dependencies.
  */
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
+// oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
 export function _yargs() {
     return yargs(hideBin(process.argv));
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.48.0",
+  "version": "15.50.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@types/js-yaml": "^4",

package/src/validation/ajv/ajvSchema.ts

@@ -14,7 +14,7 @@ import type { Ajv, ErrorObject } from 'ajv'
 import { _inspect } from '../../string/inspect.js'
 import { AjvValidationError } from './ajvValidationError.js'
 import { getAjv } from './getAjv.js'
-import { type JsonSchema, JsonSchemaAnyBuilder } from './jsonSchemaBuilder.js'
+import { type JsonSchema, JsonSchemaTerminal } from './jsonSchemaBuilder.js'
 
 /**
  * On creation - compiles ajv validation function.
@@ -73,10 +73,10 @@ export class AjvSchema<IN = unknown, OUT = IN> {
     let jsonSchema: JsonSchema<IN, OUT>
 
     if (AjvSchema.isJsonSchemaBuilder(schema)) {
-      jsonSchema = (schema as JsonSchemaAnyBuilder<IN, OUT, any>).build()
+      jsonSchema = schema.build()
       AjvSchema.requireValidJsonSchema(jsonSchema)
     } else {
-      jsonSchema = schema as JsonSchema<IN, OUT>
+      jsonSchema = schema
     }
 
     const ajvSchema = new AjvSchema<IN, OUT>(jsonSchema, cfg)
@@ -98,10 +98,8 @@ export class AjvSchema<IN = unknown, OUT = IN> {
     return AjvSchema.create(jsonSchema)
   }
 
-  static isJsonSchemaBuilder<IN, OUT>(
-    schema: unknown,
-  ): schema is JsonSchemaAnyBuilder<IN, OUT, any> {
-    return schema instanceof JsonSchemaAnyBuilder
+  static isJsonSchemaBuilder<IN, OUT>(schema: unknown): schema is JsonSchemaTerminal<IN, OUT, any> {
+    return schema instanceof JsonSchemaTerminal
   }
 
   readonly cfg: AjvSchemaCfg
@@ -286,6 +284,6 @@ export interface AjvSchemaCfg {
 }
 
 export type SchemaHandledByAjv<IN, OUT = IN> =
-  | JsonSchemaAnyBuilder<IN, OUT, any>
+  | JsonSchemaTerminal<IN, OUT, any>
   | JsonSchema<IN, OUT>
   | AjvSchema<IN, OUT>

package/src/validation/ajv/from-data/generateJsonSchemaFromData.ts

@@ -0,0 +1,112 @@
+import { _uniq } from '@naturalcycles/js-lib/array'
+import { _stringMapEntries, type AnyObject, type StringMap } from '@naturalcycles/js-lib/types'
+import type { JsonSchema } from '../jsonSchemaBuilder.js'
+
+type PrimitiveType = 'undefined' | 'null' | 'boolean' | 'string' | 'number'
+type Type = PrimitiveType | 'array' | 'object'
+
+/**
+ * Each row must be an object (current limitation).
+ *
+ * `additionalProperties` is set to `true`, cause it's safer.
+ */
+export function generateJsonSchemaFromData<T extends AnyObject = AnyObject>(
+  rows: AnyObject[],
+): JsonSchema<T> {
+  return objectToJsonSchema<T>(rows as any)
+}
+
+function objectToJsonSchema<T extends AnyObject>(rows: AnyObject[]): JsonSchema<T> {
+  const typesByKey: StringMap<Set<Type>> = {}
+
+  rows.forEach(r => {
+    Object.keys(r).forEach(key => {
+      typesByKey[key] ||= new Set<Type>()
+      typesByKey[key].add(getTypeOfValue(r[key]))
+    })
+  })
+
+  const s: JsonSchema<T> = {
+    type: 'object',
+    properties: {} as any,
+    required: [],
+    additionalProperties: true,
+  }
+
+  _stringMapEntries(typesByKey).forEach(([key, types]) => {
+    const schema = mergeTypes(
+      [...types],
+      rows.map(r => r[key]),
+    )
+    if (!schema) return
+    s.properties![key as keyof T] = schema as any
+  })
+
+  // console.log(typesByKey)
+
+  return s
+}
+
+function mergeTypes(types: Type[], samples: any[]): JsonSchema | undefined {
+  // skip "undefined" types
+  types = types.filter(t => t !== 'undefined')
+
+  if (!types.length) return undefined
+
+  if (types.length > 1) {
+    // oneOf
+    const s: JsonSchema = {
+      oneOf: types.map(type => mergeTypes([type], samples)!),
+    }
+
+    return s
+  }
+
+  const type = types[0]!
+
+  if (type === 'null') {
+    return {
+      type: 'null',
+    } as JsonSchema
+  }
+
+  if (type === 'boolean') {
+    return {
+      type: 'boolean',
+    } as JsonSchema
+  }
+
+  if (type === 'string') {
+    return {
+      type: 'string',
+    } as JsonSchema
+  }
+
+  if (type === 'number') {
+    return {
+      type: 'number',
+    } as JsonSchema
+  }
+
+  if (type === 'object') {
+    return objectToJsonSchema(samples.filter((r: any) => r && typeof r === 'object'))
+  }
+
+  if (type === 'array') {
+    // possible feature: detect if it's a tuple
+    // currently assume no-tuple
+    const items = samples.filter(r => Array.isArray(r)).flat()
+    const itemTypes = _uniq(items.map(i => getTypeOfValue(i)))
+
+    return {
+      type: 'array',
+      items: mergeTypes(itemTypes, items),
+    } as JsonSchema
+  }
+}
+
+function getTypeOfValue(v: any): Type {
+  if (v === null) return 'null'
+  if (Array.isArray(v)) return 'array'
+  return typeof v as Type
+}

package/src/validation/ajv/index.ts

@@ -2,6 +2,7 @@ import Ajv from 'ajv'
 
 export * from './ajvSchema.js'
 export * from './ajvValidationError.js'
+export * from './from-data/generateJsonSchemaFromData.js'
 export * from './getAjv.js'
 export * from './jsonSchemaBuilder.js'
 

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -134,9 +134,37 @@ const TS_2000_MILLIS = TS_2000 * 1000
      With `Opt`, we can infer it as `{ foo?: string | undefined }`.
 */
 
-export class JsonSchemaAnyBuilder<IN, OUT, Opt> {
-  constructor(protected schema: JsonSchema) {}
+export class JsonSchemaTerminal<IN, OUT, Opt> {
+  protected schema: JsonSchema
 
+  constructor(schema: JsonSchema) {
+    this.schema = schema
+  }
+
+  getSchema(): JsonSchema {
+    return this.schema
+  }
+
+  /**
+   * Produces a "clean schema object" without methods.
+   * Same as if it would be JSON.stringified.
+   */
+  build(): JsonSchema<IN, OUT> {
+    return _sortObject(JSON.parse(JSON.stringify(this.schema)), JSON_SCHEMA_ORDER)
+  }
+
+  clone(): JsonSchemaAnyBuilder<IN, OUT, Opt> {
+    return new JsonSchemaAnyBuilder<IN, OUT, Opt>(_deepCopy(this.schema))
+  }
+
+  /**
+   * @experimental
+   */
+  in!: IN
+  out!: OUT
+}
+
+export class JsonSchemaAnyBuilder<IN, OUT, Opt> extends JsonSchemaTerminal<IN, OUT, Opt> {
   protected setErrorMessage(ruleName: string, errorMessage: string | undefined): void {
     if (_isUndefined(errorMessage)) return
 
@@ -162,10 +190,6 @@ export class JsonSchemaAnyBuilder<IN, OUT, Opt> {
     return this as any
   }
 
-  getSchema(): JsonSchema {
-    return this.schema
-  }
-
   $schema($schema: string): this {
     _objectAssign(this.schema, { $schema })
     return this
@@ -222,18 +246,6 @@ export class JsonSchemaAnyBuilder<IN, OUT, Opt> {
     })
   }
 
-  /**
-   * Produces a "clean schema object" without methods.
-   * Same as if it would be JSON.stringified.
-   */
-  build(): JsonSchema<IN, OUT> {
-    return _sortObject(JSON.parse(JSON.stringify(this.schema)), JSON_SCHEMA_ORDER)
-  }
-
-  clone(): JsonSchemaAnyBuilder<IN, OUT, Opt> {
-    return new JsonSchemaAnyBuilder<IN, OUT, Opt>(_deepCopy(this.schema))
-  }
-
   /**
    * @deprecated
    * The usage of this function is discouraged as it defeats the purpose of having type-safe validation.
@@ -243,10 +255,11 @@ export class JsonSchemaAnyBuilder<IN, OUT, Opt> {
   }
 
   /**
-   * @experimental
+   * Locks the given schema chain and no other modification can be done to it.
    */
-  in!: IN
-  out!: OUT
+  final(): JsonSchemaTerminal<IN, OUT, Opt> {
+    return new JsonSchemaTerminal<IN, OUT, Opt>(this.schema)
+  }
 }
 
 export class JsonSchemaStringBuilder<
@@ -664,7 +677,7 @@ export class JsonSchemaObjectBuilder<
   /**
    * Extends the current schema with `id`, `created` and `updated` according to NC DB conventions.
    */
-  // eslint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
+  // oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
   dbEntity() {
     return this.extend({
       id: j.string(),
@@ -792,7 +805,7 @@ export class JsonSchemaObjectInferringBuilder<
   /**
    * Extends the current schema with `id`, `created` and `updated` according to NC DB conventions.
    */
-  // eslint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
+  // oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
   dbEntity() {
     return this.extend({
       id: j.string(),

package/src/yargs/yargs.util.ts

@@ -6,7 +6,7 @@ import { hideBin } from 'yargs/helpers'
  * Quick yargs helper to make it work in esm.
  * It also allows to not have yargs and `@types/yargs` to be declared as dependencies.
  */
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
+// oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
 export function _yargs() {
   return yargs(hideBin(process.argv))
 }