TS-Scribe

A TypeScript utility library tailored for Node.js and Bun development. It provides a rich set of utility functions and advanced types to enhance productivity and code quality.

Installation

npm install ts-scribe

bun add ts-scribe

Functions

Core

• getIn: Safely retrieves a nested value from an object using a path array, with support for Maps and Arrays.
• setIn: Immutably sets a nested value using a path array, creating missing containers as needed (supports Maps and Arrays).
• run: Helper to run a function or block of code in a cleaner way.
• parseBoolean: Parses various values into a boolean.
• parseNumber: Parses various values into a number.
• safeJsonParse: Safely parses a string without throwing.
• safeJsonStringify: Safely stringifies a JSON object without throwing (handles issues like circular references).
• memoize: Caches the results of function calls based on their arguments.

Array

• arrayUnique: Given an array of primitive values, returns a new array with duplicates removed.
• arrayChunk: Splits an array into chunks of a specified size.
• arrayDifference: Returns the difference between two arrays.
• arrayGroupBy: Groups an array of objects by a specified key.
• arrayIntersection: Returns the intersection of two arrays.
• arrayIntersectionDeep: Deep intersection between arrays of objects or values.
• arrayPluck: Extracts a list of property values from an array of objects.
• arrayPowerset: Returns the powerset of an array.
• arrayShuffle: Shuffles an array randomly.
• arrayUniqueBy: Returns an array of unique values based on a specified key.
• toArray: Converts almost anything into an array.
• arrayPartition: Partitions an array into two arrays based on a predicate function.

Async

• asyncForEach: Runs async operations over an array in parallel.
• asyncMap: Similar to asyncForEach but with the behavior of Array.map function.
• debounce: Debounces a function or promise.
• maybe: Maybe monad for null-safe operations.
• retry: Retries a promise a specified number of times.
• sleep: Pauses execution for a specified time.
• waterfall: Chains functions that pass results to each other.
• semaphore: Controls access to a resource with a specified concurrency limit.

List

• SortedList: Maintains a sorted list.
• WeightedList: Selects items based on weight/probability.

Math

• clamp: Clamps a number between min and max.
• greatestCommonDivisor: Finds the GCD of multiple numbers.
• smallestCommonMultiple: Finds the LCM of multiple numbers.

Object

• objectDeepClone: Deeply clones an object.
• objectDeepEquals: Deeply compares two objects or arrays.
• objectDeepFreeze: Deep freezes an object recursively.
• objectFlatten: Flattens an object into dot notation.
• objectPrune: Removes properties with undefined values.
• objectPickKeys: Creates a new object by picking specified keys from the original object.
• objectOmitKeys: Creates a new object by omitting specified keys from the original object.
• objectMask: Recursively masks sensitive properties in objects/arrays based on keys or custom predicates. Handles circular references, deep nesting, and special object types (Date, RegExp, Error, etc.).

Random

• randomBool: Generates a random boolean, optionally biased.
• randomInt: Generates a random integer in a given range.
• randomSample: Randomly samples values from an array.
• randomString: Generates a random string of given length/charset.

String

• toCamelCase: Converts a string to camelCase.
• toDotCase: Converts a string to dot.case.
• toHeaderCase: Converts a string to Header Case.
• toKebabCase: Converts a string to kebab-case.
• toPascalCase: Converts a string to PascalCase.
• toSnakeCase: Converts a string to snake_case.
• truncate: Truncates a string with configurable options.
• slugify: Slugifies a string, converting it into a URL-friendly format with customizable options.

System

• isBrowser: Returns true if running in a browser environment.
• isNode: Returns true if running in Node.js.
• getEnvironment: Returns 'Browser', 'Bun', 'Node', or 'Unknown' depending on the context it's run in.

Typeguards

• isDefined: Checks if a value is not null/undefined/NaN.
• isEmptyObject: Checks if an object has no own properties.
• isEmptyValue: Checks for null, undefined, NaN, empty string/array/object.
• isNumber: Validates numeric values or strings that can be parsed as numbers.
• isString: Validates if a value is a string.

Types

• Primitive: JavaScript primitive types.
• Nullish: Represents null | undefined.
• NonNullish: Excludes null | undefined.
• Mandatory<T>: Removes nullish from all properties of T.
• Nestable<T>: A type that can nest recursively.
• GenericFunction: A generic function type.
• TypeOfString: Valid typeof operator string values.
• TypeOfType<T>: Infers the typeof type string from a value.
• UnionToIntersection<U>: Converts a union to an intersection.
• SmartPartial<T>: Only makes properties optional if their type includes undefined.
• Simplify<T>: Flattens complex types for better readability.
• OverloadUnion<T>: Turns a union of functions into a single overloaded function type.
• DeepReadonly<T>: Deep version of Readonly<T>.
• DeepPartial<T>: Deep version of Partial<T>.
• Serializable: Represents a type that can be serialized to a JSON-compatible format.

Development

• benchmark: Wrap around a function to benchmark it's performance without affecting app behavior.
• traceFunction: Wrap around a function to trace its calls, arguments, return values, and execution time without affecting app behavior.
• createPerfTimer: Create a performance timer to measure execution time of code blocks with lap support.

Credits

• semaphore

License

MIT