@ls-stack/utils 3.13.0 → 3.15.0

package/lib/typeGuards.d.cts

@@ -0,0 +1,109 @@
+/**
+ * Type guard to check if a value is a plain object (not null, not an array).
+ *
+ * Returns true if the value is an object that is not null and not an array.
+ * This is useful for distinguishing between objects and other types.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isObject(value)) {
+ *   // TypeScript knows value is Record<string, unknown>
+ *   console.log(value.someProperty);
+ * }
+ *
+ * isObject({});           // true
+ * isObject({ a: 1 });     // true
+ * isObject(null);         // false
+ * isObject([]);           // false
+ * isObject('string');     // false
+ * ```
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to check if a value is a function.
+ *
+ * Returns true if the value is a function of any kind (regular function,
+ * arrow function, method, constructor, etc.).
+ *
+ * @param value - The value to check
+ * @returns True if the value is a function, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isFunction(value)) {
+ *   // TypeScript knows value is (...args: any[]) => any
+ *   const result = value();
+ * }
+ *
+ * isFunction(() => {});           // true
+ * isFunction(function() {});      // true
+ * isFunction(Math.max);           // true
+ * isFunction('string');           // false
+ * isFunction({});                 // false
+ * ```
+ */
+declare function isFunction(value: unknown): value is (...args: any[]) => any;
+/**
+ * Type guard to check if a value is a Promise or thenable object.
+ *
+ * Returns true if the value is an object with a `then` method that is a function.
+ * This covers both native Promises and thenable objects that implement the
+ * Promise interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Promise or thenable, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isPromise(value)) {
+ *   // TypeScript knows value is Promise<unknown>
+ *   const result = await value;
+ * }
+ *
+ * isPromise(Promise.resolve());           // true
+ * isPromise(new Promise(() => {}));       // true
+ * isPromise({ then: () => {} });          // true
+ * isPromise({ then: 'not a function' });  // false
+ * isPromise('string');                    // false
+ * ```
+ */
+declare function isPromise(value: unknown): value is Promise<unknown>;
+/**
+ * Type guard to check if a value is a plain object (created by Object literal or Object constructor).
+ *
+ * Returns true if the value is a plain object - an object created by the Object
+ * constructor or object literal syntax. This excludes instances of classes,
+ * built-in objects like Date, RegExp, etc.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isPlainObject(value)) {
+ *   // TypeScript knows value is Record<string, unknown>
+ *   console.log(Object.keys(value));
+ * }
+ *
+ * isPlainObject({});                    // true
+ * isPlainObject({ a: 1 });              // true
+ * isPlainObject(Object.create(null));   // true
+ * isPlainObject(new Date());            // false
+ * isPlainObject(/regex/);               // false
+ * isPlainObject(new MyClass());         // false
+ * isPlainObject([]);                    // false
+ * ```
+ */
+declare function isPlainObject(value: any): value is Record<string, unknown>;
+type NonEmptyArray<T> = [T, ...T[]];
+declare function isNonEmptyArray<T>(value: T[] | readonly T[]): value is NonEmptyArray<T>;
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 1): array is [T, ...T[]];
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 2): array is [T, T, ...T[]];
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 3): array is [T, T, T, ...T[]];
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 4): array is [T, T, T, T, ...T[]];
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 5): array is [T, T, T, T, T, ...T[]];
+
+export { type NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise };

