0
# @solid-primitives/utils
1

2
@solid-primitives/utils is a comprehensive TypeScript utility library designed specifically for building reactive primitives with Solid.js. It provides general-purpose reactive utilities for signal management, immutable data manipulation helpers, mathematical operations, and type definitions that maintain functional programming principles with non-mutating operations.
3

4
## Package Information
5

6
- **Package Name**: @solid-primitives/utils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @solid-primitives/utils` or `pnpm add @solid-primitives/utils`
10
- **Peer Dependencies**: solid-js ^1.6.12
11

12
## Core Imports
13

14
```typescript
15
import { 
16
  access, asAccessor, createHydratableSignal, 
17
  isClient, isServer, noop, clamp 
18
} from "@solid-primitives/utils";
19
```
20

21
Immutable helpers:
22

23
```typescript
24
import { 
25
  push, omit, pick, update, merge, add, subtract 
26
} from "@solid-primitives/utils/immutable";
27
```
28

29
For CommonJS:
30

31
```javascript
32
const { access, isClient, createHydratableSignal } = require("@solid-primitives/utils");
33
const { push, omit, pick, update } = require("@solid-primitives/utils/immutable");
34
```
35

36
## Basic Usage
37

38
```typescript
39
import { createSignal } from "solid-js";
40
import { access, createHydratableSignal } from "@solid-primitives/utils";
41
import { push, update } from "@solid-primitives/utils/immutable";
42

43
// Using accessor utilities
44
const getValue = (maybeAccessor: string | (() => string)) => {
45
  return access(maybeAccessor); // Works with both values and functions
46
};
47

48
// Creating hydratable signals
49
const [serverState, setServerState] = createHydratableSignal(
50
  "initial server value",
51
  () => "updated client value"
52
);
53

54
// Using immutable helpers with signals
55
const [list, setList] = createSignal([1, 2, 3]);
56
setList(current => push(current, 4, 5)); // [1, 2, 3, 4, 5]
57

58
const [user, setUser] = createSignal({
59
  name: "John",
60
  address: { street: "Main St", number: 123 }
61
});
62
setUser(current => update(current, "address", "number", 456));
63
```
64

65
## Architecture
66

67
@solid-primitives/utils is organized into several key functional areas:
68

69
- **Reactive Utilities**: Functions for working with Solid.js signals, accessors, and reactivity patterns
70
- **Environment Detection**: Client/server and development/production environment helpers  
71
- **Type System**: Comprehensive TypeScript types and utility types for enhanced type safety
72
- **Immutable Operations**: Functional programming helpers for non-mutating data manipulation
73
- **Object/Array Utilities**: General-purpose utilities for working with JavaScript data structures
74
- **Mathematical Operations**: Basic math functions designed for immutable workflows
75

76
## Capabilities
77

78
### Reactive Utilities
79

80
Core utilities for working with Solid.js reactivity system, including accessor manipulation, signal creation, and lifecycle management.
81

82
```typescript { .api }
83
function access<T extends MaybeAccessor<any>>(v: T): MaybeAccessorValue<T>;
84
function asAccessor<A extends MaybeAccessor<unknown>>(v: A): Accessor<MaybeAccessorValue<A>>;
85
function createHydratableSignal<T>(
86
  serverValue: T,
87
  update: () => T,
88
  options?: SignalOptions<T>
89
): ReturnType<typeof createSignal<T>>;
90
function defer<S, Next extends Prev, Prev = Next>(
91
  deps: AccessorArray<S> | Accessor<S>,
92
  fn: (input: S, prevInput: S, prev: undefined | NoInfer<Prev>) => Next,
93
  initialValue?: Next
94
): EffectFunction<undefined | NoInfer<Next>>;
95

96
type MaybeAccessor<T> = T | Accessor<T>;
97
type MaybeAccessorValue<T extends MaybeAccessor<any>> = T extends () => any ? ReturnType<T> : T;
98
```
99

100
[Reactive Utilities](./reactive-utilities.md)
101

102
### Immutable Array Operations
103

104
Non-mutating array manipulation functions that return new arrays without modifying the original data structures.
105

106
```typescript { .api }
107
function push<T>(list: readonly T[], ...items: T[]): T[];
108
function filter<T>(list: readonly T[], predicate: Predicate<T>): T[] & { removed: number };
109
function sort<T>(list: T[], compareFn?: (a: T, b: T) => number): T[];
110
function splice<T>(list: readonly T[], start: number, deleteCount?: number, ...items: T[]): T[];
111
function concat<A extends any[], V extends ItemsOf<A>>(...a: A): Array<V extends any[] ? ItemsOf<V> : V>;
112

