topkat-utils 1.0.60 → 1.1.2

package/src/isset.ts

@@ -0,0 +1,3 @@
+export function isset(...elms) {
+    return elms.every(elm => typeof elm !== 'undefined' && elm !== null)
+}

package/src/logger-utils.ts

@@ -0,0 +1,349 @@
+//----------------------------------------
+// LOGGER
+//----------------------------------------
+import { configFn } from "./private/config"
+import { isset } from "./isset"
+import { Color } from "./private/types"
+import { removeCircularJSONstringify } from "./remove-circular-json-stringify"
+import { cleanStackTrace } from "./error-utils"
+
+export const logger = {
+    log(str, type = 'log') {
+        const { preprocessLog } = configFn()
+        if (typeof preprocessLog === 'function') str = preprocessLog(str) || str
+        if (isset(console[type])) console[type](str)
+        else if (type === 'appError') console.warn(str)
+        else console.log(str)
+
+        logger.raw.push(str + `\n`)
+        logger.raw = logger.raw.slice(logger.raw.length - configFn().nbOfLogsToKeep, logger.raw.length)
+    },
+    /**
+     * @param {String[]|String} inputLogs
+     */
+    toHtml(inputLogs = [...logger.raw]) {
+        if (!Array.isArray(inputLogs)) inputLogs = [inputLogs]
+        const code2css = {
+            2: `opacity:.5`, // dim
+            32: `color:#679933`, // green
+            31: `color:#A8383B`, // red
+            33: `color:#D7941C`, // yellow
+            35: `color:#C21949`, // magenta
+            36: `color:#128C6D`, // cyan
+            34: `color:#1B568B`, // blue
+        }
+
+        let htmlLogs = ''
+        inputLogs.join('<br/>').split('\x1b[').forEach((bit, i) => {
+            // the first doesn't have a preceding (may be undef)
+            if (bit) {
+                if (i !== 0) {
+                    const [, code, R, G, B, content] = bit.match(/(^\d\d?)(?:;|m)(?:\d;(\d+);(\d+);(\d+)m)?(.*$)/) || []
+                    if (content) {
+                        const style = !isset(R) ? isset(code) ? code2css[code] : undefined : `color:rgb(${R},${G},${B})`
+                        htmlLogs += isset(style) ? `<span style='${style}'>${content.replace(/\n/g, '<br>')}</span>` : content.replace(/\n/g, '<br>')
+                    }
+                } else htmlLogs += bit.replace(/\n/g, '<br>')
+            }
+        })
+        return `<div style='color:#ccc'>${htmlLogs}<br></div>`
+    },
+    toText(inputLogs = [...logger.raw]) {
+        const str = Array.isArray(inputLogs) ? inputLogs.join('\n') : inputLogs
+        return str.replace(/\x1b\[.*?m/g, '')
+    },
+    raw: [],
+    json: [],
+}
+
+/**
+// console colored output
+// * console.log(C.green(C.dim('Hey bro !')))
+// * or C.log() // will use padding and color defined by themes
+// * or C.line('MY TITLE', 53)
+// * or C.gradientize(myLongString)
+*/
+export const C = {
+    dim: str => C.output(2, str), // opacity 0.5
+    green: str => C.output(32, str),
+    red: str => C.output(31, str),
+    yellow: str => C.output(33, str),
+    grey: str => C.output(2, str),
+    magenta: str => C.output(35, str),
+    cyan: str => C.output(36, str),
+    blue: str => C.output(34, str),
+    primary: str => {
+        const primary: Color = configFn().terminal.theme.primary
+        return C.rgb(...primary) + str + C.reset
+    },
+    reset: '\x1b[0m',
+    output: (code, str = '') => configFn().terminal.noColor ? str : `\x1b[${code}m${str.toString().split('\n').join('\x1b[0m\n\x1b[2m')}\x1b[0m`,
+    // true RGB colors B-*
+    rgb: (r, g = 0, b = 0) => configFn().terminal.noColor || !isset(r, g, b) ? '' : `\x1b[38;2;${r};${g};${b}m`,
+    bg: (r?, g?, b?) => configFn().terminal.noColor || !isset(r, g, b) ? '' : `${'\x1b['}48;2;${r};${g};${b}m`,
+    /** Output a line of title */
+    line(title = '', length = configFn().terminal.theme.pageWidth, clr = configFn().terminal.theme.primary, char = '=', paddingX = configFn().terminal.theme.paddingX) {
+        const padX = ' '.repeat(paddingX)
+        this.log('\u00A0\n' + padX + this.rgb(...clr) + (title + ' ').padEnd(length, char) + this.reset + padX + '\u00A0\n')
+    },
+    /** Eg: ['cell1', 'cell2', 'cell3'], [25, 15] will start cell2 at 25 and cell 3 at 25 + 15
+     * @param {Array} limits default divide the viewport
+     */
+    cols(strings, limits = [], clr = configFn().terminal.theme.fontColor, paddingX = configFn().terminal.theme.paddingX) {
+
+        if (!limits.length) {
+            const colWidth = Math.round(configFn().terminal.theme.pageWidth / strings.length)
+            limits = Array(strings.length - 1).fill(2).map((itm, i) => colWidth * i + 1)
+        }
+        const str = strings.reduce((glob, str = '', i) => {
+            const realCharLength = str.toString().replace(/\x1b\[.*?m/, '').length
+            const charLength = str.toString().length
+            const realLimit = limits[i] + charLength - realCharLength
+            return glob + str.toString().substring(0, realLimit || 999).padEnd(realLimit || 0, ' ')
+        }, '')
+        this.logClr(str, clr, paddingX)
+    },
+    /** Console log alias */
+    log(...stringsCtxMayBeFirstParam) {
+        stringsCtxMayBeFirstParam.forEach(str => this.logClr(str, undefined, undefined))
+    },
+    logClr(str, clr = configFn().terminal.theme.fontColor, paddingX = configFn().terminal.theme.paddingX) {
+        if (!isset(str)) return
+        const padX = ' '.repeat(paddingX)
+        str = padX + (isset(clr) ? this.rgb(...clr) : '') + str.toString().replace(/\n/g, '\n' + padX + (isset(clr) ? this.rgb(...clr) : ''))
+        logger.log(str + this.reset, 'log')
+    },
+    info(...str) {
+        str.forEach((s, i) => {
+            if (i === 0) this.logClr('ⓘ  ' + s, configFn().terminal.theme.primary)
+            else this.log(this.dimStrSplit(s))
+        })
+        this.log(' ')
+    },
+    success(...str) {
+        str.forEach((s, i) => {
+            if (i === 0) this.log(this.green('✓  ' + s))
+            else this.log(this.dimStrSplit(s))
+        })
+    },
+    /** First param **false** to avoid logging stack trace */
+    error: (...errors) => logErrPrivate('error', [255, 0, 0], ...errors),
+    /** First param **false** to avoid logging stack trace */
+    warning: (...str) => logErrPrivate('warn', [255, 122, 0], ...str),
+    customError: (color, ...str) => logErrPrivate('error', color, ...str),
+    customWarning: (color, ...str) => logErrPrivate('warn', color, ...str),
+    applicationError: (color, ...str) => logErrPrivate('appError', color, ...str),
+    warningLight: (color, ...str) => logErrPrivate('warn', [196, 120, 52], ...str),
+    dimStrSplit(...logs) {
+        let logsStr = []
+        logs.filter(isset).forEach(log => log.toString().split('\n').forEach(line => line && logsStr.push(this.dim(`    ${line}`))))
+        return logsStr.join('\n')
+    },
+    notifShow() {
+        console.log('\n\u00A0')
+        this.notifications.forEach(fn => fn())
+        this.notifications = []
+        console.log('\n\u00A0')
+    },
+    /** Keep in memory the logs to show when needed with C.notifShow()
+     * Ex: C.notification('info', str); */
+    notification(type, ...messages) {
+        this.notifications.push(() => {
+            if (isset(this[type])) {
+                this[type](...messages)
+            } else {
+                this.warning('Wrong param for C.notification')
+            }
+        })
+    },
+    notifications: [],
+    /** Gratientize lines of text (separated by \n) */
+    gradientize(str = '', rgb1 = configFn().terminal.theme.shade1, rgb2 = configFn().terminal.theme.shade2, bgRgb = configFn().terminal.theme.bgColor, paddingY = configFn().terminal.theme.paddingY, paddingX = configFn().terminal.theme.paddingX) {
+
+        const lines = str.split('\n')
+        const largestLine = lines.reduce((sum, line) => sum < line.length ? line.length : sum, 0)
+        const rgbParts = rgb1.map((val, i) => (val - rgb2[i]) / (lines.length))
+
+        const bg = bgRgb ? this.bg(bgRgb[0], bgRgb[1], bgRgb[2]) : ''
+        const padX = ' '.repeat(paddingX)
+        const padLine = bg + padX + ' '.padEnd(largestLine, ' ') + padX + '\x1b[0m\n'
+
+        console.log(padLine.repeat(paddingY) +
+            lines.reduce((s, line, i) => {
+                return s + bg + padX + this.rgb(...rgb1.map((val, i2) => Math.round(val - i * rgbParts[i2]))) + line.padEnd(largestLine, ' ') + padX + '\x1b[0m\n'
+            }, '') +
+            padLine.repeat(paddingY))
+    },
+    debugModeLog(title, ...string) {
+        this.logClr('🐞 ' + title, configFn().terminal.theme.debugModeColor, 0)
+        this.log(this.dimStrSplit(...string))
+    },
+    // DEPRECATED
+    useTheme() { },
+}
+
+export function logErrPrivate(type, color: Color, ...errors) {
+    const { isProd } = configFn()
+
+    if (errors.length === 1 && typeof errors[0].log === 'function') return errors[0].log()
+
+    let stackTrace = (new Error('')).stack || ''
+    const displayStack = errors[0] === false ? errors.shift() : true
+    const symbol = type === 'error' ? '✘ ' : '⚠ '
+    if (errors.length > 1 && !isset(errors[0])) errors.shift()
+
+    const getStringFromErr = (err, i) => {
+        if (!isset(err)) return ''
+        else if (typeof err === 'string') {
+            if (i === 0) return C.rgb(...color) + symbol + err + C.reset
+            else return err.split('\n').map(val => C.dim(val)).join('\n')
+        } else if (err instanceof Error) {
+            const { str, stackTrace: stkTrc } = stringifyInstanceOfError(err, type, color)
+            if (stkTrc) stackTrace = stkTrc
+            return str
+        } else if (typeof err === 'object') {
+            let msg = ''
+            msg += removeCircularJSONstringify(err, 2).split('\n').map(val => C.dim(val)).join('\n') + '\n'
+            const { str, stackTrace: stkTrc } = stringifyExtraInfos(err.extraInfo || err, type, color)
+            if (stkTrc) stackTrace = stkTrc
+            msg += str
+            return msg
+        } else return ''
+    }
+
+    if (errors.length && errors[0]) {
+        const messages = errors.map((e, i) => {
+            if (typeof e.log === 'function') {
+                e.log()
+                return ''
+            } else return getStringFromErr(e, i)
+        })
+        // Stack
+        if (displayStack) {
+            messages.push(isProd ? stackTrace : cleanStackTrace(stackTrace) + '\n')
+        }
+        logger.log(messages.join(''), type)
+    }
+}
+
+export function stringifyInstanceOfError(err, type = 'error', color: Color = [255, 0, 0], level = 0) { // level = keep track of recursions
+    if (level > 5) return { str: '' }
+    let str = ''
+    let stackTrace
+    const symbol = type === 'error' ? '✘ ' : '⚠ '
+    const title = err.msg || err.message || err.id || (err.stack ? err.stack.split('\n')[0] : 'Error')
+    // Err mess
+    str += C.rgb(...color) + symbol + title + C.reset + '\n'
+    if (err.stack) stackTrace = err.stack // more relevant
+    // ExtraInfos
+    if (isset(err.extraInfo)) {
+        const { str: str2, stackTrace: stkTrc } = stringifyExtraInfos(err.extraInfo, type, color, level++)
+        if (stkTrc) stackTrace = stkTrc
+        str += str2
+    }
+    return { str, stackTrace }
+}
+
+export function stringifyExtraInfos(extraInfoOriginal, type, color, level = 0) {
+    let stackTrace
+    const originalError = [C.dim(`ORIGINAL ERROR ${'-'.repeat(39)}\n`)]
+    if (extraInfoOriginal instanceof Error) { // case where error is passed directly to extraInfos
+        return stringifyInstanceOfError(extraInfoOriginal, type, color)
+    } else {
+        const extraInfo = { ...extraInfoOriginal }
+        const extraInfos = [C.dim(`EXTRA INFOS ${'-'.repeat(41)}\n`)]
+        if (typeof extraInfo === 'object' && Object.keys(extraInfo).length) {
+            for (const itemName in extraInfo) {
+                if (extraInfo[itemName] instanceof Error) {
+                    const { str, stackTrace: stkTrc } = stringifyInstanceOfError(extraInfo[itemName], type, color, level++)
+                    originalError.push(str)
+                    stackTrace = stkTrc
+                    delete extraInfo[itemName]
+                }
+            }
+        }
+        if (Object.keys(extraInfo).length) {
+            extraInfos.push(
+                removeCircularJSONstringify(extraInfo, 2)
+                    .replace(/(?:^\s*{(?:\n {2})?|}\s*$)/g, '')
+                    .replace(/\n {2}/g, '\n')
+                    .split('\n')
+                    .map(val => C.dim(val)).join('\n') + '\n')
+        }
+        return {
+            str: (extraInfos.length > 1 ? extraInfos.join('') : '') + (originalError.length > 1 ? originalError.join('') + '\n' : ''),
+            stackTrace
+        }
+    }
+}
+
+/**
+ * Call this at each steps of your progress and change the step value
+ * @param {Number} step Number of "char" to output
+ * @param {String} char Default: '.'
+ * @param {String} msg String before char. Final output will be `${str}${char.repeat(step)}`
+ */
+export function cliProgressBar(step, char = '.', msg = `\x1b[2mⓘ Waiting response`) {
+    if (isset(process) && isset(process.stdout) && isset(process.stdout.clearLine)) {
+        process.stdout.clearLine(0)
+        process.stdout.cursorTo(0)
+        process.stdout.write(`${msg}${char.repeat(step)}\x1b[0m`) // \x1b[0m == reset color
+    }
+}
+
+/** This allow an intuitive inline loading spinner with a check mark when loading as finished or a red cross for errors  */
+class cliLoadingSpinner {
+    /** Please use it like spinner.start('myStuff') then spinner.end()
+     * @param {String} type in: ['arrow', 'dots']
+     */
+    frameRate: number
+    animFrames: string[]
+    activeProcess: any
+    frameNb: number
+    progressMessage: string
+    interval: any
+
+    constructor(type = 'dots', activeProcess = process) {
+        const anims = {
+            arrow: {
+                interval: 120,
+                frames: ['▹▹▹▹▹', '▸▹▹▹▹', '▹▸▹▹▹', '▹▹▸▹▹', '▹▹▹▸▹', '▹▹▹▹▸']
+            },
+            dots: {
+                interval: 80,
+                frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+            }
+        }
+        this.frameRate = anims[type].interval
+        this.animFrames = anims[type].frames
+        this.activeProcess = activeProcess
+    }
+    start(msg) {
+        this.frameNb = 0
+        this.progressMessage = msg
+        this.interval = setInterval(() => {
+            this.activeProcess.stdout.clearLine()
+            this.activeProcess.stdout.cursorTo(0)
+            const symbol = this.animFrames[this.frameNb++ % this.animFrames.length]
+            this.activeProcess.stdout.write(C.primary(symbol) + ' ' + this.progressMessage)
+        }, this.frameRate)
+    }
+    end(error = false) {
+        clearInterval(this.interval)
+        this.activeProcess.stdout.clearLine()
+        this.activeProcess.stdout.cursorTo(0)
+        this.activeProcess.stdout.write(
+            error ? C.red('✘ ' + this.progressMessage + '\n\n')
+                : '\x1b[32m✓ ' + this.progressMessage + '\n\n')
+        this.progressMessage = ''
+    }
+    error() {
+        return this.end(true)
+    }
+}
+
+
+export function dim(str = '') {
+    return configFn().terminal.noColor ? str : `\x1b[2m${str.toString().split('\n').join('\x1b[0m\n\x1b[2m')}\x1b[0m`
+}
+

package/src/loop-utils.ts

@@ -0,0 +1,101 @@
+//----------------------------------------
+// LOOP UTILS
+//----------------------------------------
+import { ObjectGeneric } from "./private/types"
+import { err500IfNotSet } from "./error-utils"
+import { isObject } from "./is-object"
+
+export function forI<T extends any[] | any>(nbIterations: number, callback: (number: number, previousValue, arrayOfPreviousValues: any[]) => T): T[] {
+    const results = []
+    for (let i = 0; i < nbIterations; i++) {
+        const prevValue = results[results.length - 1]
+        results.push(callback(i, prevValue, results))
+    }
+    return results
+}
+
+export async function forIasync<T extends any[] | any>(nbIterations: number, callback: (number) => T): Promise<T[]> {
+    const results = []
+    for (let i = 0; i < nbIterations; i++) {
+        results.push(await callback(i))
+    }
+    return results
+}
+
+
+
+export type RecursiveCallback = (item: any, addr: string, lastElementKey: string | number, parent: ObjectGeneric | any[]) => false | any
+/**
+ * @param {any} item the first array or object or whatever you want to recursively browse
+ * @param {function} callback the callback you want to apply on items including the main one
+ *   * this callback has 2 arguments: (item, address) =>
+ *   * `item` => the actual item
+ *   * `addr` => the address of the item, not including root (Eg: subItem1.sub2.[3].[2]) array indexes are juste written as numbers
+ *   * `lastElementKey` => the key of last item. May be a number if last item is an array
+ *   * `parent` => reference the parent object as this is the only way of reassigning a value for the item. Eg: parent[lastElementKey] = myNewItem
+ *   * **NOTE** => if a key of an item contains dots, they will be replaced by '%' in `addr`
+ *   * **NOTE2** => if false is returned by the callback it will stop all other iterations (but not in an array)
+ * @param {string} addr$ optional, the base address for the callback function
+ * @param lastElementKey technical field
+ * NOTE: will remove circular references
+ * /!\ check return values
+ */
+export async function recursiveGenericFunction(item: ObjectGeneric | any[], callback: RecursiveCallback, addr$ = '', lastElementKey: string | number = '', parent?, techFieldToAvoidCircularDependency = []) {
+    err500IfNotSet({ callback })
+
+    if (!techFieldToAvoidCircularDependency.includes(item)) {
+        const result = addr$ === '' ? true : await callback(item, addr$, lastElementKey, parent)
+
+        if (result !== false) {
+            const addr = addr$ ? addr$ + '.' : ''
+            if (Array.isArray(item)) {
+                techFieldToAvoidCircularDependency.push(item)
+                await Promise.all(item.map(
+                    (e, i) => recursiveGenericFunction(e, callback, addr + '[' + i + ']', i, item, techFieldToAvoidCircularDependency)
+                ))
+            } else if (isObject(item)) {
+                techFieldToAvoidCircularDependency.push(item)
+                await Promise.all(Object.entries(item).map(
+                    ([key, val]) => recursiveGenericFunction(val, callback, addr + key.replace(/\./g, '%'), key, item, techFieldToAvoidCircularDependency)
+                ))
+            }
+        }
+    }
+    return item
+}
+
+/**
+ * @param {any} item the first array or object or whatever you want to recursively browse
+ * @param {function} callback the callback you want to apply on items including the main one
+ *   * this callback has 2 arguments: (item, address) =>
+ *   * `item` => the actual item
+ *   * `addr` => the address of the item, not including root (Eg: subItem1.sub2.[3].[2]) array indexes are juste written as numbers
+ *   * `lastElementKey` => the key of last item. May be a number if last item is an array
+ *   * `parent` => reference the parent object as this is the only way of reassigning a value for the item. Eg: parent[lastElementKey] = myNewItem
+ *   * **NOTE** => if a key of an item contains dots, they will be replaced by '%' in `addr`
+ *   * **NOTE2** => if false is returned by the callback it will stop all other iterations (but not in an array)
+ *   * **NOTE3** => to reassign a key use =>  parent[lastElementKey] = myNewItem
+ * @param {string} addr$ optional, the base address for the callback function
+ * @param lastElementKey technical field
+ * NOTE: will remove circular references
+ * /!\ check return values
+ */
+export function recursiveGenericFunctionSync(item: ObjectGeneric | any[], callback: RecursiveCallback, addr$ = '', lastElementKey: string | number = '', parent?, techFieldToAvoidCircularDependency = []) {
+    err500IfNotSet({ callback })
+
+    if (!techFieldToAvoidCircularDependency.includes(item)) {
+        const result = addr$ === '' ? true : callback(item, addr$, lastElementKey, parent)
+
+        if (result !== false) {
+            const addr = addr$ ? addr$ + '.' : ''
+            if (Array.isArray(item)) {
+                techFieldToAvoidCircularDependency.push(item) // do not up one level
+                item.forEach((e, i) => recursiveGenericFunctionSync(e, callback, addr + '[' + i + ']', i, item, techFieldToAvoidCircularDependency))
+            } else if (isObject(item)) {
+                techFieldToAvoidCircularDependency.push(item)
+                Object.entries(item).forEach(([key, val]) => recursiveGenericFunctionSync(val, callback, addr + key.replace(/\./g, '%'), key, item, techFieldToAvoidCircularDependency))
+            }
+        }
+    }
+    return item
+}

package/src/math-utils.ts

@@ -0,0 +1,38 @@
+//----------------------------------------
+// MATH UTILS
+//----------------------------------------
+import { isset } from "./isset"
+
+/** Round with custom number of decimals (default:0) */
+export function round(number: number | string, decimals = 0) { return Math.round((typeof number === 'number' ? number : parseFloat(number)) * Math.pow(10, decimals)) / Math.pow(10, decimals) }
+/** Round with custom number of decimals (default:2) */
+export function round2(number: number | string, decimals = 2) { return round(number, decimals) }
+
+/** Is number between two numbers (including those numbers) */
+export function isBetween(number: number, min: number, max: number, inclusive = true) { return inclusive ? number <= max && number >= min : number < max && number > min }
+
+/** Random number between two values with 0 decimals by default */
+export function random(nb1: number, nb2: number, nbOfDecimals = 0) { return round(Math.random() * (nb2 - nb1) + nb1, nbOfDecimals) }
+
+/** Sum all values of an array, all values MUST be numbers */
+export function sumArray(array: number[]) {
+    return array.filter(item => typeof item === 'number').reduce((sum, val) => isset(val) ? val + sum : sum, 0)
+}
+
+/** Moyenne / average between array of values 
+ * @param {Number} round number of decimals to keep. Default:2
+*/
+export function moyenne(array: number[], nbOfDecimals = 2) {
+    return round(sumArray(array) / array.length, nbOfDecimals)
+}
+
+/** length default 2, shortcut for 1 to 01 */
+export function pad(numberOrStr: number | string, length = 2) { return ('' + numberOrStr).padStart(length, '0') }
+
+/** return the number or the closest number of the range
+ * * nb min max  => returns
+ * * 7  5   10   => 7 // in the range
+ * * 2  5   10   => 5 // below the min value
+ * * 99 5   10   => 10// above the max value
+ */
+export function minMax(nb: number, min: number, max: number) { return Math.max(min, Math.min(nb, max)) }

package/src/mongo-utils.ts

@@ -0,0 +1,38 @@
+//----------------------------------------
+// MONGO UTILS
+//----------------------------------------
+import { isType } from "./validation-utils"
+import { isset } from "./isset"
+
+/** @return undefined if cannot find _id */
+export function getId(obj: any = {}): string {
+    if (!obj) return // null case
+    if (obj._id) return obj._id.toString()
+    else if (isType(obj, 'objectId')) return obj.toString()
+}
+
+/** Merge filter with correct handling of OR and AND 
+ * @param {Object} filterA 
+ * @param {Object} filterB 
+ * @param {Boolean} assignToFilterA defualt false: if true, it will modify filterA, else it will return merged filters as a new object
+ */
+export function mongoFilterMerger(filterA, filterB, assignToFilterA = false) {
+    if (isset(filterA.$and) && isset(filterB.$and)) {
+        filterA.$and.push(...filterB.$and)
+        delete filterB.$and
+    }
+    if (isset(filterA.$or) && isset(filterB.$or)) {
+        if (!isset(filterA.$and)) filterA.$and = []
+        filterA.$and.push({ $or: filterA.$or }, { $or: filterA.$or })
+        delete filterB.$or
+    }
+    if (assignToFilterA) {
+        Object.assign(filterA, filterB)
+        return filterA
+    } else return { ...filterA, ...filterB }
+}
+
+export function mongoPush(field: string, value: any, fields: { [k: string]: any }) {
+    if (!isset(fields.$push)) fields.$push = {}
+    fields.$push[field] = value
+}