@naturalcycles/js-lib 15.33.3 → 15.35.0

package/dist/array/array.util.d.ts

@@ -5,7 +5,7 @@ import type { AbortablePredicate, FalsyValue, Mapper, Predicate, SortDirection,
  *
  * @param array The array to process.
  * @param size The length of each chunk.
- * @return Returns the new array containing chunks.
+ * @returns Returns the new array containing chunks.
  *
  * https://lodash.com/docs#chunk
  *

package/dist/array/array.util.js

@@ -6,7 +6,7 @@ import { END } from '../types.js';
  *
  * @param array The array to process.
  * @param size The length of each chunk.
- * @return Returns the new array containing chunks.
+ * @returns Returns the new array containing chunks.
  *
  * https://lodash.com/docs#chunk
  *
@@ -79,8 +79,7 @@ export function _pushUniqBy(a, mapper, ...items) {
  */
 export function _uniqBy(arr, mapper) {
     const map = new Map();
-    for (let i = 0; i < arr.length; i++) {
-        const item = arr[i];
+    for (const item of arr) {
         const key = item === undefined || item === null ? item : mapper(item);
         if (!map.has(key))
             map.set(key, item);
@@ -109,8 +108,7 @@ export function _uniqBy(arr, mapper) {
  */
 export function _by(items, mapper) {
     const map = {};
-    for (let i = 0; i < items.length; i++) {
-        const v = items[i];
+    for (const v of items) {
         const k = mapper(v);
         if (k !== undefined) {
             map[k] = v;
@@ -123,8 +121,7 @@ export function _by(items, mapper) {
  */
 export function _mapBy(items, mapper) {
     const map = new Map();
-    for (let i = 0; i < items.length; i++) {
-        const item = items[i];
+    for (const item of items) {
         const key = mapper(item);
         if (key !== undefined) {
             map.set(key, item);
@@ -145,8 +142,7 @@ export function _mapBy(items, mapper) {
  */
 export function _groupBy(items, mapper) {
     const map = {};
-    for (let i = 0; i < items.length; i++) {
-        const item = items[i];
+    for (const item of items) {
         const key = mapper(item);
         if (key !== undefined) {
             ;
@@ -444,8 +440,7 @@ export function _maxByOrUndefined(array, mapper) {
         return;
     let maxItem;
     let max;
-    for (let i = 0; i < array.length; i++) {
-        const item = array[i];
+    for (const item of array) {
         const v = mapper(item);
         if (v !== undefined && (max === undefined || v > max)) {
             maxItem = item;
@@ -459,8 +454,7 @@ export function _minByOrUndefined(array, mapper) {
         return;
     let minItem;
     let min;
-    for (let i = 0; i < array.length; i++) {
-        const item = array[i];
+    for (const item of array) {
         const v = mapper(item);
         if (v !== undefined && (min === undefined || v < min)) {
             minItem = item;

package/dist/decorators/asyncMemo.decorator.d.ts

@@ -25,12 +25,12 @@ export interface AsyncMemoInstance {
     getCache: (instance: AnyAsyncFunction) => AsyncMemoCache | undefined;
 }
 /**
- * Like @_Memo, but allowing async MemoCache implementation.
+ * Like `@_Memo`, but allowing async MemoCache implementation.
  *
- * Implementation is more complex than @_Memo, because it needs to handle "in-flight" Promises
+ * Implementation is more complex than `@_Memo`, because it needs to handle "in-flight" Promises
  * while waiting for cache to resolve, to prevent "async swarm" issue.
  *
- * @experimental consider normal @_Memo for most of the cases, it's stable and predictable
+ * @experimental consider normal `@_Memo` for most of the cases, it's stable and predictable
  */
 export declare const _AsyncMemo: <FN>(opt: AsyncMemoOptions<FN>) => MethodDecorator<FN>;
 /**

package/dist/decorators/asyncMemo.decorator.js

@@ -3,12 +3,12 @@ import { _objectAssign, MISS } from '../types.js';
 import { _getTargetMethodSignature } from './decorator.util.js';
 import { jsonMemoSerializer } from './memo.util.js';
 /**
- * Like @_Memo, but allowing async MemoCache implementation.
+ * Like `@_Memo`, but allowing async MemoCache implementation.
  *
- * Implementation is more complex than @_Memo, because it needs to handle "in-flight" Promises
+ * Implementation is more complex than `@_Memo`, because it needs to handle "in-flight" Promises
  * while waiting for cache to resolve, to prevent "async swarm" issue.
  *
- * @experimental consider normal @_Memo for most of the cases, it's stable and predictable
+ * @experimental consider normal `@_Memo` for most of the cases, it's stable and predictable
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const _AsyncMemo = (opt) => (target, key, descriptor) => {

package/dist/decorators/logMethod.decorator.js

@@ -70,7 +70,7 @@ export function _LogMethod(opt = {}) {
         return descriptor;
     };
 }
-// eslint-disable-next-line max-params
+// oxlint-disable-next-line max-params
 function logFinished(logger, callSignature, started, sma, logResultFn, res, err) {
     const millis = Date.now() - started;
     const t = ['<<', callSignature, 'took', _ms(millis)];

package/dist/error/error.util.d.ts

@@ -83,7 +83,7 @@ export interface AppErrorOptions {
  * data - optional "any" payload.
  * data.userFriendly - if present, will be displayed to the User as is.
  *
- * Based on: https://medium.com/@xpl/javascript-deriving-from-error-properly-8d2f8f315801
+ * Based on: `https://medium.com/@xpl/javascript-deriving-from-error-properly-8d2f8f315801`
  */
 export declare class AppError<DATA_TYPE extends ErrorData = ErrorData> extends Error {
     data: DATA_TYPE;

package/dist/error/error.util.js

@@ -221,7 +221,7 @@ export function _errorDataAppend(err, data) {
  * data - optional "any" payload.
  * data.userFriendly - if present, will be displayed to the User as is.
  *
- * Based on: https://medium.com/@xpl/javascript-deriving-from-error-properly-8d2f8f315801
+ * Based on: `https://medium.com/@xpl/javascript-deriving-from-error-properly-8d2f8f315801`
  */
 export class AppError extends Error {
     data;

package/dist/json-schema/jsonSchemaBuilder.d.ts

@@ -1,4 +1,4 @@
-import type { AnyObject, BaseDBEntity, IsoDate, UnixTimestamp } from '../types.js';
+import type { AnyObject, BaseDBEntity, IsoDate, IsoDateTime, UnixTimestamp } from '../types.js';
 import type { JsonSchema, JsonSchemaAllOf, JsonSchemaAny, JsonSchemaArray, JsonSchemaBoolean, JsonSchemaConst, JsonSchemaEnum, JsonSchemaNull, JsonSchemaNumber, JsonSchemaObject, JsonSchemaOneOf, JsonSchemaRef, JsonSchemaString, JsonSchemaTuple } from './jsonSchema.model.js';
 export interface JsonSchemaBuilder<T = unknown> {
     build: () => JsonSchema<T>;
@@ -20,10 +20,19 @@ export declare const j: {
     unixTimestamp(): JsonSchemaNumberBuilder<UnixTimestamp>;
     unixTimestamp2000(): JsonSchemaNumberBuilder<UnixTimestamp>;
     string<T extends string = string>(): JsonSchemaStringBuilder<T>;
+    /**
+     * Accepts only the `YYYY-MM-DD` shape from all ISO 8601 variants.
+     */
     isoDate(): JsonSchemaStringBuilder<IsoDate>;
-    object<T extends AnyObject>(props: { [K in keyof T]: JsonSchemaAnyBuilder<T[K]>; }): JsonSchemaObjectBuilder<T>;
+    /**
+     * Accepts strings that start with the `YYYY-MM-DDTHH:MM:SS` shape
+     * and optionally end with either a `Z` or a `+/-hh:mm` timezone part.
+     */
+    isoDateTime(): JsonSchemaStringBuilder<IsoDateTime>;
+    object: typeof object;
+    dbEntity<T extends AnyObject>(props: T): JsonSchemaObjectBuilder<BaseDBEntity & { [K in keyof T]: T[K] extends JsonSchemaAnyBuilder<infer U, any> ? U : never; }>;
     rootObject<T extends AnyObject>(props: { [K in keyof T]: JsonSchemaAnyBuilder<T[K]>; }): JsonSchemaObjectBuilder<T>;
-    array<ITEM = unknown>(itemSchema: JsonSchemaAnyBuilder<ITEM>): JsonSchemaArrayBuilder<ITEM>;
+    array<T extends JsonSchemaAnyBuilder<any>>(itemSchema: T): JsonSchemaArrayBuilder<T["infer"]>;
     tuple<T extends any[] = unknown[]>(items: JsonSchemaAnyBuilder[]): JsonSchemaTupleBuilder<T>;
     oneOf<T = unknown>(items: JsonSchemaAnyBuilder[]): JsonSchemaAnyBuilder<T, JsonSchemaOneOf<T>>;
     allOf<T = unknown>(items: JsonSchemaAnyBuilder[]): JsonSchemaAnyBuilder<T, JsonSchemaAllOf<T>>;
@@ -46,7 +55,9 @@ export declare class JsonSchemaAnyBuilder<T = unknown, SCHEMA_TYPE extends JsonS
     oneOf(schemas: JsonSchema[]): this;
     allOf(schemas: JsonSchema[]): this;
     instanceof(of: string): this;
-    optional(optional?: boolean): this;
+    optional(): JsonSchemaAnyBuilder<T | undefined, JsonSchema<T | undefined>>;
+    optional(optional: true): JsonSchemaAnyBuilder<T | undefined, JsonSchema<T | undefined>>;
+    optional(optional: false): JsonSchemaAnyBuilder<Exclude<T, undefined>, JsonSchema<Exclude<T, undefined>>>;
     /**
      * Produces a "clean schema object" without methods.
      * Same as if it would be JSON.stringified.
@@ -81,16 +92,17 @@ export declare class JsonSchemaNumberBuilder<T extends number = number> extends
     unixTimestampMillis2000: () => this;
     utcOffset: () => this;
     utcOffsetHours: () => this;
+    branded<B extends number>(): JsonSchemaNumberBuilder<B>;
 }
 export declare class JsonSchemaStringBuilder<T extends string = string> extends JsonSchemaAnyBuilder<T, JsonSchemaString<T>> {
     constructor();
+    regex(pattern: RegExp): this;
     pattern(pattern: string): this;
     min(minLength: number): this;
     max(maxLength: number): this;
     length(minLength: number, maxLength: number): this;
     format(format: string): this;
     email: () => this;
-    isoDate: () => this;
     url: () => this;
     ipv4: () => this;
     ipv6: () => this;
@@ -104,6 +116,16 @@ export declare class JsonSchemaStringBuilder<T extends string = string> extends
     trim: (trim?: boolean) => this;
     toLowerCase: (toLowerCase?: boolean) => this;
     toUpperCase: (toUpperCase?: boolean) => this;
+    branded<B extends string>(): JsonSchemaStringBuilder<B>;
+    /**
+     * Accepts only the `YYYY-MM-DD` shape from all ISO 8601 variants.
+     */
+    isoDate(): JsonSchemaStringBuilder<IsoDate>;
+    /**
+     * Accepts strings that start with the `YYYY-MM-DDTHH:MM:SS` shape
+     * and optionally end with either a `Z` or a `+/-hh:mm` timezone part.
+     */
+    isoDateTime(): JsonSchemaStringBuilder<IsoDateTime>;
     private transformModify;
 }
 export declare class JsonSchemaObjectBuilder<T extends AnyObject> extends JsonSchemaAnyBuilder<T, JsonSchemaObject<T>> {
@@ -131,3 +153,10 @@ export declare class JsonSchemaArrayBuilder<ITEM> extends JsonSchemaAnyBuilder<I
 export declare class JsonSchemaTupleBuilder<T extends any[]> extends JsonSchemaAnyBuilder<T, JsonSchemaTuple<T>> {
     constructor(items: JsonSchemaBuilder[]);
 }
+declare function object<P extends Record<string, JsonSchemaAnyBuilder<any, any>>>(props: P): JsonSchemaObjectBuilder<{
+    [K in keyof P]: P[K] extends JsonSchemaAnyBuilder<infer U, any> ? U : never;
+}>;
+declare function object<T extends AnyObject>(props: {
+    [K in keyof T]: JsonSchemaAnyBuilder<T[K]>;
+}): JsonSchemaObjectBuilder<T>;
+export {};

package/dist/json-schema/jsonSchemaBuilder.js

@@ -56,13 +56,30 @@ export const j = {
     string() {
         return new JsonSchemaStringBuilder();
     },
+    /**
+     * Accepts only the `YYYY-MM-DD` shape from all ISO 8601 variants.
+     */
     isoDate() {
         return new JsonSchemaStringBuilder().isoDate();
     },
+    /**
+     * Accepts strings that start with the `YYYY-MM-DDTHH:MM:SS` shape
+     * and optionally end with either a `Z` or a `+/-hh:mm` timezone part.
+     */
+    isoDateTime() {
+        return new JsonSchemaStringBuilder().isoDateTime();
+    },
     // email: () => new JsonSchemaStringBuilder().email(),
     // complex types
-    object(props) {
-        return new JsonSchemaObjectBuilder().addProperties(props);
+    object,
+    dbEntity(props) {
+        return j
+            .object({
+            id: j.string(),
+            created: j.unixTimestamp2000(),
+            updated: j.unixTimestamp2000(),
+        })
+            .extend(j.object(props));
     },
     rootObject(props) {
         return new JsonSchemaObjectBuilder().addProperties(props).$schemaDraft7();
@@ -214,6 +231,9 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
     unixTimestampMillis2000 = () => this.format('unixTimestampMillis2000').description('UnixTimestampMillis2000');
     utcOffset = () => this.format('utcOffset');
     utcOffsetHours = () => this.format('utcOffsetHours');
+    branded() {
+        return this;
+    }
 }
 export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
     constructor() {
@@ -221,6 +241,9 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
             type: 'string',
         });
     }
+    regex(pattern) {
+        return this.pattern(pattern.source);
+    }
     pattern(pattern) {
         Object.assign(this.schema, { pattern });
         return this;
@@ -242,7 +265,6 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
         return this;
     }
     email = () => this.format('email');
-    isoDate = () => this.format('date').description('IsoDate'); // todo: make it custom isoDate instead
     url = () => this.format('url');
     ipv4 = () => this.format('ipv4');
     ipv6 = () => this.format('ipv6');
@@ -256,6 +278,22 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
     trim = (trim = true) => this.transformModify('trim', trim);
     toLowerCase = (toLowerCase = true) => this.transformModify('toLowerCase', toLowerCase);
     toUpperCase = (toUpperCase = true) => this.transformModify('toUpperCase', toUpperCase);
+    branded() {
+        return this;
+    }
+    /**
+     * Accepts only the `YYYY-MM-DD` shape from all ISO 8601 variants.
+     */
+    isoDate() {
+        return this.format('IsoDate').branded().description('IsoDate');
+    }
+    /**
+     * Accepts strings that start with the `YYYY-MM-DDTHH:MM:SS` shape
+     * and optionally end with either a `Z` or a `+/-hh:mm` timezone part.
+     */
+    isoDateTime() {
+        return this.format('IsoDateTime').branded().description('IsoDateTime');
+    }
     transformModify(t, add) {
         if (add) {
             this.schema.transform = _uniq([...(this.schema.transform || []), t]);
@@ -357,3 +395,6 @@ export class JsonSchemaTupleBuilder extends JsonSchemaAnyBuilder {
         });
     }
 }
+function object(props) {
+    return new JsonSchemaObjectBuilder().addProperties(props);
+}

package/dist/object/object.util.d.ts

@@ -126,7 +126,6 @@ export declare function _filterEmptyValues<T extends AnyObject>(obj: T, opt?: Mu
  *
  * **Note:** This method mutates `object`.
  *
- * @category Object
  * @param target The destination object.
  * @param sources The source objects.
  * @returns Returns `object`.
@@ -177,7 +176,7 @@ type PropertyPath = Many<PropertyKey>;
  * @param obj The object to modify.
  * @param path The path of the property to set.
  * @param value The value to set.
- * @return Returns object.
+ * @returns Returns object.
  *
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
@@ -185,7 +184,6 @@ export declare function _set<T extends AnyObject>(obj: T, path: PropertyPath, va
 /**
  * Checks if `path` is a direct property of `object` (not null, not undefined).
  *
- * @category Object
  * @param obj The object to query.
  * @param path The path to check.
  * @returns Returns `true` if `path` exists, else `false`.

package/dist/object/object.util.js

@@ -236,7 +236,6 @@ export function _filterEmptyValues(obj, opt = {}) {
  *
  * **Note:** This method mutates `object`.
  *
- * @category Object
  * @param target The destination object.
  * @param sources The source objects.
  * @returns Returns `object`.
@@ -340,7 +339,7 @@ export function _get(obj = {}, path = '') {
     return (path
         .replaceAll(/\[([^\]]+)]/g, '.$1')
         .split('.')
-        // eslint-disable-next-line unicorn/no-array-reduce
+        // oxlint-disable-next-line unicorn/no-array-reduce
         .reduce((o, p) => o?.[p], obj));
 }
 /**
@@ -350,7 +349,7 @@ export function _get(obj = {}, path = '') {
  * @param obj The object to modify.
  * @param path The path of the property to set.
  * @param value The value to set.
- * @return Returns object.
+ * @returns Returns object.
  *
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
@@ -365,7 +364,7 @@ export function _set(obj, path, value) {
     else if (!path.length) {
         return obj;
     }
-    // eslint-disable-next-line unicorn/no-array-reduce
+    // oxlint-disable-next-line unicorn/no-array-reduce
     ;
     path.slice(0, -1).reduce((a, c, i) => 
     // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
@@ -384,7 +383,6 @@ export function _set(obj, path, value) {
 /**
  * Checks if `path` is a direct property of `object` (not null, not undefined).
  *
- * @category Object
  * @param obj The object to query.
  * @param path The path to check.
  * @returns Returns `true` if `path` exists, else `false`.

package/dist/promise/pMap.js

@@ -85,7 +85,7 @@ export async function pMap(iterable, mapper, opt = {}) {
                 }
                 ret[i] = value;
                 resolvingCount--;
-                next();
+                next(); // oxlint-disable-line no-callback-in-promise
             }, (err) => {
                 if (errorMode === ErrorMode.THROW_IMMEDIATELY) {
                     isSettled = true;
@@ -100,7 +100,7 @@ export async function pMap(iterable, mapper, opt = {}) {
                         logger?.error(err);
                     }
                     resolvingCount--;
-                    next();
+                    next(); // oxlint-disable-line no-callback-in-promise
                 }
             });
         };

package/dist/string/safeJsonStringify.js

@@ -13,7 +13,8 @@ export function _safeJsonStringify(obj, replacer, spaces, cycleReplacer) {
         return JSON.stringify(obj, serializer(replacer, cycleReplacer), spaces);
     }
 }
-/* eslint-disable @typescript-eslint/no-unused-expressions, no-bitwise, no-implicit-coercion */
+/* eslint-disable no-bitwise, no-implicit-coercion */
+// oxlint-disable no-unused-expressions
 function serializer(replacer, cycleReplacer) {
     const stack = [];
     const keys = [];

package/dist/string/string.util.d.ts

@@ -16,7 +16,7 @@ export declare function _lowerFirst(s: string): Uncapitalize<string>;
 /**
  * Like String.split(), but with limit, returning the tail together with last element.
  *
- * @return Returns the new array of string segments.
+ * @returns Returns the new array of string segments.
  */
 export declare function _split(str: string, separator: string, limit: number): string[];
 export declare function _removeWhitespace(s: string): string;

package/dist/string/string.util.js

@@ -26,7 +26,7 @@ export function _lowerFirst(s) {
 /**
  * Like String.split(), but with limit, returning the tail together with last element.
  *
- * @return Returns the new array of string segments.
+ * @returns Returns the new array of string segments.
  */
 export function _split(str, separator, limit) {
     const parts = str.split(separator);

package/dist/typeFest.d.ts

@@ -37,8 +37,6 @@ type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ?
  type FooWithoutA = Except<Foo, 'a' | 'c'>;
  //=> {b: string};
  ```
-
- @category Utilities
  */
 export type Except<ObjectType, KeysType extends keyof ObjectType> = {
     [KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];
@@ -82,8 +80,6 @@ export type OmitIndexSignature<ObjectType> = {
 
  const ab: Merge<Foo, Bar> = {a: 1, b: 2};
  ```
-
- @category Utilities
  */
 export type Merge<Destination, Source> = {
     [Key in keyof OmitIndexSignature<Destination & Source>]: Key extends keyof Source ? Source[Key] : Key extends keyof Destination ? Destination[Key] : never;
@@ -109,7 +105,6 @@ export type Merge<Destination, Source> = {
  type StringKeysAndUndefined = ConditionalKeys<Example, string | undefined>;
  //=> 'a' | 'c'
  ```
- @category Utilities
  */
 export type ConditionalKeys<Base, Condition> = NonNullable<{
     [Key in keyof Base]: Base[Key] extends Condition ? Key : never;
@@ -141,7 +136,6 @@ export type ConditionalKeys<Base, Condition> = NonNullable<{
  type NonStringKeysOnly = ConditionalExcept<Example, string>;
  //=> {b: string | number; c: () => void; d: {}}
  ```
- @category Utilities
  */
 export type ConditionalExcept<Base, Condition> = Except<Base, ConditionalKeys<Base, Condition>>;
 /**
@@ -171,7 +165,6 @@ export type ConditionalExcept<Base, Condition> = Except<Base, ConditionalKeys<Ba
  type StringKeysOnly = ConditionalPick<Example, string>;
  //=> {a: string}
  ```
- @category Utilities
  */
 export type ConditionalPick<Base, Condition> = Pick<Base, ConditionalKeys<Base, Condition>>;
 /**

package/dist/types.d.ts

@@ -310,7 +310,7 @@ export type FalsyValue = false | '' | 0 | null | undefined;
  *   err.data = {} // can be done, because it was casted
  * }
  */
-export declare function _typeCast<T>(v: any): asserts v is T;
+export declare function _typeCast<T>(_v: any): asserts _v is T;
 /**
  * Type-safe Object.assign that checks that part is indeed a Partial<T>
  */
@@ -371,8 +371,6 @@ export type Class<T = any> = new (...args: any[]) => T;
  data.foo.push('bar');
  //=> error TS2339: Property 'push' does not exist on type 'readonly string[]'
  ```
- 
- @category Utilities
  */
 export type ReadonlyDeep<T> = T extends Primitive | ((...args: any[]) => unknown) ? T : T extends ReadonlyMap<infer KeyType, infer ValueType> ? ReadonlyMapDeep<KeyType, ValueType> : T extends ReadonlySet<infer ItemType> ? ReadonlySetDeep<ItemType> : T extends object ? ReadonlyObjectDeep<T> : unknown;
 /**

package/dist/types.js

@@ -59,7 +59,7 @@ export const _objectEntries = Object.entries;
  *   err.data = {} // can be done, because it was casted
  * }
  */
-export function _typeCast(v) { }
+export function _typeCast(_v) { }
 /**
  * Type-safe Object.assign that checks that part is indeed a Partial<T>
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.33.3",
+  "version": "15.35.0",
   "dependencies": {
     "tslib": "^2",
     "undici": "^7",

package/src/array/array.util.ts

@@ -15,7 +15,7 @@ import { END } from '../types.js'
  *
  * @param array The array to process.
  * @param size The length of each chunk.
- * @return Returns the new array containing chunks.
+ * @returns Returns the new array containing chunks.
  *
  * https://lodash.com/docs#chunk
  *
@@ -91,8 +91,7 @@ export function _pushUniqBy<T>(a: T[], mapper: Mapper<T, any>, ...items: T[]): T
  */
 export function _uniqBy<T>(arr: readonly T[], mapper: Mapper<T, any>): T[] {
   const map = new Map<any, T>()
-  for (let i = 0; i < arr.length; i++) {
-    const item = arr[i]!
+  for (const item of arr) {
     const key = item === undefined || item === null ? item : mapper(item)
     if (!map.has(key)) map.set(key, item)
   }
@@ -121,8 +120,7 @@ export function _uniqBy<T>(arr: readonly T[], mapper: Mapper<T, any>): T[] {
  */
 export function _by<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<T> {
   const map: StringMap<T> = {}
-  for (let i = 0; i < items.length; i++) {
-    const v = items[i]!
+  for (const v of items) {
     const k = mapper(v)
     if (k !== undefined) {
       map[k] = v
@@ -140,8 +138,7 @@ export function _mapBy<ITEM, KEY>(
   mapper: Mapper<ITEM, KEY>,
 ): Map<KEY, ITEM> {
   const map = new Map<KEY, ITEM>()
-  for (let i = 0; i < items.length; i++) {
-    const item = items[i]!
+  for (const item of items) {
     const key = mapper(item)
     if (key !== undefined) {
       map.set(key, item)
@@ -164,8 +161,7 @@ export function _mapBy<ITEM, KEY>(
 export function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<T[]> {
   const map: StringMap<T[]> = {}
 
-  for (let i = 0; i < items.length; i++) {
-    const item = items[i]!
+  for (const item of items) {
     const key = mapper(item)
     if (key !== undefined) {
       ;(map[key] ||= []).push(item)
@@ -531,8 +527,7 @@ export function _maxByOrUndefined<T>(
   let maxItem: T | undefined
   let max: number | string | undefined
 
-  for (let i = 0; i < array.length; i++) {
-    const item = array[i]!
+  for (const item of array) {
     const v = mapper(item)
     if (v !== undefined && (max === undefined || v > max)) {
       maxItem = item
@@ -551,8 +546,7 @@ export function _minByOrUndefined<T>(
   let minItem: T | undefined
   let min: number | string | undefined
 
-  for (let i = 0; i < array.length; i++) {
-    const item = array[i]!
+  for (const item of array) {
     const v = mapper(item)
     if (v !== undefined && (min === undefined || v < min)) {
       minItem = item

package/src/browser/analytics.util.ts

@@ -1,6 +1,8 @@
 import { isServerSide } from '../env.js'
 import { loadScript } from './script.util.js'
 
+// oxlint-disable no-var
+
 declare global {
   var dataLayer: any[]
   var gtag: (...args: any[]) => void

package/src/decorators/asyncMemo.decorator.ts

@@ -36,12 +36,12 @@ export interface AsyncMemoInstance {
 }
 
 /**
- * Like @_Memo, but allowing async MemoCache implementation.
+ * Like `@_Memo`, but allowing async MemoCache implementation.
  *
- * Implementation is more complex than @_Memo, because it needs to handle "in-flight" Promises
+ * Implementation is more complex than `@_Memo`, because it needs to handle "in-flight" Promises
  * while waiting for cache to resolve, to prevent "async swarm" issue.
  *
- * @experimental consider normal @_Memo for most of the cases, it's stable and predictable
+ * @experimental consider normal `@_Memo` for most of the cases, it's stable and predictable
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const _AsyncMemo =

package/src/decorators/logMethod.decorator.ts

@@ -138,7 +138,7 @@ export function _LogMethod(opt: LogMethodOptions = {}): MethodDecorator {
   }
 }
 
-// eslint-disable-next-line max-params
+// oxlint-disable-next-line max-params
 function logFinished(
   logger: CommonLogger,
   callSignature: string,

package/src/error/error.util.ts

@@ -304,7 +304,7 @@ export interface AppErrorOptions {
  * data - optional "any" payload.
  * data.userFriendly - if present, will be displayed to the User as is.
  *
- * Based on: https://medium.com/@xpl/javascript-deriving-from-error-properly-8d2f8f315801
+ * Based on: `https://medium.com/@xpl/javascript-deriving-from-error-properly-8d2f8f315801`
  */
 export class AppError<DATA_TYPE extends ErrorData = ErrorData> extends Error {
   data!: DATA_TYPE

package/src/json-schema/jsonSchemaBuilder.ts

@@ -1,7 +1,7 @@
 import { _uniq } from '../array/array.util.js'
 import { _deepCopy } from '../object/object.util.js'
 import { _sortObject } from '../object/sortObject.js'
-import type { AnyObject, BaseDBEntity, IsoDate, UnixTimestamp } from '../types.js'
+import type { AnyObject, BaseDBEntity, IsoDate, IsoDateTime, UnixTimestamp } from '../types.js'
 import { JSON_SCHEMA_ORDER } from './jsonSchema.cnst.js'
 import type {
   JsonSchema,
@@ -77,27 +77,47 @@ export const j = {
   unixTimestamp2000() {
     return new JsonSchemaNumberBuilder<UnixTimestamp>().unixTimestamp2000()
   },
+
   // string types
   string<T extends string = string>() {
     return new JsonSchemaStringBuilder<T>()
   },
+
+  /**
+   * Accepts only the `YYYY-MM-DD` shape from all ISO 8601 variants.
+   */
   isoDate() {
     return new JsonSchemaStringBuilder<IsoDate>().isoDate()
   },
+
+  /**
+   * Accepts strings that start with the `YYYY-MM-DDTHH:MM:SS` shape
+   * and optionally end with either a `Z` or a `+/-hh:mm` timezone part.
+   */
+  isoDateTime() {
+    return new JsonSchemaStringBuilder<IsoDateTime>().isoDateTime()
+  },
+
   // email: () => new JsonSchemaStringBuilder().email(),
   // complex types
-  object<T extends AnyObject>(props: {
-    [K in keyof T]: JsonSchemaAnyBuilder<T[K]>
-  }) {
-    return new JsonSchemaObjectBuilder<T>().addProperties(props)
+  object,
+  dbEntity<T extends AnyObject>(props: T) {
+    return j
+      .object<BaseDBEntity>({
+        id: j.string(),
+        created: j.unixTimestamp2000(),
+        updated: j.unixTimestamp2000(),
+      })
+      .extend(j.object(props))
   },
+
   rootObject<T extends AnyObject>(props: {
     [K in keyof T]: JsonSchemaAnyBuilder<T[K]>
   }) {
     return new JsonSchemaObjectBuilder<T>().addProperties(props).$schemaDraft7()
   },
-  array<ITEM = unknown>(itemSchema: JsonSchemaAnyBuilder<ITEM>) {
-    return new JsonSchemaArrayBuilder<ITEM>(itemSchema)
+  array<T extends JsonSchemaAnyBuilder<any>>(itemSchema: T) {
+    return new JsonSchemaArrayBuilder<T['infer']>(itemSchema)
   },
   tuple<T extends any[] = unknown[]>(items: JsonSchemaAnyBuilder[]) {
     return new JsonSchemaTupleBuilder<T>(items)
@@ -181,7 +201,12 @@ export class JsonSchemaAnyBuilder<T = unknown, SCHEMA_TYPE extends JsonSchema<T>
     return this
   }
 
-  optional(optional = true): this {
+  optional(): JsonSchemaAnyBuilder<T | undefined, JsonSchema<T | undefined>>
+  optional(optional: true): JsonSchemaAnyBuilder<T | undefined, JsonSchema<T | undefined>>
+  optional(
+    optional: false,
+  ): JsonSchemaAnyBuilder<Exclude<T, undefined>, JsonSchema<Exclude<T, undefined>>>
+  optional(optional = true): JsonSchemaAnyBuilder<any, JsonSchema<any>> {
     if (optional) {
       this.schema.optionalField = true
     } else {
@@ -275,6 +300,10 @@ export class JsonSchemaNumberBuilder<T extends number = number> extends JsonSche
 
   utcOffset = (): this => this.format('utcOffset')
   utcOffsetHours = (): this => this.format('utcOffsetHours')
+
+  branded<B extends number>(): JsonSchemaNumberBuilder<B> {
+    return this as unknown as JsonSchemaNumberBuilder<B>
+  }
 }
 
 export class JsonSchemaStringBuilder<T extends string = string> extends JsonSchemaAnyBuilder<
@@ -287,6 +316,10 @@ export class JsonSchemaStringBuilder<T extends string = string> extends JsonSche
     })
   }
 
+  regex(pattern: RegExp): this {
+    return this.pattern(pattern.source)
+  }
+
   pattern(pattern: string): this {
     Object.assign(this.schema, { pattern })
     return this
@@ -313,7 +346,6 @@ export class JsonSchemaStringBuilder<T extends string = string> extends JsonSche
   }
 
   email = (): this => this.format('email')
-  isoDate = (): this => this.format('date').description('IsoDate') // todo: make it custom isoDate instead
   url = (): this => this.format('url')
   ipv4 = (): this => this.format('ipv4')
   ipv6 = (): this => this.format('ipv6')
@@ -329,6 +361,25 @@ export class JsonSchemaStringBuilder<T extends string = string> extends JsonSche
   toLowerCase = (toLowerCase = true): this => this.transformModify('toLowerCase', toLowerCase)
   toUpperCase = (toUpperCase = true): this => this.transformModify('toUpperCase', toUpperCase)
 
+  branded<B extends string>(): JsonSchemaStringBuilder<B> {
+    return this as unknown as JsonSchemaStringBuilder<B>
+  }
+
+  /**
+   * Accepts only the `YYYY-MM-DD` shape from all ISO 8601 variants.
+   */
+  isoDate(): JsonSchemaStringBuilder<IsoDate> {
+    return this.format('IsoDate').branded<IsoDate>().description('IsoDate')
+  }
+
+  /**
+   * Accepts strings that start with the `YYYY-MM-DDTHH:MM:SS` shape
+   * and optionally end with either a `Z` or a `+/-hh:mm` timezone part.
+   */
+  isoDateTime(): JsonSchemaStringBuilder<IsoDateTime> {
+    return this.format('IsoDateTime').branded<IsoDateTime>().description('IsoDateTime')
+  }
+
   private transformModify(t: 'trim' | 'toLowerCase' | 'toUpperCase', add: boolean): this {
     if (add) {
       this.schema.transform = _uniq([...(this.schema.transform || []), t])
@@ -457,3 +508,21 @@ export class JsonSchemaTupleBuilder<T extends any[]> extends JsonSchemaAnyBuilde
     })
   }
 }
+
+// TODO and Notes
+// The issue is that in `j` we mix two approaches:
+// 1) the builder driven approach
+// 2) the type driven approach.
+
+function object<P extends Record<string, JsonSchemaAnyBuilder<any, any>>>(
+  props: P,
+): JsonSchemaObjectBuilder<{
+  [K in keyof P]: P[K] extends JsonSchemaAnyBuilder<infer U, any> ? U : never
+}>
+function object<T extends AnyObject>(props: {
+  [K in keyof T]: JsonSchemaAnyBuilder<T[K]>
+}): JsonSchemaObjectBuilder<T>
+
+function object(props: any): any {
+  return new JsonSchemaObjectBuilder<any>().addProperties(props)
+}

package/src/object/object.util.ts

@@ -292,7 +292,6 @@ export function _filterEmptyValues<T extends AnyObject>(obj: T, opt: MutateOptio
  *
  * **Note:** This method mutates `object`.
  *
- * @category Object
  * @param target The destination object.
  * @param sources The source objects.
  * @returns Returns `object`.
@@ -402,7 +401,7 @@ export function _get<T extends AnyObject>(obj = {} as T, path = ''): unknown {
     path
       .replaceAll(/\[([^\]]+)]/g, '.$1')
       .split('.')
-      // eslint-disable-next-line unicorn/no-array-reduce
+      // oxlint-disable-next-line unicorn/no-array-reduce
       .reduce((o, p) => o?.[p], obj)
   )
 }
@@ -417,7 +416,7 @@ type PropertyPath = Many<PropertyKey>
  * @param obj The object to modify.
  * @param path The path of the property to set.
  * @param value The value to set.
- * @return Returns object.
+ * @returns Returns object.
  *
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
@@ -432,7 +431,7 @@ export function _set<T extends AnyObject>(obj: T, path: PropertyPath, value: any
     return obj as any
   }
 
-  // eslint-disable-next-line unicorn/no-array-reduce
+  // oxlint-disable-next-line unicorn/no-array-reduce
   ;(path as any[]).slice(0, -1).reduce(
     (
       a,
@@ -458,7 +457,6 @@ export function _set<T extends AnyObject>(obj: T, path: PropertyPath, value: any
 /**
  * Checks if `path` is a direct property of `object` (not null, not undefined).
  *
- * @category Object
  * @param obj The object to query.
  * @param path The path to check.
  * @returns Returns `true` if `path` exists, else `false`.

package/src/promise/pMap.ts

@@ -126,7 +126,7 @@ export async function pMap<IN, OUT>(
 
             ret[i] = value
             resolvingCount--
-            next()
+            next() // oxlint-disable-line no-callback-in-promise
           },
           (err: Error) => {
             if (errorMode === ErrorMode.THROW_IMMEDIATELY) {
@@ -140,7 +140,7 @@ export async function pMap<IN, OUT>(
                 logger?.error(err)
               }
               resolvingCount--
-              next()
+              next() // oxlint-disable-line no-callback-in-promise
             }
           },
         )

package/src/string/safeJsonStringify.ts

@@ -20,8 +20,8 @@ export function _safeJsonStringify(
   }
 }
 
-/* eslint-disable @typescript-eslint/no-unused-expressions, no-bitwise, no-implicit-coercion */
-
+/* eslint-disable no-bitwise, no-implicit-coercion */
+// oxlint-disable no-unused-expressions
 function serializer(replacer?: Reviver, cycleReplacer?: Reviver): Reviver {
   const stack: any[] = []
   const keys: string[] = []

package/src/string/string.util.ts

@@ -31,7 +31,7 @@ export function _lowerFirst(s: string): Uncapitalize<string> {
 /**
  * Like String.split(), but with limit, returning the tail together with last element.
  *
- * @return Returns the new array of string segments.
+ * @returns Returns the new array of string segments.
  */
 export function _split(str: string, separator: string, limit: number): string[] {
   const parts = str.split(separator)

package/src/typeFest.ts

@@ -42,8 +42,6 @@ type Filter<KeyType, ExcludeType> =
  type FooWithoutA = Except<Foo, 'a' | 'c'>;
  //=> {b: string};
  ```
-
- @category Utilities
  */
 export type Except<ObjectType, KeysType extends keyof ObjectType> = {
   [KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType]
@@ -94,8 +92,6 @@ export type OmitIndexSignature<ObjectType> = {
 
  const ab: Merge<Foo, Bar> = {a: 1, b: 2};
  ```
-
- @category Utilities
  */
 export type Merge<Destination, Source> = {
   [Key in keyof OmitIndexSignature<Destination & Source>]: Key extends keyof Source
@@ -126,7 +122,6 @@ export type Merge<Destination, Source> = {
  type StringKeysAndUndefined = ConditionalKeys<Example, string | undefined>;
  //=> 'a' | 'c'
  ```
- @category Utilities
  */
 export type ConditionalKeys<Base, Condition> = NonNullable<
   // Wrap in `NonNullable` to strip away the `undefined` type from the produced union.
@@ -169,7 +164,6 @@ export type ConditionalKeys<Base, Condition> = NonNullable<
  type NonStringKeysOnly = ConditionalExcept<Example, string>;
  //=> {b: string | number; c: () => void; d: {}}
  ```
- @category Utilities
  */
 export type ConditionalExcept<Base, Condition> = Except<Base, ConditionalKeys<Base, Condition>>
 
@@ -200,7 +194,6 @@ export type ConditionalExcept<Base, Condition> = Except<Base, ConditionalKeys<Ba
  type StringKeysOnly = ConditionalPick<Example, string>;
  //=> {a: string}
  ```
- @category Utilities
  */
 export type ConditionalPick<Base, Condition> = Pick<Base, ConditionalKeys<Base, Condition>>
 

package/src/types.ts

@@ -396,7 +396,7 @@ export type FalsyValue = false | '' | 0 | null | undefined
  *   err.data = {} // can be done, because it was casted
  * }
  */
-export function _typeCast<T>(v: any): asserts v is T {}
+export function _typeCast<T>(_v: any): asserts _v is T {}
 
 /**
  * Type-safe Object.assign that checks that part is indeed a Partial<T>
@@ -469,8 +469,6 @@ export type Class<T = any> = new (...args: any[]) => T
  data.foo.push('bar');
  //=> error TS2339: Property 'push' does not exist on type 'readonly string[]'
  ```
- 
- @category Utilities
  */
 /* eslint-disable @typescript-eslint/no-restricted-types */
 export type ReadonlyDeep<T> = T extends Primitive | ((...args: any[]) => unknown)