@ls-stack/utils 3.17.1 → 3.19.0

package/docs/runShellCmd/README.md

@@ -0,0 +1,201 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / runShellCmd
+
+# runShellCmd
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Functions
+
+### ~~concurrentCmd()~~
+
+```ts
+function concurrentCmd(
+   label, 
+   cmd, 
+onResult): Promise<() => void>;
+```
+
+Defined in: [packages/utils/src/runShellCmd.ts:122](https://github.com/lucasols/utils/blob/main/packages/utils/src/runShellCmd.ts#L122)
+
+#### Parameters
+
+##### label
+
+`string`
+
+##### cmd
+
+`string` | `string`[]
+
+##### onResult
+
+(`result`) => `void`
+
+#### Returns
+
+`Promise`\<() => `void`\>
+
+#### Deprecated
+
+This utility has been moved to @ls-stack/node-utils. Please update your imports:
+```
+// Old (deprecated)
+import { concurrentCmd } from '@ls-stack/utils/runShellCmd';
+
+// New (preferred)
+import { concurrentCmd } from '@ls-stack/node-utils/runShellCmd';
+```
+
+***
+
+### ~~runCmd()~~
+
+```ts
+function runCmd(
+   label, 
+   command, 
+__namedParameters): Promise<CmdResult>;
+```
+
+Defined in: [packages/utils/src/runShellCmd.ts:31](https://github.com/lucasols/utils/blob/main/packages/utils/src/runShellCmd.ts#L31)
+
+#### Parameters
+
+##### label
+
+`null` | `string`
+
+##### command
+
+`string` | `string`[]
+
+##### \_\_namedParameters
+
+[`RunCmdOptions`](-internal-.md#runcmdoptions) = `{}`
+
+#### Returns
+
+`Promise`\<[`CmdResult`](-internal-.md#cmdresult)\>
+
+#### Deprecated
+
+This utility has been moved to @ls-stack/node-utils. Please update your imports:
+```
+// Old (deprecated)
+import { runCmd } from '@ls-stack/utils/runShellCmd';
+
+// New (preferred)
+import { runCmd } from '@ls-stack/node-utils/runShellCmd';
+```
+
+***
+
+### ~~runCmdSilent()~~
+
+```ts
+function runCmdSilent(command): Promise<CmdResult>;
+```
+
+Defined in: [packages/utils/src/runShellCmd.ts:182](https://github.com/lucasols/utils/blob/main/packages/utils/src/runShellCmd.ts#L182)
+
+#### Parameters
+
+##### command
+
+`string` | `string`[]
+
+#### Returns
+
+`Promise`\<[`CmdResult`](-internal-.md#cmdresult)\>
+
+#### Deprecated
+
+This utility has been moved to @ls-stack/node-utils. Please update your imports:
+```
+// Old (deprecated)
+import { runCmdSilent } from '@ls-stack/utils/runShellCmd';
+
+// New (preferred)
+import { runCmdSilent } from '@ls-stack/node-utils/runShellCmd';
+```
+
+***
+
+### ~~runCmdSilentUnwrap()~~
+
+```ts
+function runCmdSilentUnwrap(command): Promise<string>;
+```
+
+Defined in: [packages/utils/src/runShellCmd.ts:196](https://github.com/lucasols/utils/blob/main/packages/utils/src/runShellCmd.ts#L196)
+
+#### Parameters
+
+##### command
+
+`string` | `string`[]
+
+#### Returns
+
+`Promise`\<`string`\>
+
+#### Deprecated
+
+This utility has been moved to @ls-stack/node-utils. Please update your imports:
+```
+// Old (deprecated)
+import { runCmdSilentUnwrap } from '@ls-stack/utils/runShellCmd';
+
+// New (preferred)
+import { runCmdSilentUnwrap } from '@ls-stack/node-utils/runShellCmd';
+```
+
+***
+
+### ~~runCmdUnwrap()~~
+
+```ts
+function runCmdUnwrap(
+   label, 
+   command, 
+__namedParameters): Promise<string>;
+```
+
+Defined in: [packages/utils/src/runShellCmd.ts:160](https://github.com/lucasols/utils/blob/main/packages/utils/src/runShellCmd.ts#L160)
+
+#### Parameters
+
+##### label
+
+`null` | `string`
+
+##### command
+
+`string` | `string`[]
+
+##### \_\_namedParameters
+
+###### silent?
+
+`boolean` \| `"timeOnly"`
+
+#### Returns
+
+`Promise`\<`string`\>
+
+#### Deprecated
+
+This utility has been moved to @ls-stack/node-utils. Please update your imports:
+```
+// Old (deprecated)
+import { runCmdUnwrap } from '@ls-stack/utils/runShellCmd';
+
+// New (preferred)
+import { runCmdUnwrap } from '@ls-stack/node-utils/runShellCmd';
+```

package/docs/safeJson.md

@@ -0,0 +1,51 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / safeJson
+
+# safeJson
+
+## Functions
+
+### safeJsonParse()
+
+```ts
+function safeJsonParse(value): unknown;
+```
+
+Defined in: [packages/utils/src/safeJson.ts:11](https://github.com/lucasols/utils/blob/main/packages/utils/src/safeJson.ts#L11)
+
+JSON.parse can throw if the value is not valid JSON, this function catches those errors and returns undefined
+
+#### Parameters
+
+##### value
+
+`string`
+
+#### Returns
+
+`unknown`
+
+***
+
+### safeJsonStringify()
+
+```ts
+function safeJsonStringify(value): undefined | string;
+```
+
+Defined in: [packages/utils/src/safeJson.ts:2](https://github.com/lucasols/utils/blob/main/packages/utils/src/safeJson.ts#L2)
+
+JSON.stringify can throw if the value is circular or contains functions, this function catches those errors and returns undefined
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+#### Returns
+
+`undefined` \| `string`

package/docs/saferTyping.md

@@ -0,0 +1,228 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / saferTyping
+
+# saferTyping
+
+## Type Aliases
+
+### \_\_FIX\_THIS\_TYPING\_\_
+
+```ts
+type __FIX_THIS_TYPING__ = any;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:48](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L48)
+
+***
+
+### \_\_LEGIT\_ANY\_\_
+
+```ts
+type __LEGIT_ANY__ = any;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:4](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L4)
+
+Use this only when you have 100% of certainty that this will not break the types
+
+***
+
+### \_\_LEGIT\_ANY\_FUNCTION\_\_()
+
+```ts
+type __LEGIT_ANY_FUNCTION__ = (...params) => __LEGIT_ANY__;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:8](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L8)
+
+#### Parameters
+
+##### params
+
+...`any`
+
+#### Returns
+
+[`__LEGIT_ANY__`](#__legit_any__)
+
+***
+
+### AnyNonPrimitiveValue
+
+```ts
+type AnyNonPrimitiveValue = object;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:56](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L56)
+
+Any type that is not a primitive (number, string, boolean, null, undefined, symbol, bigint, ...)
+Equivalent to `object` type
+
+***
+
+### EmptyObject
+
+```ts
+type EmptyObject = Record<string, never>;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:13](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L13)
+
+An empty object type, equivalent to `{}` but with safer typing
+
+## Functions
+
+### \_\_FIX\_THIS\_CASTING\_\_()
+
+```ts
+function __FIX_THIS_CASTING__<T>(value): T;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:44](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L44)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+#### Returns
+
+`T`
+
+***
+
+### \_\_FIX\_THIS\_TYPING\_\_()
+
+```ts
+function __FIX_THIS_TYPING__(value): any;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:48](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L48)
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+#### Returns
+
+`any`
+
+***
+
+### \_\_LEGIT\_ANY\_CAST\_\_()
+
+```ts
+function __LEGIT_ANY_CAST__<V>(value): any;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:20](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L20)
+
+Cast a value to `any` type. Use this when you have legit usage of `any` casting.
+
+#### Type Parameters
+
+##### V
+
+`V` = `unknown`
+
+(optional) - When used enforces that the casted value is assignable to the type V, use it for safer casts
+
+#### Parameters
+
+##### value
+
+`V`
+
+#### Returns
+
+`any`
+
+***
+
+### \_\_LEGIT\_CAST\_\_()
+
+```ts
+function __LEGIT_CAST__<T, V>(value): T;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:30](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L30)
+
+Cast a value to a specific type T. Use this when you have legit usage of type assertion.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+The type to cast to
+
+##### V
+
+`V` = `unknown`
+
+(optional) - When used enforces that the casted value is assignable to the type V, use it for safer casts
+
+#### Parameters
+
+##### value
+
+`V`
+
+#### Returns
+
+`T`
+
+***
+
+### \_\_REFINE\_CAST\_\_()
+
+```ts
+function __REFINE_CAST__<T>(value): <R>() => R;
+```
+
+Defined in: [packages/utils/src/saferTyping.ts:40](https://github.com/lucasols/utils/blob/main/packages/utils/src/saferTyping.ts#L40)
+
+Refine a value to a specific type T. Use this when you have legit usage of type assertion.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+The type to cast to
+
+#### Parameters
+
+##### value
+
+`T`
+
+#### Returns
+
+```ts
+<R>(): R;
+```
+
+##### Type Parameters
+
+###### R
+
+`R`
+
+##### Returns
+
+`R`

package/docs/serializeXML.md

@@ -0,0 +1,100 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / serializeXML
+
+# serializeXML
+
+## Type Aliases
+
+### SerializeOptions
+
+```ts
+type SerializeOptions = object;
+```
+
+Defined in: [packages/utils/src/serializeXML.ts:36](https://github.com/lucasols/utils/blob/main/packages/utils/src/serializeXML.ts#L36)
+
+#### Properties
+
+##### escapeText?
+
+```ts
+optional escapeText: boolean;
+```
+
+Defined in: [packages/utils/src/serializeXML.ts:38](https://github.com/lucasols/utils/blob/main/packages/utils/src/serializeXML.ts#L38)
+
+##### indent?
+
+```ts
+optional indent: number | string;
+```
+
+Defined in: [packages/utils/src/serializeXML.ts:37](https://github.com/lucasols/utils/blob/main/packages/utils/src/serializeXML.ts#L37)
+
+##### invalidNodes?
+
+```ts
+optional invalidNodes: "throw" | "reject";
+```
+
+Defined in: [packages/utils/src/serializeXML.ts:40](https://github.com/lucasols/utils/blob/main/packages/utils/src/serializeXML.ts#L40)
+
+##### validateTagName?
+
+```ts
+optional validateTagName: boolean;
+```
+
+Defined in: [packages/utils/src/serializeXML.ts:39](https://github.com/lucasols/utils/blob/main/packages/utils/src/serializeXML.ts#L39)
+
+***
+
+### XMLNode
+
+```ts
+type XMLNode = 
+  | {
+  attrs?: Record<string, string | number | boolean | null | undefined>;
+  children?: (XMLNode | null | undefined | false)[] | string;
+  escapeText?: boolean;
+  name: string;
+  type?: "node";
+}
+  | {
+  content: string;
+  escapeText?: boolean;
+  type: "comment";
+}
+  | {
+  type: "emptyLine";
+};
+```
+
+Defined in: [packages/utils/src/serializeXML.ts:19](https://github.com/lucasols/utils/blob/main/packages/utils/src/serializeXML.ts#L19)
+
+## Functions
+
+### serializeXML()
+
+```ts
+function serializeXML(node, options?): string;
+```
+
+Defined in: [packages/utils/src/serializeXML.ts:43](https://github.com/lucasols/utils/blob/main/packages/utils/src/serializeXML.ts#L43)
+
+#### Parameters
+
+##### node
+
+[`XMLNode`](#xmlnode) | false \| XMLNode \| null \| undefined[]
+
+##### options?
+
+[`SerializeOptions`](#serializeoptions)
+
+#### Returns
+
+`string`

package/docs/shallowEqual.md

@@ -0,0 +1,33 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / shallowEqual
+
+# shallowEqual
+
+## Functions
+
+### shallowEqual()
+
+```ts
+function shallowEqual(foo, bar): boolean;
+```
+
+Defined in: [packages/utils/src/shallowEqual.ts:11](https://github.com/lucasols/utils/blob/main/packages/utils/src/shallowEqual.ts#L11)
+
+shallow equal version of https://github.com/lukeed/dequal
+
+#### Parameters
+
+##### foo
+
+`any`
+
+##### bar
+
+`any`
+
+#### Returns
+
+`boolean`

package/docs/sleep.md

@@ -0,0 +1,27 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / sleep
+
+# sleep
+
+## Functions
+
+### sleep()
+
+```ts
+function sleep(ms): Promise<unknown>;
+```
+
+Defined in: [packages/utils/src/sleep.ts:1](https://github.com/lucasols/utils/blob/main/packages/utils/src/sleep.ts#L1)
+
+#### Parameters
+
+##### ms
+
+`number`
+
+#### Returns
+
+`Promise`\<`unknown`\>

package/docs/stringUtils/-internal-.md

@@ -0,0 +1,17 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / [stringUtils](README.md) / \<internal\>
+
+# \<internal\>
+
+## Type Aliases
+
+### Arg
+
+```ts
+type Arg = string | false | undefined | null;
+```
+
+Defined in: [packages/utils/src/stringUtils.ts:1](https://github.com/lucasols/utils/blob/main/packages/utils/src/stringUtils.ts#L1)