@ls-stack/utils 3.39.0 → 3.41.0

package/dist/typingTestUtils.d.cts

@@ -3,36 +3,77 @@ type TestTypeNotEqual<X, Y> = true extends TestTypeIsEqual<X, Y> ? false : true;
 declare function test(title: string, func: () => any): void;
 declare function describe(title: string, func: () => any): void;
 /**
- * Helper function for type testing that ensures a type extends `true`.
- * Used in combination with `TestTypeIsEqual` to verify type equality at compile time.
+ * Helper function for type testing that ensures a type extends `true`. Used in
+ * combination with `TestTypeIsEqual` to verify type equality at compile time.
  *
+ * @deprecated Use {@link expectTypesAreEqual} or {@link expectTypesAreNotEqual}
+ *   instead
  * @example
- * expectType<TestTypeIsEqual<string, string>>(); // OK
- * expectType<TestTypeIsEqual<string, number>>(); // Type error
+ *   expectType<TestTypeIsEqual<string, string>>(); // OK
+ *   expectType<TestTypeIsEqual<string, number>>(); // Type error
  *
  * @template T Type that must extend `true`
  * @returns An empty object cast to type T
  */
 declare function expectType<T extends true>(): T;
 /**
- * Helper function for type testing that compares two types and expects a specific result.
- * This function allows for more explicit type equality assertions with a descriptive result.
+ * Helper function for type testing that compares two types and expects a
+ * specific result. This function allows for more explicit type equality
+ * assertions with a descriptive result.
+ *
+ * @deprecated Use {@link expectTypesAreEqual} or {@link expectTypesAreNotEqual}
+ *   instead
+ * @example
+ *   expectTypesAre<string, string>('equal'); // OK
+ *   expectTypesAre<string, number>('notEqual'); // OK
+ *   expectTypesAre<string, string>('notEqual'); // Type error
+ *
+ * @template X First type to compare
+ * @template Y Second type to compare
+ * @param result Expected comparison result: 'equal' if types are equal,
+ *   'notEqual' if they differ
+ */
+declare function expectTypesAre<X, Y>(result: TestTypeIsEqual<X, Y> extends true ? 'equal' : 'notEqual'): void;
+/**
+ * Helper function for type testing that ensures two types are equal. If types
+ * are not equal, it will show a compile-time error with details about the
+ * mismatch.
+ *
+ * @example
+ *   expectTypesAreEqual<string, string>(); // OK
+ *   expectTypesAreEqual<string, number>(); // Compile error with details
  *
  * @template X First type to compare
  * @template Y Second type to compare
- * @param result Expected comparison result: 'equal' if types are equal, 'notEqual' if they differ
+ * @param result Optional error parameter that appears only when types don't
+ *   match
+ */
+declare function expectTypesAreEqual<X, Y>(...result: TestTypeIsEqual<X, Y> extends true ? [] : [
+    error: 'type assertion failed, types should be equal but',
+    typeOnLeft: X,
+    _: 'is not equal to',
+    typeOnRight: Y
+]): void;
+/**
+ * Helper function for type testing that ensures two types are not equal. If
+ * types are equal, it will show a compile-time error.
  *
  * @example
- * expectTypesAre<string, string>('equal'); // OK
- * expectTypesAre<string, number>('notEqual'); // OK
- * expectTypesAre<string, string>('notEqual'); // Type error
+ *   expectTypesAreNotEqual<string, number>(); // OK
+ *   expectTypesAreNotEqual<string, string>(); // Compile error
+ *
+ * @template X First type to compare
+ * @template Y Second type to compare
+ * @param result Optional error parameter that appears only when types match
  */
-declare function expectTypesAre<X, Y>(result: TestTypeIsEqual<X, Y> extends true ? 'equal' : 'notEqual'): void;
+declare function expectTypesAreNotEqual<X, Y>(...result: TestTypeIsEqual<X, Y> extends false ? [] : ['error: type assertion failed, types should be NOT equal']): void;
 declare const typingTest: {
     test: typeof test;
     describe: typeof describe;
     expectType: typeof expectType;
     expectTypesAre: typeof expectTypesAre;
+    expectTypesAreEqual: typeof expectTypesAreEqual;
+    expectTypesAreNotEqual: typeof expectTypesAreNotEqual;
 };
 
 export { type TestTypeIsEqual, type TestTypeNotEqual, typingTest };

