@dereekb/util 13.2.2 → 13.3.1

package/src/lib/encryption/encryption.object.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Branded type representing a string that has been encrypted.
+ *
+ * Use this type to distinguish encrypted ciphertext from plain strings at the type level.
+ * The actual encryption algorithm is determined by the {@link StringEncryptionProvider}.
+ */
+export type EncryptedString = string;
+/**
+ * Encrypts a plaintext string to an encrypted string.
+ */
+export type EncryptStringFunction = (plaintext: string) => EncryptedString;
+/**
+ * Decrypts an encrypted string back to plaintext.
+ */
+export type DecryptStringFunction = (ciphertext: EncryptedString) => string;
+/**
+ * Provider that can encrypt and decrypt strings.
+ *
+ * Implementations wrap a specific algorithm (e.g. AES-256-GCM) and key management
+ * behind a simple encrypt/decrypt interface for use with selective field encryption.
+ */
+export interface StringEncryptionProvider {
+    readonly encrypt: EncryptStringFunction;
+    readonly decrypt: DecryptStringFunction;
+}
+/**
+ * Configuration for selective object field encryption.
+ *
+ * @template T - The object type being encrypted.
+ * @template F - The union of field names to encrypt.
+ */
+export interface SelectiveFieldEncryptionConfig<T, F extends keyof T> {
+    /**
+     * The encryption provider for string encrypt/decrypt.
+     */
+    readonly provider: StringEncryptionProvider;
+    /**
+     * Fields to encrypt/decrypt.
+     */
+    readonly fields: F[];
+    /**
+     * Prefix marker for encrypted fields.
+     *
+     * @defaultValue '$'
+     */
+    readonly prefix?: string;
+}
+/**
+ * Default prefix used for encrypted field names.
+ */
+export declare const DEFAULT_ENCRYPTED_FIELD_PREFIX = "$";
+/**
+ * Maps an object type so that specified fields are removed and replaced with
+ * prefixed encrypted string fields.
+ *
+ * Given `{ a: number; b: string; c: boolean }` with fields `['a', 'b']` and prefix `'$'`,
+ * produces `{ $a: EncryptedString; $b: EncryptedString; c: boolean }`.
+ *
+ * @template T - The original object type.
+ * @template F - Union of field names to encrypt.
+ * @template Prefix - The string prefix for encrypted field names.
+ */
+export type SelectivelyEncryptedObject<T, F extends keyof T, Prefix extends string = '$'> = Omit<T, F> & {
+    [K in F as `${Prefix}${string & K}`]: EncryptedString;
+};
+/**
+ * Instance that can encrypt/decrypt specific fields on an object.
+ *
+ * @template T - The original object type.
+ * @template F - Union of field names to encrypt.
+ */
+export interface SelectiveFieldEncryptor<T, F extends keyof T> {
+    /**
+     * Encrypts specified fields, producing an object with prefixed encrypted keys.
+     *
+     * Original field keys are removed and replaced with `${prefix}${fieldName}` keys
+     * whose values are encrypted strings.
+     */
+    encrypt(input: T): SelectivelyEncryptedObject<T, F>;
+    /**
+     * Decrypts prefixed encrypted keys back to the original field names and values.
+     *
+     * Prefixed keys are removed and replaced with the original field keys. If a prefixed
+     * key is missing, the field is skipped (it wasn't present in the original).
+     */
+    decrypt(input: SelectivelyEncryptedObject<T, F>): T;
+}
+/**
+ * Creates a selective field encryptor that encrypts/decrypts specific fields on an object.
+ *
+ * Each encrypted field's value is JSON.stringified before encryption and JSON.parsed after
+ * decryption, so fields can hold any JSON-serializable value (not just strings).
+ *
+ * @example
+ * ```ts
+ * const encryptor = selectiveFieldEncryptor({
+ *   provider: myEncryptionProvider,
+ *   fields: ['client_secret'] as const
+ * });
+ *
+ * const encrypted = encryptor.encrypt({ client_id: 'abc', client_secret: 's3cret' });
+ * // encrypted => { client_id: 'abc', $client_secret: '<ciphertext>' }
+ *
+ * const decrypted = encryptor.decrypt(encrypted);
+ * // decrypted => { client_id: 'abc', client_secret: 's3cret' }
+ * ```
+ *
+ * @param config - Encryption configuration specifying provider, fields, and optional prefix.
+ * @returns A selective field encryptor instance.
+ */
+export declare function selectiveFieldEncryptor<T extends object, F extends keyof T>(config: SelectiveFieldEncryptionConfig<T, F>): SelectiveFieldEncryptor<T, F>;