113
type Predicate<T> = (item: T, index: number, array: readonly T[]) => boolean;
114
```
115

116
[Immutable Arrays](./immutable-arrays.md)
117

118
### Immutable Object Operations
119

120
Non-mutating object manipulation functions for property selection, modification, merging, and copying operations.
121

122
```typescript { .api }
123
function omit<O extends object, K extends keyof O>(object: O, ...keys: K[]): Omit<O, K>;
124
function pick<O extends object, K extends keyof O>(object: O, ...keys: K[]): Pick<O, K>;
125
function merge<A extends object, B extends object>(a: A, b: B): Modify<A, B>;
126
function get<O extends object, K extends keyof O>(obj: O, key: K): O[K];
127
function update<O extends object, K extends keyof O, V>(
128
  object: O,
129
  key: K,
130
  setter: UpdateSetter<O, K, V>
131
): ModifyValue<O, K, V>;
132
function shallowArrayCopy<T>(array: readonly T[]): T[];
133
function shallowObjectCopy<T extends object>(object: T): T;
134
function withArrayCopy<T>(array: readonly T[], mutator: (copy: T[]) => void): T[];
135
function withObjectCopy<T extends object>(object: T, mutator: (copy: T) => void): T;
136

137
type UpdateSetter<O, K extends keyof O, V> = V | ((prev: O[K]) => V);
138
type Modify<T, R> = Omit<T, keyof R> & R;
139
type ModifyValue<O, K extends keyof O, V> = Omit<O, K> & { [key in K]: V };
140
```
141

142
[Immutable Objects](./immutable-objects.md)
143

144
### Mathematical Operations
145

146
Immutable mathematical functions for basic arithmetic operations, designed to work well with functional programming patterns.
147

148
```typescript { .api }
149
function add(...a: number[]): number;
150
function add(...a: string[]): string;
151
function substract(a: number, ...b: number[]): number;
152
function multiply(a: number, ...b: number[]): number;
153
function divide(a: number, ...b: number[]): number;
154
function power(a: number, ...b: number[]): number;
155
function clamp(n: number, min: number, max: number): number;
156
```
157

158
[Mathematical Operations](./math-operations.md)
159

160
### Environment and Utility Functions
161

162
Environment detection, utility functions, and general-purpose helpers for common programming tasks.
163

164
```typescript { .api }
165
const isServer: boolean;
166
const isClient: boolean;
167
const isDev: boolean;
168
const isProd: boolean;
169

170
function noop(...a: any[]): void;
171
function isObject(value: any): value is AnyObject;
172
function arrayEquals(a: readonly unknown[], b: readonly unknown[]): boolean;
173
function chain<Args extends [] | any[]>(callbacks: {
174
  [Symbol.iterator](): IterableIterator<((...args: Args) => any) | undefined>;
175
}): (...args: Args) => void;
176

177
type AnyObject = Record<PropertyKey, any>;
178
```
179

180
[Environment and Utilities](./environment-utilities.md)
181

182
### Type Definitions
183

184
Comprehensive TypeScript type utilities and definitions for enhanced type safety and developer experience.
185

186
```typescript { .api }
187
type Many<T> = T | T[];
188
type ItemsOf<T> = T extends (infer E)[] ? E : never;
189
type Directive<P = true> = (el: Element, props: Accessor<P>) => void;
190
type Truthy<T> = Exclude<T, FalsyValue>;
191
type Falsy<T> = Extract<T, FalsyValue>;
192
type Position = { x: number; y: number; };
193
type Size = { width: number; height: number; };
194
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
195

196
type FalsyValue = false | 0 | "" | null | undefined;
197
type PrimitiveValue = PropertyKey | boolean | bigint | null | undefined;
198
```
199

200
[Type Definitions](./type-definitions.md)