package/dist/typingTestUtils.d.ts

@@ -3,36 +3,77 @@ type TestTypeNotEqual<X, Y> = true extends TestTypeIsEqual<X, Y> ? false : true;
 declare function test(title: string, func: () => any): void;
 declare function describe(title: string, func: () => any): void;
 /**
- * Helper function for type testing that ensures a type extends `true`.
- * Used in combination with `TestTypeIsEqual` to verify type equality at compile time.
+ * Helper function for type testing that ensures a type extends `true`. Used in
+ * combination with `TestTypeIsEqual` to verify type equality at compile time.
  *
+ * @deprecated Use {@link expectTypesAreEqual} or {@link expectTypesAreNotEqual}
+ *   instead
  * @example
- * expectType<TestTypeIsEqual<string, string>>(); // OK
- * expectType<TestTypeIsEqual<string, number>>(); // Type error
+ *   expectType<TestTypeIsEqual<string, string>>(); // OK
+ *   expectType<TestTypeIsEqual<string, number>>(); // Type error
  *
  * @template T Type that must extend `true`
  * @returns An empty object cast to type T
  */
 declare function expectType<T extends true>(): T;
 /**
- * Helper function for type testing that compares two types and expects a specific result.
- * This function allows for more explicit type equality assertions with a descriptive result.
+ * Helper function for type testing that compares two types and expects a
+ * specific result. This function allows for more explicit type equality
+ * assertions with a descriptive result.
+ *
+ * @deprecated Use {@link expectTypesAreEqual} or {@link expectTypesAreNotEqual}
+ *   instead
+ * @example
+ *   expectTypesAre<string, string>('equal'); // OK
+ *   expectTypesAre<string, number>('notEqual'); // OK
+ *   expectTypesAre<string, string>('notEqual'); // Type error
+ *
+ * @template X First type to compare
+ * @template Y Second type to compare
+ * @param result Expected comparison result: 'equal' if types are equal,
+ *   'notEqual' if they differ
+ */
+declare function expectTypesAre<X, Y>(result: TestTypeIsEqual<X, Y> extends true ? 'equal' : 'notEqual'): void;
+/**
+ * Helper function for type testing that ensures two types are equal. If types
+ * are not equal, it will show a compile-time error with details about the
+ * mismatch.
+ *
+ * @example
+ *   expectTypesAreEqual<string, string>(); // OK
+ *   expectTypesAreEqual<string, number>(); // Compile error with details
  *
  * @template X First type to compare
  * @template Y Second type to compare
- * @param result Expected comparison result: 'equal' if types are equal, 'notEqual' if they differ
+ * @param result Optional error parameter that appears only when types don't
+ *   match
+ */
+declare function expectTypesAreEqual<X, Y>(...result: TestTypeIsEqual<X, Y> extends true ? [] : [
+    error: 'type assertion failed, types should be equal but',
+    typeOnLeft: X,
+    _: 'is not equal to',
+    typeOnRight: Y
+]): void;
+/**
+ * Helper function for type testing that ensures two types are not equal. If
+ * types are equal, it will show a compile-time error.
  *
  * @example
- * expectTypesAre<string, string>('equal'); // OK
- * expectTypesAre<string, number>('notEqual'); // OK
- * expectTypesAre<string, string>('notEqual'); // Type error
+ *   expectTypesAreNotEqual<string, number>(); // OK
+ *   expectTypesAreNotEqual<string, string>(); // Compile error
+ *
+ * @template X First type to compare
+ * @template Y Second type to compare
+ * @param result Optional error parameter that appears only when types match
  */
-declare function expectTypesAre<X, Y>(result: TestTypeIsEqual<X, Y> extends true ? 'equal' : 'notEqual'): void;
+declare function expectTypesAreNotEqual<X, Y>(...result: TestTypeIsEqual<X, Y> extends false ? [] : ['error: type assertion failed, types should be NOT equal']): void;
 declare const typingTest: {
     test: typeof test;
     describe: typeof describe;
     expectType: typeof expectType;
     expectTypesAre: typeof expectTypesAre;
+    expectTypesAreEqual: typeof expectTypesAreEqual;
+    expectTypesAreNotEqual: typeof expectTypesAreNotEqual;
 };
 
 export { type TestTypeIsEqual, type TestTypeNotEqual, typingTest };