package/src/lib/encryption/index.d.ts

@@ -0,0 +1 @@
+export * from './encryption.object';

package/src/lib/file/index.d.ts

@@ -1,2 +1,3 @@
 export * from './xml';
 export * from './file';
+export * from './pdf';

package/src/lib/index.d.ts

@@ -33,3 +33,4 @@ export * from './page';
 export * from './path';
 export * from './sort';
 export * from './type';
+export * from './encryption';

package/src/lib/number/encoded.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A number encoded as a radix-36 string using digits 0-9 and letters a-z.
+ *
+ * Radix-36 encoding produces compact string representations of numbers,
+ * useful for URL-safe identifiers and short codes.
+ *
+ * @example
+ * ```ts
+ * const encoded: Radix36EncodedNumber = 'z'; // represents 35
+ * const largeEncoded: Radix36EncodedNumber = '2s'; // represents 100
+ * ```
+ */
+export type Radix36EncodedNumber = string;
+/**
+ * Encodes a number as a radix-36 string.
+ *
+ * Uses digits 0-9 and lowercase letters a-z, producing compact representations
+ * that are useful for URL-safe identifiers and short codes.
+ *
+ * @param number - The number to encode. Should be a non-negative integer for consistent results.
+ * @returns The radix-36 encoded string representation.
+ *
+ * @example
+ * ```ts
+ * encodeRadix36Number(0);   // '0'
+ * encodeRadix36Number(35);  // 'z'
+ * encodeRadix36Number(100); // '2s'
+ * ```
+ */
+export declare function encodeRadix36Number(number: number): Radix36EncodedNumber;
+/**
+ * Decodes a radix-36 encoded string back to a number.
+ *
+ * Parses a string containing digits 0-9 and letters a-z (case-insensitive)
+ * as a base-36 number.
+ *
+ * @param encoded - The radix-36 encoded string to decode.
+ * @returns The decoded numeric value. Returns `NaN` if the input is not a valid radix-36 string.
+ *
+ * @example
+ * ```ts
+ * decodeRadix36Number('0');  // 0
+ * decodeRadix36Number('z');  // 35
+ * decodeRadix36Number('2s'); // 100
+ * ```
+ */
+export declare function decodeRadix36Number(encoded: Radix36EncodedNumber): number;
+/**
+ * A string containing only hexadecimal characters (0-9, a-f or A-F).
+ */
+export type HexString = string;
+/**
+ * Pattern that matches strings containing only hexadecimal characters (0-9, a-f, A-F).
+ */
+export declare const HEX_PATTERN: RegExp;
+/**
+ * Checks whether the input string contains only valid hexadecimal characters.
+ *
+ * @example
+ * ```ts
+ * isHex('a1b2c3'); // true
+ * isHex('FF00AA'); // true
+ * isHex('hello');  // false
+ * isHex('');       // false
+ * ```
+ *
+ * @param value - The string to check.
+ * @returns True if the string is non-empty and contains only hex characters.
+ */
+export declare function isHex(value: string): value is HexString;

package/src/lib/number/index.d.ts

@@ -7,3 +7,4 @@ export * from './random';
 export * from './round';
 export * from './sort';
 export * from './transform';
+export * from './encoded';

package/src/lib/object/object.d.ts

@@ -5,6 +5,10 @@ import { type KeyAsString } from '../type';
  * Any valid Plain-old Javascript Object key.
  */
 export type POJOKey = PrimativeKey | symbol;
+/**
+ * This is an object that can be serialized to JSON and back and be equivalent.
+ */
+export type JsonSerializableObject = Record<PrimativeKey, any>;
 /**
  * String key of an object.
  */

package/src/lib/string/string.d.ts

@@ -9,6 +9,12 @@ export type MapStringFunction<T> = MapFunction<string, T>;
  * Reads a string from the input value.
  */
 export type ReadStringFunction<T, S extends string = string> = MapFunction<T, S>;
