@1nkvi/utils 0.3.1 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -9
- package/build/artifacts/src/index.d.ts +1 -0
- package/build/artifacts/src/index.js +1 -0
- package/build/artifacts/src/types/LooseString.d.ts +10 -0
- package/build/artifacts/src/types/LooseString.js +1 -0
- package/build/artifacts/src/types/index.d.ts +1 -0
- package/build/artifacts/src/types/index.js +1 -0
- package/build/artifacts/src/window/getCssProperty.d.ts +12 -0
- package/build/artifacts/src/window/getCssProperty.js +15 -0
- package/build/artifacts/src/window/index.d.ts +1 -0
- package/build/artifacts/src/window/index.js +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,15 +1,30 @@
|
|
|
1
1
|
# @1nkvi/utils
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@1nkvi/utils)
|
|
4
|
+
[](https://www.npmjs.com/package/@1nkvi/utils)
|
|
5
|
+
[](https://www.npmjs.com/package/@1nkvi/utils)
|
|
6
|
+
[](./LICENSE)
|
|
7
|
+
|
|
8
|
+
Type-safe utility functions for the common scenarios that occur when working with objects — deep merging, immutable updates
|
|
9
|
+
by dot-notation path, and dot-path utility types — plus a handful of array, map, randomness, and type-guard helpers to
|
|
10
|
+
round things out.
|
|
11
|
+
|
|
12
|
+
- 🧩 **Fully typed** — written in TypeScript; ships its own declarations.
|
|
13
|
+
- 🌳 **Tree-shakeable** — side-effect free, so bundlers drop what you don't import.
|
|
14
|
+
- 🪶 **Zero runtime dependencies.**
|
|
15
|
+
|
|
16
|
+
## Requirements
|
|
17
|
+
|
|
18
|
+
- **ESM-only.** The package ships only an `import` entry — use it from ESM (or a bundler). `require("@1nkvi/utils")`
|
|
19
|
+
is not supported.
|
|
20
|
+
- **Node ≥ 24.**
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
3
24
|
```shell
|
|
4
25
|
pnpm i @1nkvi/utils
|
|
5
26
|
```
|
|
6
27
|
|
|
7
|
-
A small collection of TypeScript helper functions and utility types. Its centerpiece is **deeply merging** partial
|
|
8
|
-
objects and arrays — composing a list of partials into one while overriding primitives, concatenating and de-duplicating
|
|
9
|
-
arrays, and merging nested objects recursively, all while filtering out "empty" values like `null`, `undefined` and
|
|
10
|
-
`""`. Alongside it are a handful of array, map, randomness, and type-guard utilities, plus reusable object/path utility
|
|
11
|
-
types.
|
|
12
|
-
|
|
13
28
|
## Changelog
|
|
14
29
|
|
|
15
30
|
[Changelog link](./CHANGELOG.md)
|
|
@@ -19,8 +34,8 @@ types.
|
|
|
19
34
|
```ts
|
|
20
35
|
import { merge } from "@1nkvi/utils"
|
|
21
36
|
|
|
22
|
-
merge([{ id: 1 }, { name: "
|
|
23
|
-
// → { id: 1, name: "
|
|
37
|
+
merge([{ id: 1 }, { name: "Hello" }, { name: "World" }])
|
|
38
|
+
// → { id: 1, name: "World" }
|
|
24
39
|
```
|
|
25
40
|
|
|
26
41
|
## Modules
|
|
@@ -33,4 +48,5 @@ merge([{ id: 1 }, { name: "Ada" }, { name: "Ada Lovelace" }])
|
|
|
33
48
|
| [merge](./docs/merge.md) | Deeply `merge` partial objects, `mergeArrays` with de-duplication, and `filterValidPrimitiveArrayValues`, all skipping "empty" values. |
|
|
34
49
|
| [object](./docs/object.md) | `replace` a single deeply nested value by dot-notation path — immutably and type-safely, without touching its siblings. |
|
|
35
50
|
| [random](./docs/random.md) | Random integers: `random` within inclusive/exclusive bounds, and `randomMarginalChange` to nudge a value by fixed and percentage margins. |
|
|
36
|
-
| [types](./docs/types.md) | Utility types for nested objects: `DeepPartial`, `DotPaths`, `LeafDotPaths`, `DotPathsWithArrayIndex`, `FlatObject`, `IsPlainObject
|
|
51
|
+
| [types](./docs/types.md) | Utility types for nested objects: `DeepPartial`, `DotPaths`, `LeafDotPaths`, `DotPathsWithArrayIndex`, `FlatObject`, `IsPlainObject`, plus `LooseString` for string-literal autocomplete. |
|
|
52
|
+
| [window](./docs/window.md) | Browser DOM helpers: `getCssProperty` reads a computed CSS custom property from an element (defaults to `<html>`). |
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Allows user to insert any `string` but also provides autocomplete for `TType`
|
|
3
|
+
* @example ```tsx
|
|
4
|
+
* type Dark = "dark"|"light"
|
|
5
|
+
*
|
|
6
|
+
* const works: LooseString<Dark> = "dark"
|
|
7
|
+
* const alsoWorks: LooseString<Dark> = "system"
|
|
8
|
+
* ```
|
|
9
|
+
*/
|
|
10
|
+
export type LooseString<TType extends string> = TType | (string & {});
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Retrieves css property based on the input.
|
|
3
|
+
* @param propertyName full name of css property (e.g. `--breakpoint-lg`)
|
|
4
|
+
* @param ref optional reference to html element. If not provided, root document is used
|
|
5
|
+
* @remarks resulting string doesnt resolve calculations. If css variable contains e.g. `calc(2rem + 5%)`, the output will be this, not resulting value
|
|
6
|
+
*
|
|
7
|
+
* @example ```tsx
|
|
8
|
+
* getCssProperty("--breakpoint-lg") // 64rem
|
|
9
|
+
* getCssProperty("--radius-sm") // calc(0.625rem - 4px)
|
|
10
|
+
* ```
|
|
11
|
+
*/
|
|
12
|
+
export declare function getCssProperty(propertyName: string, ref?: HTMLElement | null): string;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Retrieves css property based on the input.
|
|
3
|
+
* @param propertyName full name of css property (e.g. `--breakpoint-lg`)
|
|
4
|
+
* @param ref optional reference to html element. If not provided, root document is used
|
|
5
|
+
* @remarks resulting string doesnt resolve calculations. If css variable contains e.g. `calc(2rem + 5%)`, the output will be this, not resulting value
|
|
6
|
+
*
|
|
7
|
+
* @example ```tsx
|
|
8
|
+
* getCssProperty("--breakpoint-lg") // 64rem
|
|
9
|
+
* getCssProperty("--radius-sm") // calc(0.625rem - 4px)
|
|
10
|
+
* ```
|
|
11
|
+
*/
|
|
12
|
+
export function getCssProperty(propertyName, ref) {
|
|
13
|
+
const el = ref ?? document.documentElement;
|
|
14
|
+
return window.getComputedStyle(el).getPropertyValue(propertyName);
|
|
15
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./getCssProperty";
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./getCssProperty";
|