package/dist/typingTestUtils.js

@@ -10,11 +10,17 @@ function expectType() {
 }
 function expectTypesAre(result) {
 }
+function expectTypesAreEqual(...result) {
+}
+function expectTypesAreNotEqual(...result) {
+}
 var typingTest = {
   test,
   describe,
   expectType,
-  expectTypesAre
+  expectTypesAre,
+  expectTypesAreEqual,
+  expectTypesAreNotEqual
 };
 export {
   typingTest

package/dist/typingUtils.d.cts

@@ -6,7 +6,10 @@ type PartialRecord<K extends keyof any, T> = {
 type NonPartial<T> = {
     [K in keyof Required<T>]: T[K];
 };
-/** @deprecated Use `ObjKeysWithValuesOfType` from `@ls-stack/utils/typeUtils` instead */
+/**
+ * @deprecated Use `ObjKeysWithValuesOfType` from `@ls-stack/utils/typeUtils`
+ *   instead
+ */
 type ObjKeysWithValuesOfType<Obj extends Record<PropertyKey, unknown>, ValueType> = {
     [K in keyof Obj]: Obj[K] extends ValueType ? K : never;
 }[keyof Obj];

package/dist/typingUtils.d.ts

@@ -6,7 +6,10 @@ type PartialRecord<K extends keyof any, T> = {
 type NonPartial<T> = {
     [K in keyof Required<T>]: T[K];
 };
-/** @deprecated Use `ObjKeysWithValuesOfType` from `@ls-stack/utils/typeUtils` instead */
+/**
+ * @deprecated Use `ObjKeysWithValuesOfType` from `@ls-stack/utils/typeUtils`
+ *   instead
+ */
 type ObjKeysWithValuesOfType<Obj extends Record<PropertyKey, unknown>, ValueType> = {
     [K in keyof Obj]: Obj[K] extends ValueType ? K : never;
 }[keyof Obj];

package/dist/yamlStringify.cjs

@@ -88,14 +88,12 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
       const entries = Object.entries(value).filter(
         ([, val]) => val !== void 0 || showUndefined
       );
-      const isSimpleObject = entries.every(
-        ([, val]) => {
-          if (typeof val === "string") {
-            return !val.includes("'") && !val.includes('"') && !val.includes("\\");
-          }
-          return typeof val === "number" || typeof val === "boolean" || val === null || val === void 0;
+      const isSimpleObject = entries.every(([, val]) => {
+        if (typeof val === "string") {
+          return !val.includes("'") && !val.includes('"') && !val.includes("\\");
         }
-      );
+        return typeof val === "number" || typeof val === "boolean" || val === null || val === void 0;
+      });
       const shouldCollapse = isArrayItem ? entries.length > 1 : entries.length > 0;
       if (isSimpleObject && shouldCollapse) {
         let line = "{ ";
@@ -148,7 +146,9 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
         false
       );
       const willBeCollapsed = isObject(objVal) && (Object.keys(objVal).length === 0 || collapseObjects && depth + 1 > 0 && (() => {
-        const filteredEntries = Object.entries(objVal).filter(([, val]) => val !== void 0 || showUndefined);
+        const filteredEntries = Object.entries(objVal).filter(
+          ([, val]) => val !== void 0 || showUndefined
+        );
         const shouldCollapseThis = isArrayItem ? filteredEntries.length > 1 : filteredEntries.length > 0;
         return shouldCollapseThis && filteredEntries.every(([, val]) => {
           if (typeof val === "string") {
@@ -158,7 +158,9 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
         });
       })());
       const prevWasCollapsed = prevValue && isObject(prevValue) && (Object.keys(prevValue).length === 0 || collapseObjects && depth + 1 > 0 && (() => {
-        const filteredEntries = Object.entries(prevValue).filter(([, val]) => val !== void 0 || showUndefined);
+        const filteredEntries = Object.entries(prevValue).filter(
+          ([, val]) => val !== void 0 || showUndefined
+        );
         const shouldCollapseThis = isArrayItem ? filteredEntries.length > 1 : filteredEntries.length > 0;
         return shouldCollapseThis && filteredEntries.every(([, val]) => {
           if (typeof val === "string") {

package/dist/yamlStringify.js

@@ -1,8 +1,8 @@
 import {
   yamlStringify
-} from "./chunk-ADM37GSC.js";
+} from "./chunk-7L4KCZJJ.js";
 import "./chunk-IATIXMCE.js";
-import "./chunk-KW55OTUG.js";
+import "./chunk-B3KFV2MH.js";
 import "./chunk-JF2MDHOJ.js";
 export {
   yamlStringify

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Universal TypeScript utilities for browser and Node.js",
-  "version": "3.39.0",
+  "version": "3.41.0",
   "license": "MIT",
   "files": [
     "dist",
@@ -212,6 +212,10 @@
       "import": "./dist/typingTestUtils.js",
       "require": "./dist/typingTestUtils.cjs"
     },
+    "./typingTestUtils.typesTest": {
+      "import": "./dist/typingTestUtils.typesTest.js",
+      "require": "./dist/typingTestUtils.typesTest.cjs"
+    },
     "./typingUtils": {
       "import": "./dist/typingUtils.js",
       "require": "./dist/typingUtils.cjs"
@@ -252,7 +256,7 @@
   },
   "dependencies": {
     "evtmitter": "^1.0.2",
-    "t-result": "^0.3.0"
+    "t-result": "^0.6.1"
   },
   "scripts": {
     "test:ui": "vitest --ui",

package/docs/README.md

@@ -1,72 +0,0 @@
-**@ls-stack/utils**
-
-***
-
-# @ls-stack/utils
-
-Generic TypeScript utilities for modern JavaScript/TypeScript projects.
-
-## Installation
-
-```bash
-npm install @ls-stack/utils
-# or
-pnpm add @ls-stack/utils
-# or
-yarn add @ls-stack/utils
-```
-
-## Usage
-
-Import specific utilities from their modules:
-
-```typescript
-import { createAsyncQueue } from '@ls-stack/utils/asyncQueue';
-import { deepEqual } from '@ls-stack/utils/deepEqual';
-import { debounce } from '@ls-stack/utils/debounce';
-```
-
-## Documentation
-
-For a complete list of available utilities and their APIs, see the auto-generated documentation in the [`docs/`](docs/) folder. Start with the [modules overview](_media/modules.md) to explore all available utilities.
-
-### Generating Documentation
-
-To regenerate the documentation after making changes:
-
-```bash
-pnpm docs
-```
-
-For continuous updates during development:
-
-```bash
-pnpm docs:watch
-```
-
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Run tests
-pnpm test
-
-# Run tests with UI
-pnpm test:ui
-
-# Build the library
-pnpm build
-
-# Lint code
-pnpm lint
-```
-
-## License
-
-MIT
-
-## Repository
-
-[github:lucasols/utils](https://github.com/lucasols/utils)

package/docs/_media/modules.md

@@ -1,58 +0,0 @@
-[**@ls-stack/utils**](README.md)
-
-***
-
-# @ls-stack/utils
-
-## Modules
-
-- [arrayUtils](arrayUtils/README.md)
-- [assertions](assertions/README.md)
-- [asyncQueue](asyncQueue/README.md)
-- [awaitDebounce](awaitDebounce.md)
-- [cache](cache/README.md)
-- [castValues](castValues.md)
-- [concurrentCalls](concurrentCalls/README.md)
-- [consoleFmt](consoleFmt.md)
-- [conversions](conversions.md)
-- [createThrottleController](createThrottleController/README.md)
-- [debounce](debounce.md)
-- [dedent](dedent/README.md)
-- [deepEqual](deepEqual.md)
-- [enhancedMap](enhancedMap.md)
-- [exhaustiveMatch](exhaustiveMatch/README.md)
-- [filterObjectOrArrayKeys](filterObjectOrArrayKeys.md)
-- [getAutoIncrementId](getAutoIncrementId.md)
-- [getCompositeKey](getCompositeKey.md)
-- [getValueStableKey](getValueStableKey.md)
-- [hash](hash.md)
-- [interpolate](interpolate/README.md)
-- [keepPrevIfUnchanged](keepPrevIfUnchanged.md)
-- [levenshtein](levenshtein.md)
-- [main](main.md)
-- [mathUtils](mathUtils.md)
-- [mutationUtils](mutationUtils.md)
-- [objUtils](objUtils.md)
-- [parallelAsyncCalls](parallelAsyncCalls/README.md)
-- [promiseUtils](promiseUtils/README.md)
-- [retryOnError](retryOnError/README.md)
-- [runShellCmd](runShellCmd/README.md)
-- [safeJson](safeJson.md)
-- [saferTyping](saferTyping.md)
-- [serializeXML](serializeXML.md)
-- [shallowEqual](shallowEqual.md)
-- [sleep](sleep.md)
-- [stringUtils](stringUtils/README.md)
-- [testUtils](testUtils.md)
-- [throttle](throttle/README.md)
-- [time](time.md)
-- [timers](timers.md)
-- [tsResult](tsResult/README.md)
-- [typedStrings](typedStrings.md)
-- [typeGuards](typeGuards.md)
-- [typeUtils](typeUtils/README.md)
-- [typeUtils.typesTest](typeUtils.typesTest.md)
-- [typingFnUtils](typingFnUtils/README.md)
-- [typingTestUtils](typingTestUtils.md)
-- [typingUtils](typingUtils.md)
-- [yamlStringify](yamlStringify.md)

package/docs/arrayUtils/-internal-.md

@@ -1,179 +0,0 @@
-[**@ls-stack/utils**](../README.md)
-
-***
-
-[@ls-stack/utils](../modules.md) / [arrayUtils](README.md) / \<internal\>
-
-# \<internal\>
-
-## Type Aliases
-
-### ArrayOps\<T\>
-
-```ts
-type ArrayOps<T> = object;
-```
-
-Defined in: [packages/utils/src/arrayUtils.ts:259](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L259)
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-#### Properties
-
-##### filterAndMap()
-
-```ts
-filterAndMap: <R>(mapFilter) => R[];
-```
-
-Defined in: [packages/utils/src/arrayUtils.ts:272](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L272)
-
-Filter and map an array
-
-###### Type Parameters
-
-###### R
-
-`R`
-
-###### Parameters
-
-###### mapFilter
-
-(`item`, `index`) => `false` \| `R`
-
-A function that takes an item and returns a value or `false`
-to reject the item.
-
-###### Returns
-
-`R`[]
-
-###### Example
-
-```ts
-const items = [1, 2, 3];
-
-const enhancedItems = arrayOps(items);
-
-enhancedItems.filterAndMap((item) => item === 2 ? false : item);
-```
-
-##### findAndMap()
-
-```ts
-findAndMap: <R>(predicate) => R | undefined;
-```
-
-Defined in: [packages/utils/src/arrayUtils.ts:275](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L275)
-
-###### Type Parameters
-
-###### R
-
-`R`
-
-###### Parameters
-
-###### predicate
-
-(`value`) => `R` \| `false`
-
-###### Returns
-
-`R` \| `undefined`
-
-##### rejectDuplicates()
-
-```ts
-rejectDuplicates: (getKey) => T[];
-```
-
-Defined in: [packages/utils/src/arrayUtils.ts:274](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L274)
-
-###### Parameters
-
-###### getKey
-
-(`item`) => `unknown`
-
-###### Returns
-
-`T`[]
-
-##### sortBy()
-
-```ts
-sortBy: (sortByValue, props) => T[];
-```
-
-Defined in: [packages/utils/src/arrayUtils.ts:273](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L273)
-
-###### Parameters
-
-###### sortByValue
-
-[`SortByValue`](#sortbyvalue)\<`T`\>
-
-###### props
-
-[`SortByProps`](#sortbyprops)
-
-###### Returns
-
-`T`[]
-
-***
-
-### SortByProps
-
-```ts
-type SortByProps = 
-  | {
-  order?: SortOrder | SortOrder[];
-}
-  | SortOrder
-  | SortOrder[];
-```
-
-Defined in: [packages/utils/src/arrayUtils.ts:48](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L48)
-
-***
-
-### SortByValue()\<T\>
-
-```ts
-type SortByValue<T> = (item) => (number | string)[] | number | string;
-```
-
-Defined in: [packages/utils/src/arrayUtils.ts:46](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L46)
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-#### Parameters
-
-##### item
-
-`T`
-
-#### Returns
-
-(`number` \| `string`)[] \| `number` \| `string`
-
-***
-
-### SortOrder
-
-```ts
-type SortOrder = "desc" | "asc";
-```
-
-Defined in: [packages/utils/src/arrayUtils.ts:44](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L44)