+/**
+ * Represents a string that is made up of values separated by a delimiter.
+ *
+ * Optional generic typing exists for communicating what values are separated within the string.
+ */
+export type SeparatedString<T = unknown> = string;
 /**
  * Represents a string that is made up of comma-separated values.
  *
@@ -16,7 +22,7 @@ export type ReadStringFunction<T, S extends string = string> = MapFunction<T, S>
  *
  * I.E. 0,1,2
  */
-export type CommaSeparatedString<T = unknown> = string;
+export type CommaSeparatedString<T = unknown> = SeparatedString<T>;
 /**
  * Represents a string that is made up of space-separated values.
  *
@@ -24,20 +30,15 @@ export type CommaSeparatedString<T = unknown> = string;
  *
  * I.E. 0 1 2
  */
-export type SpaceSeparatedString<T = unknown> = string;
+export type SpaceSeparatedString<T = unknown> = SeparatedString<T>;
 /**
  * Default comma joiner character used by comma-related string functions.
  */
 export declare const COMMA_JOINER = ",";
 /**
- * Converts a string to its lowercase equivalent for case-insensitive comparison.
- *
- * @param input - string to convert to lowercase
- * @returns the lowercased string, or undefined if the input is undefined
+ * Default space joiner character used by space-related string functions.
  */
-export declare function caseInsensitiveString(input: string): string;
-export declare function caseInsensitiveString(input: undefined): undefined;
-export declare function caseInsensitiveString(input: Maybe<string>): Maybe<string>;
+export declare const SPACE_JOINER = " ";
 /**
  * Joins an array of strings into a single string. Trims and omits empty values.
  *
@@ -49,30 +50,137 @@ export declare function caseInsensitiveString(input: Maybe<string>): Maybe<strin
 export declare function joinStrings(input: MaybeNot, joiner?: string, trim?: boolean): MaybeNot;
 export declare function joinStrings(input: ArrayOrValue<Maybe<string>>, joiner?: string, trim?: boolean): string;
 /**
- * Joins an array of strings into a single string using commas. Does not trim empty values by default.
+ * Splits a string like {@link String.prototype.split}, but joins overflow segments back together
+ * instead of discarding them. Useful when you only want to split on the first N-1 occurrences.
  *
- * @param input string or array of strings
- * @param trim whether or not to trim the strings before joining. Defaults to false.
- * @returns joined string, or null/undefined if the input is null/undefined
+ * @param input - string to split
+ * @param separator - delimiter to split on
+ * @param limit - maximum number of resulting segments; overflow segments are rejoined with the separator
+ * @returns array of string segments, with length at most equal to limit
  */
-export declare function joinStringsWithCommas(input: MaybeNot): MaybeNot;
-export declare function joinStringsWithCommas(input: ArrayOrValue<Maybe<string>>): string;
+export declare function splitJoinRemainder(input: string, separator: string, limit: number): string[];
 /**
- * Splits a comma-separated string into an array of strings.
+ * A callable instance that joins arrays of strings using a configured delimiter.
  *
- * @param input string to split
- * @param mapFn function to map each split string to a value
- * @returns array of strings
+ * Can be called directly as a function or accessed for its configuration properties.
+ *
+ * @example
+ * ```ts
+ * const join = joinStringsInstance({ joiner: ',' });
+ * join(['a', 'b', 'c']); // 'a,b,c'
+ * join.joiner; // ','
+ * ```
  */