package/lib/typeGuards.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Type guard to check if a value is a plain object (not null, not an array).
+ *
+ * Returns true if the value is an object that is not null and not an array.
+ * This is useful for distinguishing between objects and other types.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isObject(value)) {
+ *   // TypeScript knows value is Record<string, unknown>
+ *   console.log(value.someProperty);
+ * }
+ *
+ * isObject({});           // true
+ * isObject({ a: 1 });     // true
+ * isObject(null);         // false
+ * isObject([]);           // false
+ * isObject('string');     // false
+ * ```
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to check if a value is a function.
+ *
+ * Returns true if the value is a function of any kind (regular function,
+ * arrow function, method, constructor, etc.).
+ *
+ * @param value - The value to check
+ * @returns True if the value is a function, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isFunction(value)) {
+ *   // TypeScript knows value is (...args: any[]) => any
+ *   const result = value();
+ * }
+ *
+ * isFunction(() => {});           // true
+ * isFunction(function() {});      // true
+ * isFunction(Math.max);           // true
+ * isFunction('string');           // false
+ * isFunction({});                 // false
+ * ```
+ */
+declare function isFunction(value: unknown): value is (...args: any[]) => any;
+/**
+ * Type guard to check if a value is a Promise or thenable object.
+ *
+ * Returns true if the value is an object with a `then` method that is a function.
+ * This covers both native Promises and thenable objects that implement the
+ * Promise interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Promise or thenable, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isPromise(value)) {
+ *   // TypeScript knows value is Promise<unknown>
+ *   const result = await value;
+ * }
+ *
+ * isPromise(Promise.resolve());           // true
+ * isPromise(new Promise(() => {}));       // true
+ * isPromise({ then: () => {} });          // true
+ * isPromise({ then: 'not a function' });  // false
+ * isPromise('string');                    // false
+ * ```
+ */
+declare function isPromise(value: unknown): value is Promise<unknown>;
+/**
+ * Type guard to check if a value is a plain object (created by Object literal or Object constructor).
+ *
+ * Returns true if the value is a plain object - an object created by the Object
+ * constructor or object literal syntax. This excludes instances of classes,
+ * built-in objects like Date, RegExp, etc.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isPlainObject(value)) {
+ *   // TypeScript knows value is Record<string, unknown>
+ *   console.log(Object.keys(value));
+ * }
+ *
+ * isPlainObject({});                    // true
+ * isPlainObject({ a: 1 });              // true
+ * isPlainObject(Object.create(null));   // true
+ * isPlainObject(new Date());            // false
+ * isPlainObject(/regex/);               // false
+ * isPlainObject(new MyClass());         // false
+ * isPlainObject([]);                    // false
+ * ```
+ */
+declare function isPlainObject(value: any): value is Record<string, unknown>;
+type NonEmptyArray<T> = [T, ...T[]];
+declare function isNonEmptyArray<T>(value: T[] | readonly T[]): value is NonEmptyArray<T>;
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 1): array is [T, ...T[]];
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 2): array is [T, T, ...T[]];
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 3): array is [T, T, T, ...T[]];
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 4): array is [T, T, T, T, ...T[]];
+declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 5): array is [T, T, T, T, T, ...T[]];
+
+export { type NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise };

package/lib/typeGuards.js

@@ -0,0 +1,16 @@
+import {
+  arrayHasAtLeastXItems,
+  isFunction,
+  isNonEmptyArray,
+  isObject,
+  isPlainObject,
+  isPromise
+} from "./chunk-SSKW673U.js";
+export {
+  arrayHasAtLeastXItems,
+  isFunction,
+  isNonEmptyArray,
+  isObject,
+  isPlainObject,
+  isPromise
+};

package/lib/typingFnUtils.cjs

@@ -25,8 +25,10 @@ __export(typingFnUtils_exports, {
   isObjKey: () => isObjKey,
   isSubTypeOf: () => isSubTypeOf,
   narrowStringToUnion: () => narrowStringToUnion,
+  typeOnRightExtendsLeftType: () => typeOnRightExtendsLeftType,
   typedObjectEntries: () => typedObjectEntries,
-  typedObjectKeys: () => typedObjectKeys
+  typedObjectKeys: () => typedObjectKeys,
+  unionsAreTheSame: () => unionsAreTheSame
 });
 module.exports = __toCommonJS(typingFnUtils_exports);
 function asNonPartial(obj) {
@@ -47,12 +49,15 @@ function narrowStringToUnion(key, union) {
   }
   return void 0;
 }
