bupkis 0.18.3 → 1.0.0

package/dist/util.cjs

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * Utility functions.
+ *
+ * @module util
+ * @category API
+ * @example
+ *
+ * ```ts
+ * import * as util from 'bupkis/util';
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKeypath = exports.keyBy = exports.has = exports.get = void 0;
+__exportStar(require("./value-to-schema.cjs"), exports);
+const { isInteger, isNaN } = Number;
+/**
+ * Retrieves the value at a given keypath from an object using dot or bracket
+ * notation.
+ *
+ * Supports keypaths like:
+ *
+ * - `'foo.bar'` - dot notation
+ * - `'foo[1].spam'` - bracket notation with array indices
+ * - `'foo["bar-baz"].quux'` - bracket notation with quoted strings
+ * - `"foo['bar-baz'].quux"` - bracket notation with single quotes
+ *
+ * This function cannot retrieve values associated with symbol keys.
+ *
+ * @example
+ *
+ * ```ts
+ * const obj = {
+ *   foo: {
+ *     bar: 'hello',
+ *     'bar-baz': { quux: 'world' },
+ *   },
+ *   arr: [{ spam: 'eggs' }],
+ * };
+ *
+ * get(obj, 'foo.bar');
+ * get(obj, 'arr[0].spam');
+ * get(obj, 'foo["bar-baz"].quux');
+ * get(obj, 'foo.nonexistent');
+ * get(obj, 'foo.nonexistent', 'default');
+ * ```
+ *
+ * @function
+ * @param obj The object to retrieve the value from
+ * @param keypath The keypath using dot or bracket notation
+ * @param defaultValue Optional default value to return if the keypath is not
+ *   found
+ * @returns The value at the keypath, or defaultValue if not found
+ */
+const get = (obj, keypath, defaultValue) => {
+    if (typeof obj !== 'object' || obj === null || typeof keypath !== 'string') {
+        return defaultValue;
+    }
+    const keys = (0, exports.parseKeypath)(keypath);
+    if (keys.length === 0) {
+        return defaultValue;
+    }
+    let current = obj;
+    for (const key of keys) {
+        if (current == null || typeof current !== 'object') {
+            return defaultValue;
+        }
+        const currentObj = current;
+        if (!(key in currentObj)) {
+            return defaultValue;
+        }
+        current = currentObj[key];
+    }
+    return current;
+};
+exports.get = get;
+/**
+ * Returns whether a value exists at a given keypath within an object using dot
+ * or bracket notation.
+ *
+ * Supports keypaths like:
+ *
+ * - `'foo.bar'` - dot notation
+ * - `'foo[1].spam'` - bracket notation with array indices
+ * - `'foo["bar-baz"].quux'` - bracket notation with quoted strings
+ * - `"foo['bar-baz'].quux"` - bracket notation with single quotes
+ *
+ * This function cannot consider values associated with symbol keys.
+ *
+ * @example
+ *
+ * ```ts
+ * const obj = {
+ *   foo: {
+ *     bar: 'hello',
+ *     'bar-baz': { quux: 'world' },
+ *   },
+ *   arr: [{ spam: 'eggs' }],
+ * };
+ *
+ * has(obj, 'foo.bar');
+ * has(obj, 'arr[0].spam');
+ * has(obj, 'foo["bar-baz"].quux');
+ * has(obj, 'foo.nonexistent');
+ * ```
+ *
+ * @function
+ * @param obj The object to examine the value from
+ * @param keypath The keypath using dot or bracket notation
+ * @returns `true` if the keypath exists, `false` otherwise
+ */
+const has = (obj, keypath) => {
+    if (typeof obj !== 'object' || obj === null || typeof keypath !== 'string') {
+        return false;
+    }
+    const keys = (0, exports.parseKeypath)(keypath);
+    if (keys.length === 0) {
+        return false;
+    }
+    let current = obj;
+    for (const key of keys) {
+        if (current == null || typeof current !== 'object') {
+            return false;
+        }
+        const currentObj = current;
+        if (!(key in currentObj)) {
+            return false;
+        }
+        current = currentObj[key];
+    }
+    return true;
+};
+exports.has = has;
+/**
+ * Maps an array of objects to an object keyed by the specified key.
+ *
+ * @function
+ * @param collection Array of objects
+ * @param key Name of key
+ * @returns Object mapping key values to objects
+ */
+const keyBy = (collection, key) => {
+    const result = {};
+    for (const item of collection) {
+        const keyValue = item[key];
+        if (typeof keyValue === 'string' ||
+            typeof keyValue === 'number' ||
+            typeof keyValue === 'symbol') {
+            result[String(keyValue)] = item;
+        }
+    }
+    return result;
+};
+exports.keyBy = keyBy;
+/**
+ * Parses a keypath string into an array of individual keys, supporting dot and
+ * bracket notation.
+ *
+ * Parsing rules:
+ *
+ * - Dot notation: Splits keys by `.` (e.g., `'foo.bar'` → `['foo', 'bar']`).
+ * - Bracket notation: Extracts keys inside `[]`. If the key is a quoted string
+ *   (single or double quotes), the quotes are removed (e.g., `'foo["bar-baz"]'`
+ *   → `['foo', 'bar-baz']`). If the key is an integer (e.g., `'foo[0]'`), it is
+ *   parsed as a number.
+ * - Mixed notation: Supports combinations (e.g., `'foo.bar[0].baz'` → `['foo',
+ *   'bar', 0, 'baz']`).
+ * - Quoted keys: Keys inside brackets can be quoted with single or double quotes.
+ *   Quotes are stripped, and the content is used as the key.
+ * - Numeric keys: If a bracketed key is an integer, it is returned as a number;
+ *   otherwise, as a string.
+ * - Whitespace inside brackets is preserved as part of the key.
+ * - Does not support escape sequences inside quotes.
+ *
+ * Limitations:
+ *
+ * - Does not support symbol keys.
+ * - Does not handle escape characters inside quoted keys.
+ *
+ * @example
+ *
+ * ```ts
+ * parseKeypath('foo.bar'); // ['foo', 'bar']
+ * parseKeypath('foo[0].baz'); // ['foo', 0, 'baz']
+ * parseKeypath('foo["bar-baz"].quux'); // ['foo', 'bar-baz', 'quux']
+ * parseKeypath("foo['bar-baz'].quux"); // ['foo', 'bar-baz', 'quux']
+ * parseKeypath("arr[10]['spam']"); // ['arr', 10, 'spam']
+ * ```
+ *
+ * @function
+ * @param keypath The keypath string to parse, using dot and/or bracket
+ *   notation.
+ * @returns An array of keys, where each key is a string or number. Bracketed
+ *   integer keys are returned as numbers; all others as strings.
+ */
+const parseKeypath = (keypath) => {
+    const keys = [];
+    let i = 0;
+    while (i < keypath.length) {
+        if (keypath[i] === '[') {
+            i++;
+            let key = '';
+            let inQuotes = false;
+            let quoteChar = '';
+            while (i < keypath.length && (keypath[i] !== ']' || inQuotes)) {
+                const char = keypath[i];
+                if (!inQuotes && (char === '"' || char === "'")) {
+                    inQuotes = true;
+                    quoteChar = char;
+                }
+                else if (inQuotes && char === quoteChar) {
+                    inQuotes = false;
+                    quoteChar = '';
+                }
+                else {
+                    key += char;
+                }
+                i++;
+            }
+            i++;
+            const numKey = Number(key);
+            keys.push(isInteger(numKey) && !isNaN(numKey) ? numKey : key);
+        }
+        else if (keypath[i] === '.') {
+            i++;
+        }
+        else {
+            let key = '';
+            while (i < keypath.length && keypath[i] !== '.' && keypath[i] !== '[') {
+                key += keypath[i];
+                i++;
+            }
+            if (key) {
+                keys.push(key);
+            }
+        }
+    }
+    return keys;
+};
+exports.parseKeypath = parseKeypath;
+//# sourceMappingURL=util.js.map

package/dist/util.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/dist/util.d.cts

@@ -0,0 +1,141 @@
+/**
+ * Utility functions.
+ *
+ * @module util
+ * @category API
+ * @example
+ *
+ * ```ts
+ * import * as util from 'bupkis/util';
+ * ```
+ */
+import { type StringKeyOf } from 'type-fest';
+import { type Keypath } from "./types.cjs";
+export * from "./value-to-schema.cjs";
+/**
+ * Retrieves the value at a given keypath from an object using dot or bracket
+ * notation.
+ *
+ * Supports keypaths like:
+ *
+ * - `'foo.bar'` - dot notation
+ * - `'foo[1].spam'` - bracket notation with array indices
+ * - `'foo["bar-baz"].quux'` - bracket notation with quoted strings
+ * - `"foo['bar-baz'].quux"` - bracket notation with single quotes
+ *
+ * This function cannot retrieve values associated with symbol keys.
+ *
+ * @example
+ *
+ * ```ts
+ * const obj = {
+ *   foo: {
+ *     bar: 'hello',
+ *     'bar-baz': { quux: 'world' },
+ *   },
+ *   arr: [{ spam: 'eggs' }],
+ * };
+ *
+ * get(obj, 'foo.bar');
+ * get(obj, 'arr[0].spam');
+ * get(obj, 'foo["bar-baz"].quux');
+ * get(obj, 'foo.nonexistent');
+ * get(obj, 'foo.nonexistent', 'default');
+ * ```
+ *
+ * @function
+ * @param obj The object to retrieve the value from
+ * @param keypath The keypath using dot or bracket notation
+ * @param defaultValue Optional default value to return if the keypath is not
+ *   found
+ * @returns The value at the keypath, or defaultValue if not found
+ */
+export declare const get: <T = unknown>(obj: unknown, keypath: Keypath, defaultValue?: T) => T | undefined;
+/**
+ * Returns whether a value exists at a given keypath within an object using dot
+ * or bracket notation.
+ *
+ * Supports keypaths like:
+ *
+ * - `'foo.bar'` - dot notation
+ * - `'foo[1].spam'` - bracket notation with array indices
+ * - `'foo["bar-baz"].quux'` - bracket notation with quoted strings
+ * - `"foo['bar-baz'].quux"` - bracket notation with single quotes
+ *
+ * This function cannot consider values associated with symbol keys.
+ *
+ * @example
+ *
+ * ```ts
+ * const obj = {
+ *   foo: {
+ *     bar: 'hello',
+ *     'bar-baz': { quux: 'world' },
+ *   },
+ *   arr: [{ spam: 'eggs' }],
+ * };
+ *
+ * has(obj, 'foo.bar');
+ * has(obj, 'arr[0].spam');
+ * has(obj, 'foo["bar-baz"].quux');
+ * has(obj, 'foo.nonexistent');
+ * ```
+ *
+ * @function
+ * @param obj The object to examine the value from
+ * @param keypath The keypath using dot or bracket notation
+ * @returns `true` if the keypath exists, `false` otherwise
+ */
+export declare const has: (obj: unknown, keypath: Keypath) => boolean;
+/**
+ * Maps an array of objects to an object keyed by the specified key.
+ *
+ * @function
+ * @param collection Array of objects
+ * @param key Name of key
+ * @returns Object mapping key values to objects
+ */
+export declare const keyBy: <const T extends readonly Record<PropertyKey, any>[], K extends StringKeyOf<T[number]>>(collection: T, key: K) => Record<string, T[number]>;
+/**
+ * Parses a keypath string into an array of individual keys, supporting dot and
+ * bracket notation.
+ *
+ * Parsing rules:
+ *
+ * - Dot notation: Splits keys by `.` (e.g., `'foo.bar'` → `['foo', 'bar']`).
+ * - Bracket notation: Extracts keys inside `[]`. If the key is a quoted string
+ *   (single or double quotes), the quotes are removed (e.g., `'foo["bar-baz"]'`
+ *   → `['foo', 'bar-baz']`). If the key is an integer (e.g., `'foo[0]'`), it is
+ *   parsed as a number.
+ * - Mixed notation: Supports combinations (e.g., `'foo.bar[0].baz'` → `['foo',
+ *   'bar', 0, 'baz']`).
+ * - Quoted keys: Keys inside brackets can be quoted with single or double quotes.
+ *   Quotes are stripped, and the content is used as the key.
+ * - Numeric keys: If a bracketed key is an integer, it is returned as a number;
+ *   otherwise, as a string.
+ * - Whitespace inside brackets is preserved as part of the key.
+ * - Does not support escape sequences inside quotes.
+ *
+ * Limitations:
+ *
+ * - Does not support symbol keys.
+ * - Does not handle escape characters inside quoted keys.
+ *
+ * @example
+ *
+ * ```ts
+ * parseKeypath('foo.bar'); // ['foo', 'bar']
+ * parseKeypath('foo[0].baz'); // ['foo', 0, 'baz']
+ * parseKeypath('foo["bar-baz"].quux'); // ['foo', 'bar-baz', 'quux']
+ * parseKeypath("foo['bar-baz'].quux"); // ['foo', 'bar-baz', 'quux']
+ * parseKeypath("arr[10]['spam']"); // ['arr', 10, 'spam']
+ * ```
+ *
+ * @function
+ * @param keypath The keypath string to parse, using dot and/or bracket
+ *   notation.
+ * @returns An array of keys, where each key is a string or number. Bracketed
+ *   integer keys are returned as numbers; all others as strings.
+ */
+export declare const parseKeypath: <S extends string = string>(keypath: Keypath<S>) => (number | string)[];
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,KAAK,OAAO,EAAE,oBAAmB;AAE1C,sCAAqC;AAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,GAAG,OAAO,EAC7B,KAAK,OAAO,EACZ,SAAS,OAAO,EAChB,eAAe,CAAC,KACf,CAAC,GAAG,SA4BN,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,GAAG,GAAI,KAAK,OAAO,EAAE,SAAS,OAAO,KAAG,OA2BpD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAChB,KAAK,CAAC,CAAC,SAAS,SAAS,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,EACnD,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAEhC,YAAY,CAAC,EACb,KAAK,CAAC,KACL,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAe1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EACpD,SAAS,OAAO,CAAC,CAAC,CAAC,KAClB,CAAC,MAAM,GAAG,MAAM,CAAC,EAgDnB,CAAC"}

package/dist/util.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Utility functions.
+ *
+ * @module util
+ * @category API
+ * @example
+ *
+ * ```ts
+ * import * as util from 'bupkis/util';
+ * ```
+ */
+import { type StringKeyOf } from 'type-fest';
+import { type Keypath } from "./types.js";
+export * from "./value-to-schema.js";
+/**
+ * Retrieves the value at a given keypath from an object using dot or bracket
+ * notation.
+ *
+ * Supports keypaths like:
+ *
+ * - `'foo.bar'` - dot notation
+ * - `'foo[1].spam'` - bracket notation with array indices
+ * - `'foo["bar-baz"].quux'` - bracket notation with quoted strings
+ * - `"foo['bar-baz'].quux"` - bracket notation with single quotes
+ *
+ * This function cannot retrieve values associated with symbol keys.
+ *
+ * @example
+ *
+ * ```ts
+ * const obj = {
+ *   foo: {
+ *     bar: 'hello',
+ *     'bar-baz': { quux: 'world' },
+ *   },
+ *   arr: [{ spam: 'eggs' }],
+ * };
+ *
+ * get(obj, 'foo.bar');
+ * get(obj, 'arr[0].spam');
+ * get(obj, 'foo["bar-baz"].quux');
+ * get(obj, 'foo.nonexistent');
+ * get(obj, 'foo.nonexistent', 'default');
+ * ```
+ *
+ * @function
+ * @param obj The object to retrieve the value from
+ * @param keypath The keypath using dot or bracket notation
+ * @param defaultValue Optional default value to return if the keypath is not
+ *   found
+ * @returns The value at the keypath, or defaultValue if not found
+ */
+export declare const get: <T = unknown>(obj: unknown, keypath: Keypath, defaultValue?: T) => T | undefined;
+/**
+ * Returns whether a value exists at a given keypath within an object using dot
+ * or bracket notation.
+ *
+ * Supports keypaths like:
+ *
+ * - `'foo.bar'` - dot notation
+ * - `'foo[1].spam'` - bracket notation with array indices
+ * - `'foo["bar-baz"].quux'` - bracket notation with quoted strings
+ * - `"foo['bar-baz'].quux"` - bracket notation with single quotes
+ *
+ * This function cannot consider values associated with symbol keys.
+ *
+ * @example
+ *
+ * ```ts
+ * const obj = {
+ *   foo: {
+ *     bar: 'hello',
+ *     'bar-baz': { quux: 'world' },
+ *   },
+ *   arr: [{ spam: 'eggs' }],
+ * };
+ *
+ * has(obj, 'foo.bar');
+ * has(obj, 'arr[0].spam');
+ * has(obj, 'foo["bar-baz"].quux');
+ * has(obj, 'foo.nonexistent');
+ * ```
+ *
+ * @function
+ * @param obj The object to examine the value from
+ * @param keypath The keypath using dot or bracket notation
+ * @returns `true` if the keypath exists, `false` otherwise
+ */
+export declare const has: (obj: unknown, keypath: Keypath) => boolean;
+/**
+ * Maps an array of objects to an object keyed by the specified key.
+ *
+ * @function
+ * @param collection Array of objects
+ * @param key Name of key
+ * @returns Object mapping key values to objects
+ */
+export declare const keyBy: <const T extends readonly Record<PropertyKey, any>[], K extends StringKeyOf<T[number]>>(collection: T, key: K) => Record<string, T[number]>;
+/**
+ * Parses a keypath string into an array of individual keys, supporting dot and
+ * bracket notation.
+ *
+ * Parsing rules:
+ *
+ * - Dot notation: Splits keys by `.` (e.g., `'foo.bar'` → `['foo', 'bar']`).
+ * - Bracket notation: Extracts keys inside `[]`. If the key is a quoted string
+ *   (single or double quotes), the quotes are removed (e.g., `'foo["bar-baz"]'`
+ *   → `['foo', 'bar-baz']`). If the key is an integer (e.g., `'foo[0]'`), it is
+ *   parsed as a number.
+ * - Mixed notation: Supports combinations (e.g., `'foo.bar[0].baz'` → `['foo',
+ *   'bar', 0, 'baz']`).
+ * - Quoted keys: Keys inside brackets can be quoted with single or double quotes.
+ *   Quotes are stripped, and the content is used as the key.
+ * - Numeric keys: If a bracketed key is an integer, it is returned as a number;
+ *   otherwise, as a string.
+ * - Whitespace inside brackets is preserved as part of the key.
+ * - Does not support escape sequences inside quotes.
+ *
+ * Limitations:
+ *
+ * - Does not support symbol keys.
+ * - Does not handle escape characters inside quoted keys.
+ *
+ * @example
+ *
+ * ```ts
+ * parseKeypath('foo.bar'); // ['foo', 'bar']
+ * parseKeypath('foo[0].baz'); // ['foo', 0, 'baz']
+ * parseKeypath('foo["bar-baz"].quux'); // ['foo', 'bar-baz', 'quux']
+ * parseKeypath("foo['bar-baz'].quux"); // ['foo', 'bar-baz', 'quux']
+ * parseKeypath("arr[10]['spam']"); // ['arr', 10, 'spam']
+ * ```
+ *
+ * @function
+ * @param keypath The keypath string to parse, using dot and/or bracket
+ *   notation.
+ * @returns An array of keys, where each key is a string or number. Bracketed
+ *   integer keys are returned as numbers; all others as strings.
+ */
+export declare const parseKeypath: <S extends string = string>(keypath: Keypath<S>) => (number | string)[];
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,KAAK,OAAO,EAAE,mBAAmB;AAE1C,qCAAqC;AAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,GAAG,OAAO,EAC7B,KAAK,OAAO,EACZ,SAAS,OAAO,EAChB,eAAe,CAAC,KACf,CAAC,GAAG,SA4BN,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,GAAG,GAAI,KAAK,OAAO,EAAE,SAAS,OAAO,KAAG,OA2BpD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAChB,KAAK,CAAC,CAAC,SAAS,SAAS,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,EACnD,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAEhC,YAAY,CAAC,EACb,KAAK,CAAC,KACL,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAe1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EACpD,SAAS,OAAO,CAAC,CAAC,CAAC,KAClB,CAAC,MAAM,GAAG,MAAM,CAAC,EAgDnB,CAAC"}