-export declare function splitCommaSeparatedString(input: CommaSeparatedString<string>): string[];
-export declare function splitCommaSeparatedString<T = unknown>(input: CommaSeparatedString<T>, mapFn: MapStringFunction<T>): T[];
+export interface JoinStringsInstance<T extends string = string> {
+    readonly joiner: string;
+    readonly trimByDefault: boolean;
+    (input: MaybeNot): MaybeNot;
+    (input: ArrayOrValue<Maybe<string>>): T;
+    (input: Maybe<ArrayOrValue<Maybe<string>>>, trim?: boolean): Maybe<T>;
+}
 /**
- * Splits a comma-separated string into a Set of unique trimmed string values.
+ * Configuration for creating a {@link JoinStringsInstance}.
+ */
+export interface JoinStringsInstanceConfig {
+    /**
+     * The delimiter character to use for splitting and joining.
+     */
+    readonly joiner: string;
+    /**
+     * Whether or not to trim values before joining.
+     *
+     * Defaults to false.
+     */
+    readonly trimByDefault?: boolean;
+}
+/**
+ * Creates a {@link JoinStringsInstance} that joins arrays of strings using the configured delimiter.
  *
- * @param input - comma-separated string to split, or null/undefined
- * @returns a Set of unique string values; empty Set if input is null/undefined
+ * @example
+ * ```ts
+ * const joinWithPipe = joinStringsInstance({ joiner: '|' });
+ * joinWithPipe(['a', 'b']); // 'a|b'
+ * joinWithPipe(null); // null
+ * ```
+ *
+ * @param config - configuration for the delimiter and default trim behavior
+ * @returns a new callable {@link JoinStringsInstance}
  */
-export declare function splitCommaSeparatedStringToSet(input: Maybe<CommaSeparatedString>): Set<string>;
+export declare function joinStringsInstance<T extends string = string>(config: JoinStringsInstanceConfig): JoinStringsInstance<T>;
+/**
+ * An instance that provides split and join operations for strings using a configured delimiter.
+ *
+ * @example
+ * ```ts
+ * const instance = stringSplitJoinInstance({ joiner: ',' });
+ * instance.joinStrings(['a', 'b', 'c']); // 'a,b,c'
+ * instance.splitStrings('a,b,c'); // ['a', 'b', 'c']
+ * instance.splitStringsToSet('a,b,a'); // Set {'a', 'b'}
+ * ```
+ */
+export interface StringSplitJoinInstance<T extends string = string> extends Pick<JoinStringsInstance<T>, 'joiner' | 'trimByDefault'> {
+    /**
+     * Joins an array of strings into a single delimited string. Filters out null/undefined values.
+     */
+    joinStrings(input: MaybeNot): MaybeNot;
+    joinStrings(input: ArrayOrValue<Maybe<string>>): T;
+    joinStrings(input: Maybe<ArrayOrValue<Maybe<string>>>, trim?: boolean): Maybe<T>;
+    /**
+     * Splits a delimited string into an array of trimmed strings, optionally mapping each value.
+     */
+    splitStrings(input: T): string[];
+    splitStrings<O>(input: T, mapFn: MapStringFunction<O>): O[];
+    /**
+     * Splits a delimited string into a Set of unique trimmed string values.
+     *
+     * Returns an empty set if the input is null/undefined.
+     */
+    splitStringsToSet(input: Maybe<T>): Set<string>;
+    /**
+     * Splits the input string by the configured delimiter, joining overflow segments back together
+     * instead of discarding them. Useful when you only want to split on the first N-1 occurrences.
+     *
+     * @param input - string to split
+     * @param limit - maximum number of resulting segments; overflow segments are rejoined with the delimiter
+     * @returns array of string segments, with length at most equal to limit
+     */
+    splitJoinRemainder(input: string, limit: number): string[];
+}
+/**
+ * Configuration for creating a {@link StringSplitJoinInstance}.
+ */
+export type StringSplitJoinInstanceConfig = JoinStringsInstanceConfig;
+/**
+ * Creates a {@link StringSplitJoinInstance} that splits and joins strings using the configured delimiter.
+ *
+ * @example
+ * ```ts
+ * const pipeSplitJoin = stringSplitJoinInstance({ joiner: '|' });
+ * pipeSplitJoin.joinStrings(['a', 'b']); // 'a|b'
+ * pipeSplitJoin.splitStrings('a|b'); // ['a', 'b']
+ * ```
+ *
+ * @param config - configuration for the delimiter and default trim behavior
+ * @returns a new {@link StringSplitJoinInstance}
+ */
+export declare function stringSplitJoinInstance<T extends string = string>(config: StringSplitJoinInstanceConfig): StringSplitJoinInstance<T>;
+/**
+ * Global {@link StringSplitJoinInstance} that uses commas as the delimiter.
+ */
+export declare const COMMA_STRING_SPLIT_JOIN: StringSplitJoinInstance<CommaSeparatedString>;
+/**
+ * Global {@link StringSplitJoinInstance} that uses spaces as the delimiter, with trimming enabled by default.
+ */
+export declare const SPACE_STRING_SPLIT_JOIN: StringSplitJoinInstance<SpaceSeparatedString>;
+/**
+ * Converts a string to its lowercase equivalent for case-insensitive comparison.
+ *
+ * @param input - string to convert to lowercase
+ * @returns the lowercased string, or undefined if the input is undefined
+ */
+export declare function caseInsensitiveString(input: string): string;
+export declare function caseInsensitiveString(input: undefined): undefined;
+export declare function caseInsensitiveString(input: Maybe<string>): Maybe<string>;
 /**
  * Adds a plus prefix to the input value and converts it to a string. If the value is negative or 0, no prefix is added.
  *
@@ -97,24 +205,10 @@ export declare function capitalizeFirstLetter(value: string): string;
  * @returns the input string with its first character lowercased
  */
 export declare function lowercaseFirstLetter(value: string): string;
