@ls-stack/utils 3.17.1 → 3.19.0

package/docs/typingTestUtils.md

@@ -0,0 +1,172 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / typingTestUtils
+
+# typingTestUtils
+
+## Type Aliases
+
+### TestTypeIsEqual\<X, Y\>
+
+```ts
+type TestTypeIsEqual<X, Y> = <T>() => T extends X ? 1 : 2 extends <T>() => T extends Y ? 1 : 2 ? true : false;
+```
+
+Defined in: [packages/utils/src/typingTestUtils.ts:1](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingTestUtils.ts#L1)
+
+#### Type Parameters
+
+##### X
+
+`X`
+
+##### Y
+
+`Y`
+
+***
+
+### TestTypeNotEqual\<X, Y\>
+
+```ts
+type TestTypeNotEqual<X, Y> = true extends TestTypeIsEqual<X, Y> ? false : true;
+```
+
+Defined in: [packages/utils/src/typingTestUtils.ts:4](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingTestUtils.ts#L4)
+
+#### Type Parameters
+
+##### X
+
+`X`
+
+##### Y
+
+`Y`
+
+## Variables
+
+### typingTest
+
+```ts
+const typingTest: object;
+```
+
+Defined in: [packages/utils/src/typingTestUtils.ts:48](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingTestUtils.ts#L48)
+
+#### Type declaration
+
+##### describe()
+
+```ts
+describe: (title, func) => void;
+```
+
+###### Parameters
+
+###### title
+
+`string`
+
+###### func
+
+() => `any`
+
+###### Returns
+
+`void`
+
+##### expectType()
+
+```ts
+expectType: <T>() => T;
+```
+
+Helper function for type testing that ensures a type extends `true`.
+Used in combination with `TestTypeIsEqual` to verify type equality at compile time.
+
+###### Type Parameters
+
+###### T
+
+`T` *extends* `true`
+
+Type that must extend `true`
+
+###### Returns
+
+`T`
+
+An empty object cast to type T
+
+###### Example
+
+```ts
+expectType<TestTypeIsEqual<string, string>>(); // OK
+expectType<TestTypeIsEqual<string, number>>(); // Type error
+```
+
+##### expectTypesAre()
+
+```ts
+expectTypesAre: <X, Y>(result) => void;
+```
+
+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.
+
+###### Type Parameters
+
+###### X
+
+`X`
+
+First type to compare
+
+###### Y
+
+`Y`
+
+Second type to compare
+
+###### Parameters
+
+###### result
+
+[`TestTypeIsEqual`](#testtypeisequal)\<`X`, `Y`\> *extends* `true` ? `"equal"` : `"notEqual"`
+
+Expected comparison result: 'equal' if types are equal, 'notEqual' if they differ
+
+###### Returns
+
+`void`
+
+###### Example
+
+```ts
+expectTypesAre<string, string>('equal'); // OK
+expectTypesAre<string, number>('notEqual'); // OK
+expectTypesAre<string, string>('notEqual'); // Type error
+```
+
+##### test()
+
+```ts
+test: (title, func) => void;
+```
+
+###### Parameters
+
+###### title
+
+`string`
+
+###### func
+
+() => `any`
+
+###### Returns
+
+`void`

package/docs/typingUtils.md

@@ -0,0 +1,111 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / typingUtils
+
+# typingUtils
+
+## Type Aliases
+
+### DeepPrettify\<T\>
+
+```ts
+type DeepPrettify<T> = { [K in keyof T]: T[K] extends Record<string, unknown> ? DeepPrettify<T[K]> : T[K] } & object;
+```
+
+Defined in: [packages/utils/src/typingUtils.ts:25](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingUtils.ts#L25)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+***
+
+### IsAny\<T\>
+
+```ts
+type IsAny<T> = unknown extends T ? [keyof T] extends [never] ? false : true : false;
+```
+
+Defined in: [packages/utils/src/typingUtils.ts:14](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingUtils.ts#L14)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+***
+
+### NonPartial\<T\>
+
+```ts
+type NonPartial<T> = { [K in keyof Required<T>]: T[K] };
+```
+
+Defined in: [packages/utils/src/typingUtils.ts:5](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingUtils.ts#L5)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+***
+
+### ObjKeysWithValuesOfType\<Obj, ValueType\>
+
+```ts
+type ObjKeysWithValuesOfType<Obj, ValueType> = { [K in keyof Obj]: Obj[K] extends ValueType ? K : never }[keyof Obj];
+```
+
+Defined in: [packages/utils/src/typingUtils.ts:7](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingUtils.ts#L7)
+
+#### Type Parameters
+
+##### Obj
+
+`Obj` *extends* `Record`\<`PropertyKey`, `unknown`\>
+
+##### ValueType
+
+`ValueType`
+
+***
+
+### PartialRecord\<K, T\>
+
+```ts
+type PartialRecord<K, T> = { [P in K]?: T };
+```
+
+Defined in: [packages/utils/src/typingUtils.ts:1](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingUtils.ts#L1)
+
+#### Type Parameters
+
+##### K
+
+`K` *extends* keyof `any`
+
+##### T
+
+`T`
+
+***
+
+### Prettify\<T\>
+
+```ts
+type Prettify<T> = { [P in keyof T]: T[P] } & object;
+```
+
+Defined in: [packages/utils/src/typingUtils.ts:21](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingUtils.ts#L21)
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>

package/docs/yamlStringify.md

@@ -0,0 +1,45 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / yamlStringify
+
+# yamlStringify
+
+## Functions
+
+### yamlStringify()
+
+```ts
+function yamlStringify(obj, __namedParameters): string;
+```
+
+Defined in: [packages/utils/src/yamlStringify.ts:5](https://github.com/lucasols/utils/blob/main/packages/utils/src/yamlStringify.ts#L5)
+
+#### Parameters
+
+##### obj
+
+`unknown`
+
+##### \_\_namedParameters
+
+###### addRootObjSpaces?
+
+`false` \| `"beforeAndAfter"` \| `"before"` \| `"after"` = `'beforeAndAfter'`
+
+###### maxDepth?
+
+`number` = `50`
+
+###### maxLineLength?
+
+`number` = `100`
+
+###### showUndefined?
+
+`boolean`
+
+#### Returns
+
+`string`

package/lib/arrayUtils.js

@@ -10,9 +10,9 @@ import {
   rejectDuplicates,
   sortBy,
   truncateArray
-} from "./chunk-DMW5Q4T2.js";
-import "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-SRVMMYSW.js";
+import "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 export {
   arrayWithPrev,
   arrayWithPrevAndIndex,

package/lib/assertions.js

@@ -9,8 +9,8 @@ import {
   isPromise,
   notNullish,
   notUndefined
-} from "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 export {
   assertIsNotNullish,
   assertIsNotUndefined,

package/lib/awaitDebounce.cjs

@@ -0,0 +1,106 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/awaitDebounce.ts
+var awaitDebounce_exports = {};
+__export(awaitDebounce_exports, {
+  awaitDebounce: () => awaitDebounce
+});
+module.exports = __toCommonJS(awaitDebounce_exports);
+
+// src/typeGuards.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/assertions.ts
+var isObject2 = isObject;
+
+// src/getCompositeKey.ts
+function getCompositeKey(input, maxSortingDepth = 3) {
+  if (typeof input === "string") return `"${input}`;
+  if (!input || typeof input !== "object") return `$${input}`;
+  return stringifyCompact(input, maxSortingDepth, 0, /* @__PURE__ */ new WeakSet());
+}
+function stringifyCompact(input, maxSortingDepth, depth, refs) {
+  const isJsObj = input && typeof input === "object";
+  if (isJsObj) {
+    if (refs.has(input)) {
+      throw new Error("Circular reference detected");
+    }
+    refs.add(input);
+  }
+  let result;
+  if (Array.isArray(input)) {
+    result = "[";
+    for (const v of input) {
+      if (result.length > 1) result += ",";
+      result += stringifyCompact(v, maxSortingDepth, depth + 1, refs);
+    }
+    result += "]";
+  } else if (isObject2(input)) {
+    let entries = Object.entries(input);
+    if (entries.length === 0) {
+      result = "{}";
+    } else {
+      if (depth < maxSortingDepth) {
+        entries = entries.sort(
+          ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+        );
+      }
+      result = "{";
+      for (const [k, v] of entries) {
+        if (v === void 0) continue;
+        if (result.length > 1) result += ",";
+        result += `${k}:${stringifyCompact(v, maxSortingDepth, depth + 1, refs)}`;
+      }
+      result += "}";
+    }
+  } else {
+    result = JSON.stringify(input);
+  }
+  if (isJsObj) {
+    refs.delete(input);
+  }
+  return result;
+}
+
+// src/awaitDebounce.ts
+var resolvers = {};
+var debouncers = {};
+async function awaitDebounce({
+  callId: _callId,
+  debounce
+}) {
+  const callId = getCompositeKey(_callId);
+  if (debouncers[callId]) clearTimeout(debouncers[callId]);
+  debouncers[callId] = globalThis.setTimeout(() => {
+    const resolve = resolvers[callId];
+    resolvers[callId] = void 0;
+    resolve?.("continue");
+  }, debounce);
+  if (resolvers[callId]) resolvers[callId]("skip");
+  return new Promise((resolve) => {
+    resolvers[callId] = resolve;
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  awaitDebounce
+});

package/lib/awaitDebounce.d.cts

@@ -0,0 +1,38 @@
+import { __LEGIT_ANY__ } from './saferTyping.cjs';
+
+/**
+ * Creates an awaitable debounce mechanism that allows you to debounce async operations.
+ * When called multiple times with the same `callId`, only the last call will resolve with 'continue',
+ * while all previous calls resolve with 'skip'.
+ *
+ * This is useful for debouncing API calls, search operations, or any async work where you want
+ * to ensure only the most recent request is processed.
+ *
+ * @param options - Configuration object
+ * @param options.callId - Unique identifier for the debounce group. Calls with the same ID are debounced together
+ * @param options.debounce - Debounce delay in milliseconds
+ * @returns Promise that resolves to 'continue' if this call should proceed, or 'skip' if it was superseded
+ *
+ * @example
+ * ```ts
+ * async function searchUsers(query: string) {
+ *   const result = await awaitDebounce({ callId: 'search', debounce: 300 });
+ *   if (result === 'skip') return; // This search was superseded
+ *
+ *   // Only the most recent search will reach here
+ *   const users = await fetchUsers(query);
+ *   updateUI(users);
+ * }
+ *
+ * // Called rapidly - only the last call will execute
+ * searchUsers('a');
+ * searchUsers('ab');
+ * searchUsers('abc'); // Only this one will continue
+ * ```
+ */
+declare function awaitDebounce({ callId: _callId, debounce, }: {
+    callId: __LEGIT_ANY__;
+    debounce: number;
+}): Promise<'continue' | 'skip'>;
+
+export { awaitDebounce };

package/lib/awaitDebounce.d.ts

@@ -0,0 +1,38 @@
+import { __LEGIT_ANY__ } from './saferTyping.js';
+
+/**
+ * Creates an awaitable debounce mechanism that allows you to debounce async operations.
+ * When called multiple times with the same `callId`, only the last call will resolve with 'continue',
+ * while all previous calls resolve with 'skip'.
+ *
+ * This is useful for debouncing API calls, search operations, or any async work where you want
+ * to ensure only the most recent request is processed.
+ *
+ * @param options - Configuration object
+ * @param options.callId - Unique identifier for the debounce group. Calls with the same ID are debounced together
+ * @param options.debounce - Debounce delay in milliseconds
+ * @returns Promise that resolves to 'continue' if this call should proceed, or 'skip' if it was superseded
+ *
+ * @example
+ * ```ts
+ * async function searchUsers(query: string) {
+ *   const result = await awaitDebounce({ callId: 'search', debounce: 300 });
+ *   if (result === 'skip') return; // This search was superseded
+ *
+ *   // Only the most recent search will reach here
+ *   const users = await fetchUsers(query);
+ *   updateUI(users);
+ * }
+ *
+ * // Called rapidly - only the last call will execute
+ * searchUsers('a');
+ * searchUsers('ab');
+ * searchUsers('abc'); // Only this one will continue
+ * ```
+ */
+declare function awaitDebounce({ callId: _callId, debounce, }: {
+    callId: __LEGIT_ANY__;
+    debounce: number;
+}): Promise<'continue' | 'skip'>;
+
+export { awaitDebounce };

package/lib/awaitDebounce.js

@@ -0,0 +1,28 @@
+import {
+  getCompositeKey
+} from "./chunk-6FIBVC2P.js";
+import "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
+
+// src/awaitDebounce.ts
+var resolvers = {};
+var debouncers = {};
+async function awaitDebounce({
+  callId: _callId,
+  debounce
+}) {
+  const callId = getCompositeKey(_callId);
+  if (debouncers[callId]) clearTimeout(debouncers[callId]);
+  debouncers[callId] = globalThis.setTimeout(() => {
+    const resolve = resolvers[callId];
+    resolvers[callId] = void 0;
+    resolve?.("continue");
+  }, debounce);
+  if (resolvers[callId]) resolvers[callId]("skip");
+  return new Promise((resolve) => {
+    resolvers[callId] = resolve;
+  });
+}
+export {
+  awaitDebounce
+};

package/lib/cache.js

@@ -5,8 +5,8 @@ import "./chunk-HTCYUMDR.js";
 import "./chunk-II4R3VVX.js";
 import {
   isPromise
-} from "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 
 // src/cache.ts
 function cachedGetter(getter) {

package/lib/{chunk-NH2LCAQS.js → chunk-6FIBVC2P.js}

@@ -1,6 +1,6 @@
 import {
   isObject
-} from "./chunk-WS4WEVHU.js";
+} from "./chunk-C2SVCIWE.js";
 
 // src/getCompositeKey.ts
 function getCompositeKey(input, maxSortingDepth = 3) {

package/lib/{chunk-GKOTKAIV.js → chunk-7CQPOM5I.js}

@@ -1,6 +1,6 @@
 import {
   isFunction
-} from "./chunk-WS4WEVHU.js";
+} from "./chunk-C2SVCIWE.js";
 
 // src/enhancedMap.ts
 var enhancedMapReject = Symbol();

package/lib/{chunk-WS4WEVHU.js → chunk-C2SVCIWE.js}

@@ -3,7 +3,7 @@ import {
   isObject,
   isPlainObject,
   isPromise
-} from "./chunk-SSKW673U.js";
+} from "./chunk-JF2MDHOJ.js";
 
 // src/assertions.ts
 var undefErrMsg = "not undefined assertion failed";

package/lib/{chunk-SSKW673U.js → chunk-JF2MDHOJ.js}

@@ -25,6 +25,9 @@ function isNonEmptyArray(value) {
 function arrayHasAtLeastXItems(array, minLength) {
   return array.length >= minLength;
 }
+function isTruthy(value) {
+  return !!value;
+}
 
 export {
   isObject,
@@ -32,5 +35,6 @@ export {
   isPromise,
   isPlainObject,
   isNonEmptyArray,
-  arrayHasAtLeastXItems
+  arrayHasAtLeastXItems,
+  isTruthy
 };