-function isSubTypeOf() {
+function typeOnRightExtendsLeftType() {
   return void 0;
 }
+var isSubTypeOf = typeOnRightExtendsLeftType;
 function isObjKey(key, obj) {
   return typeof key === "string" && key in obj;
 }
+function unionsAreTheSame(_diff) {
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   asNonPartial,
@@ -60,6 +65,8 @@ function isObjKey(key, obj) {
   isObjKey,
   isSubTypeOf,
   narrowStringToUnion,
+  typeOnRightExtendsLeftType,
   typedObjectEntries,
-  typedObjectKeys
+  typedObjectKeys,
+  unionsAreTheSame
 });

package/lib/typingFnUtils.d.cts

@@ -18,10 +18,33 @@ declare function narrowStringToUnion<const T extends string>(key: string | undef
  * @template SubType - The type that should extend BaseType
  * @returns {unknown} Returns undefined, only used for type checking
  */
-declare function isSubTypeOf<BaseType, SubType extends BaseType>(): unknown;
+declare function typeOnRightExtendsLeftType<BaseType, SubType extends BaseType>(): unknown;
+/** @deprecated use typeOnRightExtendsLeftType instead */
+declare const isSubTypeOf: typeof typeOnRightExtendsLeftType;
 /**
  * Type helper to narrow a string to a key of an object.
  */
 declare function isObjKey<T extends Record<string, unknown>>(key: unknown, obj: T): key is keyof T;
+type UnionDiff<T, U> = [
+    T
+] extends [U] ? [
+    U
+] extends [T] ? null : {
+    onRightHasExtra: Exclude<U, T>;
+} : [U] extends [T] ? {
+    onRightHasMissing: Exclude<T, U>;
+} : {
+    onRightHasExtra: Exclude<U, T>;
+    onRightHasMissing: Exclude<T, U>;
+};
+/**
+ * Type helper to compare two union types and determine their relationship.
+ *
+ * @template T - The first union type (left side)
+ * @template U - The second union type (right side)
+ * @param _diff - null if unions are identical, or an object describing the difference
+ * @returns void - This function is only used for type checking
+ */
+declare function unionsAreTheSame<T, U>(_diff: UnionDiff<T, U>): void;
 
-export { asNonPartial, asType, isObjKey, isSubTypeOf, narrowStringToUnion, typedObjectEntries, typedObjectKeys };
+export { asNonPartial, asType, isObjKey, isSubTypeOf, narrowStringToUnion, typeOnRightExtendsLeftType, typedObjectEntries, typedObjectKeys, unionsAreTheSame };

package/lib/typingFnUtils.d.ts

@@ -18,10 +18,33 @@ declare function narrowStringToUnion<const T extends string>(key: string | undef
  * @template SubType - The type that should extend BaseType
  * @returns {unknown} Returns undefined, only used for type checking
  */
-declare function isSubTypeOf<BaseType, SubType extends BaseType>(): unknown;
+declare function typeOnRightExtendsLeftType<BaseType, SubType extends BaseType>(): unknown;
+/** @deprecated use typeOnRightExtendsLeftType instead */
+declare const isSubTypeOf: typeof typeOnRightExtendsLeftType;
 /**
  * Type helper to narrow a string to a key of an object.
  */
 declare function isObjKey<T extends Record<string, unknown>>(key: unknown, obj: T): key is keyof T;
+type UnionDiff<T, U> = [
+    T
+] extends [U] ? [
+    U
+] extends [T] ? null : {
+    onRightHasExtra: Exclude<U, T>;
+} : [U] extends [T] ? {
+    onRightHasMissing: Exclude<T, U>;
+} : {
+    onRightHasExtra: Exclude<U, T>;
+    onRightHasMissing: Exclude<T, U>;
+};
+/**
+ * Type helper to compare two union types and determine their relationship.
+ *
+ * @template T - The first union type (left side)
+ * @template U - The second union type (right side)
+ * @param _diff - null if unions are identical, or an object describing the difference
+ * @returns void - This function is only used for type checking
+ */
+declare function unionsAreTheSame<T, U>(_diff: UnionDiff<T, U>): void;
 
-export { asNonPartial, asType, isObjKey, isSubTypeOf, narrowStringToUnion, typedObjectEntries, typedObjectKeys };
+export { asNonPartial, asType, isObjKey, isSubTypeOf, narrowStringToUnion, typeOnRightExtendsLeftType, typedObjectEntries, typedObjectKeys, unionsAreTheSame };

package/lib/typingFnUtils.js

@@ -17,18 +17,23 @@ function narrowStringToUnion(key, union) {
   }
   return void 0;
 }
-function isSubTypeOf() {
+function typeOnRightExtendsLeftType() {
   return void 0;
 }
+var isSubTypeOf = typeOnRightExtendsLeftType;
 function isObjKey(key, obj) {
   return typeof key === "string" && key in obj;
 }
+function unionsAreTheSame(_diff) {
+}
 export {
   asNonPartial,
   asType,
   isObjKey,
   isSubTypeOf,
   narrowStringToUnion,
+  typeOnRightExtendsLeftType,
   typedObjectEntries,
-  typedObjectKeys
+  typedObjectKeys,
+  unionsAreTheSame
 };

package/lib/yamlStringify.cjs

@@ -24,7 +24,7 @@ __export(yamlStringify_exports, {
 });
 module.exports = __toCommonJS(yamlStringify_exports);
 
-// src/assertions.ts
+// src/typeGuards.ts
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -40,6 +40,10 @@ function isPlainObject(value) {
   return typeof Ctor == "function" && Function.toString.call(Ctor) === objectCtorString;
 }
 
+// src/assertions.ts
+var isObject2 = isObject;
+var isPlainObject2 = isPlainObject;
+
 // src/conversions.ts
 function bytesToHumanReadable(bytes) {
   if (bytes < 1024) {
@@ -70,7 +74,7 @@ function yamlStringify(obj, {
   maxDepth = 50,
   addRootObjSpaces = "beforeAndAfter"
 } = {}) {
-  if (isObject(obj) || Array.isArray(obj) || typeof obj === "function") {
+  if (isObject2(obj) || Array.isArray(obj) || typeof obj === "function") {
     return `${stringifyValue(obj, "", maxLineLength, !!showUndefined, maxDepth, 0, addRootObjSpaces)}
 `;
   }
@@ -79,7 +83,7 @@ function yamlStringify(obj, {
 function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, depth, addObjSpaces) {
   let result = "";
   const childIndent = `${indent}  `;
-  if (isPlainObject(value)) {
+  if (isPlainObject2(value)) {
     if (Object.keys(value).length === 0) {
       return "{}";
     }
@@ -106,7 +110,7 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
         depth + 1,
         addObjSpaces
       );
-      if (!afterSpaceWasAdded && indent === "" && isObject(objVal) && prevValue && (addObjSpaces === "before" || addObjSpaces === "beforeAndAfter")) {
+      if (!afterSpaceWasAdded && indent === "" && isObject2(objVal) && prevValue && (addObjSpaces === "before" || addObjSpaces === "beforeAndAfter")) {
         result += "\n";
       }
       if (Array.isArray(objVal)) {
@@ -117,7 +121,7 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
           result += `${indent}${key}:
 `;
         }
-      } else if (isObject(objVal)) {
+      } else if (isObject2(objVal)) {
         if (Object.keys(objVal).length === 0) {
           result += `${indent}${key}: `;
         } else {
@@ -130,7 +134,7 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
       result += valueString;
       result += "\n";
       if (indent === "") {
-        if (isObject(objVal)) {
+        if (isObject2(objVal)) {
           if (addObjSpaces === "after" || addObjSpaces === "beforeAndAfter") {
             result += "\n";
             afterSpaceWasAdded = true;
@@ -180,7 +184,7 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
           item = `{max depth reached}`;
         }
         result += `${indent}- `;
-        if (Array.isArray(item) || isObject(item)) {
+        if (Array.isArray(item) || isObject2(item)) {
           let arrayString = stringifyValue(
             item,
             childIndent,
@@ -227,8 +231,12 @@ ${indent}${line}
         }
       }
     } else {
-      if (value.includes("'")) {
+      if (value.includes("'") && !value.includes('"')) {
         result += `"${value}"`;
+      } else if (value.includes('"') && !value.includes("'")) {
+        result += `'${value}'`;
+      } else if (value.includes("'") && value.includes('"')) {
+        result += `"${value.replace(/"/g, '\\"')}"`;
       } else {
         result += `'${value}'`;
       }
@@ -255,7 +263,7 @@ ${indent}${line}
   return JSON.stringify(value);
 }
 function normalizeValue(value) {
-  if (value === null || isPlainObject(value) || Array.isArray(value)) {
+  if (value === null || isPlainObject2(value) || Array.isArray(value)) {
     return null;
   }
   if (value instanceof Map) {

package/lib/yamlStringify.js

@@ -4,7 +4,8 @@ import {
 import {
   isObject,
   isPlainObject
-} from "./chunk-3XCS7FVO.js";
+} from "./chunk-WS4WEVHU.js";
+import "./chunk-SSKW673U.js";
 import {
   bytesToHumanReadable
 } from "./chunk-IATIXMCE.js";
@@ -173,8 +174,12 @@ ${indent}${line}
         }
       }
     } else {
-      if (value.includes("'")) {
+      if (value.includes("'") && !value.includes('"')) {
         result += `"${value}"`;
+      } else if (value.includes('"') && !value.includes("'")) {
+        result += `'${value}'`;
+      } else if (value.includes("'") && value.includes('"')) {
+        result += `"${value.replace(/"/g, '\\"')}"`;
       } else {
         result += `'${value}'`;
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Typescript utils",
-  "version": "3.13.0",
+  "version": "3.15.0",
   "license": "MIT",
   "files": [
     "lib"
@@ -150,6 +150,10 @@
       "import": "./lib/tsResult.js",
       "require": "./lib/tsResult.cjs"
     },
+    "./typeGuards": {
+      "import": "./lib/typeGuards.js",
+      "require": "./lib/typeGuards.cjs"
+    },
     "./typingFnUtils": {
       "import": "./lib/typingFnUtils.js",
       "require": "./lib/typingFnUtils.cjs"

package/lib/chunk-3XCS7FVO.js

@@ -1,66 +0,0 @@
-// src/assertions.ts
-var undefErrMsg = "not undefined assertion failed";
-var nullishErrMsg = "not nullish assertion failed";
-function notUndefined(value, errorMsg = undefErrMsg) {
-  if (value === void 0) {
-    throw new Error(errorMsg);
-  }
-  return value;
-}
-function notNullish(value, errorMsg = nullishErrMsg) {
-  if (value === void 0 || value === null) {
-    throw new Error(errorMsg);
-  }
-  return value;
-}
-function assertIsNotNullish(value, errorMsg = nullishErrMsg) {
-  if (value === void 0 || value === null) {
-    throw new Error(errorMsg);
-  }
-}
-function assertIsNotUndefined(value, errorMsg = undefErrMsg) {
-  if (value === void 0) {
-    throw new Error(errorMsg);
-  }
-}
-function invariant(condition, errorMsg = "Invariant violation") {
-  if (!condition) {
-    throw new Error(`Invariant violation: ${errorMsg}`);
-  }
-}
-function exhaustiveCheck(narrowedType) {
-  return new Error("This should never happen");
-}
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isFunction(value) {
-  return typeof value === "function";
-}
-function isPromise(value) {
-  return isObject(value) && "then" in value && isFunction(value.then);
-}
-function isPlainObject(value) {
-  if (!value || typeof value !== "object") return false;
-  const proto = Object.getPrototypeOf(value);
-  if (proto === null) {
-    return true;
-  }
-  const Ctor = Object.hasOwnProperty.call(proto, "constructor") && proto.constructor;
-  if (Ctor === Object) return true;
-  const objectCtorString = Object.prototype.constructor.toString();
-  return typeof Ctor == "function" && Function.toString.call(Ctor) === objectCtorString;
-}
-
-export {
-  notUndefined,
-  notNullish,
-  assertIsNotNullish,
-  assertIsNotUndefined,
-  invariant,
-  exhaustiveCheck,
-  isObject,
-  isFunction,
-  isPromise,
-  isPlainObject
-};