-/**
- * Splits a string like {@link String.prototype.split}, but joins overflow segments back together
- * instead of discarding them. Useful when you only want to split on the first N-1 occurrences.
- *
- * @param input - string to split
- * @param separator - delimiter to split on
- * @param limit - maximum number of resulting segments; overflow segments are rejoined with the separator
- * @returns array of string segments, with length at most equal to limit
- */
-export declare function splitJoinRemainder(input: string, separator: string, limit: number): string[];
 /**
  * A tuple of [firstName, lastName] where lastName may be undefined if the input has no space.
  */
 export type FirstNameLastNameTuple = [string, string | undefined];
-/**
- * Default space joiner character used by space-related string functions.
- */
-export declare const SPACE_JOINER = " ";
 /**
  * Splits the input string into a first name and last name tuple using a space as the delimiter.
  * If the name contains more than one space, the remainder is treated as the last name.
@@ -123,14 +217,6 @@ export declare const SPACE_JOINER = " ";
  * @returns a tuple of [firstName, lastName], where lastName includes all text after the first space
  */
 export declare function splitJoinNameString(input: string): FirstNameLastNameTuple;
-/**
- * Joins one or more strings together with spaces. Extra spaces are trimmed from the values.
- *
- * @param input string or array of strings
- * @returns joined string, or null/undefined if the input is null/undefined
- */
-export declare function joinStringsWithSpaces(input: MaybeNot): MaybeNot;
-export declare function joinStringsWithSpaces(input: ArrayOrValue<Maybe<string>>): string;
 /**
  * Creates a string that repeats the given string a specified number of times.
  *
@@ -200,3 +286,52 @@ export declare function flattenWhitespace(input: string): string;
  * @returns the string with simplified whitespace and newlines
  */
 export declare function simplifyWhitespace(input: string): string;
+/**
+ * Joins an array of strings into a single string using commas. Does not trim empty values by default.
+ *
+ * Delegates to {@link COMMA_STRING_SPLIT_JOIN}.
+ *
+ * @param input string or array of strings
+ * @param trim whether or not to trim the strings before joining. Defaults to false.
+ * @returns joined string, or null/undefined if the input is null/undefined
+ */
+export declare const joinStringsWithCommas: {
+    (input: MaybeNot): MaybeNot;
+    (input: ArrayOrValue<Maybe<string>>): string;
+    (input: Maybe<ArrayOrValue<Maybe<string>>>, trim?: boolean): Maybe<string>;
+};
+/**
+ * Splits a comma-separated string into an array of strings.
+ *
+ * Delegates to {@link COMMA_STRING_SPLIT_JOIN}.
+ *
+ * @param input string to split
+ * @param mapFn function to map each split string to a value
+ * @returns array of strings
+ */
+export declare const splitCommaSeparatedString: {
+    (input: string): string[];
+    <O>(input: string, mapFn: MapStringFunction<O>): O[];
+};
+/**
+ * Splits a comma-separated string into a Set of unique trimmed string values.
+ *
+ * Delegates to {@link COMMA_STRING_SPLIT_JOIN}.
+ *
+ * @param input - comma-separated string to split, or null/undefined
+ * @returns a Set of unique string values; empty Set if input is null/undefined
+ */
+export declare const splitCommaSeparatedStringToSet: (input: Maybe<string>) => Set<string>;
+/**
+ * Joins one or more strings together with spaces. Extra spaces are trimmed from the values.
+ *
+ * Delegates to {@link SPACE_STRING_SPLIT_JOIN}.
+ *
+ * @param input string or array of strings
+ * @returns joined string, or null/undefined if the input is null/undefined
+ */
+export declare const joinStringsWithSpaces: {
+    (input: MaybeNot): MaybeNot;
+    (input: ArrayOrValue<Maybe<string>>): string;
+    (input: Maybe<ArrayOrValue<Maybe<string>>>, trim?: boolean): Maybe<string>;
+};

package/src/lib/string/url.d.ts

@@ -155,6 +155,10 @@ export interface WebsiteUrlDetails {
     readonly hasHttpPrefix: boolean;
     /** Whether the input contains a website domain. */
     readonly hasWebsiteDomain: boolean;
+    /** Whether the input contains a port number. */
+    readonly hasPortNumber: boolean;
+    /** The port number, or `undefined` if none is present. */
+    readonly portNumber: PortNumber | undefined;
     /** The domain and path split pair. */
     readonly splitPair: WebsiteDomainAndPathPair;
     /** The extracted domain. */
@@ -183,7 +187,7 @@ export type WebsiteUrlWithPrefix = string;
  * @param input - The string to check.
  * @returns Whether the input is a website URL with an HTTP prefix.
  */
-export declare function isWebsiteUrlWithPrefix(input: string): input is WebsiteUrl;
+export declare function isWebsiteUrlWithPrefix(input: string): input is WebsiteUrlWithPrefix;
 /**
  * A "standard" internet accessible website url with a tld (.com/.net/etc) and optionally has the http/https protocol, but no other protocol.
  *

package/src/lib/value/label.d.ts

@@ -29,3 +29,9 @@ export interface LabeledValue<T> extends LabelRef {
  * ```
  */
 export declare function labeledValueMap<V extends LabeledValue<T>, T extends PrimativeKey>(values: V[]): Map<T, V>;
+/**
+ * Pairs a value with a human-readable label and an optional description.
+ */
+export interface LabeledValueWithDescription<T> extends LabeledValue<T> {
+    description?: string;
+}

package/test/index.cjs.js

@@ -377,7 +377,7 @@ function _ts_generator$2(thisArg, body) {
  * @param config - fixture, test builder, and instance lifecycle functions
  */ function useTestContextFixture(config) {
     var buildTests = config.buildTests, fixture = config.fixture, initInstance = config.initInstance, destroyInstance = config.destroyInstance;
-    var clearInstance;
+    var clearInstance = null;
     var instance;
     // Create an instance
     beforeEach(function() {
@@ -433,7 +433,7 @@ function _ts_generator$2(thisArg, body) {
                         if (fixture.instance != null) {
                             console.warn('Expected instance to be set on fixture for cleanup but was set to something else.');
                         }
-                        if (!destroyInstance) return [
+                        if (!(destroyInstance && instance != null)) return [
                             3,
                             4
                         ];

package/test/index.esm.js

@@ -375,7 +375,7 @@ function _ts_generator$2(thisArg, body) {
  * @param config - fixture, test builder, and instance lifecycle functions
  */ function useTestContextFixture(config) {
     var buildTests = config.buildTests, fixture = config.fixture, initInstance = config.initInstance, destroyInstance = config.destroyInstance;
-    var clearInstance;
+    var clearInstance = null;
     var instance;
     // Create an instance
     beforeEach(function() {
@@ -431,7 +431,7 @@ function _ts_generator$2(thisArg, body) {
                         if (fixture.instance != null) {
                             console.warn('Expected instance to be set on fixture for cleanup but was set to something else.');
                         }
-                        if (!destroyInstance) return [
+                        if (!(destroyInstance && instance != null)) return [
                             3,
                             4
                         ];

package/test/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/test",
-  "version": "13.2.2",
+  "version": "13.3.1",
   "peerDependencies": {
-    "@dereekb/util": "13.2.2",
+    "@dereekb/util": "13.3.1",
     "make-error": "^1.3.0"
   },
   "exports": {