mutts 1.0.11 → 1.0.13
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 +5 -2
- package/dist/browser.cjs +237 -2596
- package/dist/browser.cjs.map +1 -1
- package/dist/browser.d.ts +1407 -2
- package/dist/browser.dev.cjs +44 -43
- package/dist/browser.dev.cjs.map +1 -1
- package/dist/browser.dev.d.ts +2 -2
- package/dist/browser.dev.esm.js +2 -2
- package/dist/browser.esm.js +3 -3
- package/dist/chunks/index-CAdnMJev.cjs +2735 -0
- package/dist/chunks/index-CAdnMJev.cjs.map +1 -0
- package/dist/chunks/{index-Sf74wXTV.esm.js → index-XsYTUhHx.esm.js} +200 -77
- package/dist/chunks/index-XsYTUhHx.esm.js.map +1 -0
- package/dist/chunks/{async-node-3PrbVAbB.cjs → node-DrrphEPf.cjs} +4 -4
- package/dist/chunks/node-DrrphEPf.cjs.map +1 -0
- package/dist/chunks/{node-Bo7WU5S2.esm.js → node-NEZvVo4M.esm.js} +2 -2
- package/dist/chunks/{node-Bo7WU5S2.esm.js.map → node-NEZvVo4M.esm.js.map} +1 -1
- package/dist/chunks/{proxy-D2C49sXH.esm.js → proxy-BtmPFjSr.esm.js} +307 -66
- package/dist/chunks/proxy-BtmPFjSr.esm.js.map +1 -0
- package/dist/chunks/{proxy-Cc79Lrzj.cjs → proxy-DBHj3kGK.cjs} +341 -70
- package/dist/chunks/proxy-DBHj3kGK.cjs.map +1 -0
- package/dist/debug.cjs +537 -167
- package/dist/debug.cjs.map +1 -1
- package/dist/debug.d.ts +96 -80
- package/dist/debug.esm.js +533 -166
- package/dist/debug.esm.js.map +1 -1
- package/dist/devtools/panel.js.map +1 -1
- package/dist/mutts.umd.js +508 -140
- package/dist/mutts.umd.js.map +1 -1
- package/dist/mutts.umd.min.js +1 -1
- package/dist/mutts.umd.min.js.map +1 -1
- package/dist/node.cjs +44 -42
- package/dist/node.cjs.map +1 -1
- package/dist/node.d.ts +2 -2
- package/dist/node.dev.cjs +44 -42
- package/dist/node.dev.cjs.map +1 -1
- package/dist/node.dev.d.ts +2 -2
- package/dist/node.dev.esm.js +3 -3
- package/dist/node.esm.js +3 -3
- package/dist/{types-Bx2PhORg.d.ts → types.d.ts} +12 -0
- package/docs/ai/api-reference.md +102 -12
- package/docs/ai/manual.md +60 -24
- package/docs/debug-getReason.md +161 -0
- package/docs/flavored.md +98 -1
- package/docs/reactive/advanced.md +15 -2
- package/docs/reactive/attend.md +32 -0
- package/docs/reactive/core.md +40 -6
- package/docs/reactive/debugging.md +25 -2
- package/docs/reactive.md +2 -0
- package/package.json +2 -3
- package/dist/chunks/async-browser-Dgr5CreQ.cjs +0 -218
- package/dist/chunks/async-browser-Dgr5CreQ.cjs.map +0 -1
- package/dist/chunks/async-core-CRLKP3l-.cjs +0 -29
- package/dist/chunks/async-core-CRLKP3l-.cjs.map +0 -1
- package/dist/chunks/async-node-3PrbVAbB.cjs.map +0 -1
- package/dist/chunks/index-Sf74wXTV.esm.js.map +0 -1
- package/dist/chunks/proxy-Cc79Lrzj.cjs.map +0 -1
- package/dist/chunks/proxy-D2C49sXH.esm.js.map +0 -1
- package/dist/index.d.ts +0 -1322
package/dist/browser.d.ts
CHANGED
|
@@ -1,2 +1,1407 @@
|
|
|
1
|
-
|
|
2
|
-
export { A as AZone,
|
|
1
|
+
import { c as EffectAccess, d as EffectCloser, S as ScopedCallback, e as State, a as Evolution, b as EffectCleanup, Z as ZoneAggregator, C as CleanupReason, H as HistoryValue, E as EffectTrigger, f as CatchFunction, g as EffectOptions } from './types.js';
|
|
2
|
+
export { A as AZone, G as GetterWrapper, P as PropTrigger, R as ReactiveError, h as ReactiveErrorCode, i as Zone, j as ZoneHistory, k as asyncZone, l as debugPreset, m as devPreset, n as formatCleanupReason, o as isReactive, p as objectToProxy, q as prodPreset, r as proxyToObject, s as reactiveOptions, u as unwrap } from './types.js';
|
|
3
|
+
|
|
4
|
+
type Restorer = () => () => void;
|
|
5
|
+
type Hook = () => Restorer;
|
|
6
|
+
declare const hooks$1: Set<Hook>;
|
|
7
|
+
declare const asyncHooks: {
|
|
8
|
+
addHook(hook: Hook): () => void;
|
|
9
|
+
/**
|
|
10
|
+
* [Hack] Sanitize a promise (or value) to prevent context leaks.
|
|
11
|
+
* Default: Identity function.
|
|
12
|
+
* Browser: Uses Macrotask wrapping to break microtask chains.
|
|
13
|
+
*/
|
|
14
|
+
sanitizePromise(p: any): any;
|
|
15
|
+
};
|
|
16
|
+
/**
|
|
17
|
+
* Register a hook that will be called whenever an asynchronous operation is initiated.
|
|
18
|
+
* The hook should return a restorer function which will be called just before the async callback runs.
|
|
19
|
+
* That restorer should in turn return an undoer function which will be called just after the async callback finishes.
|
|
20
|
+
*/
|
|
21
|
+
declare const asyncHook: (hook: Hook) => () => void;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Error thrown when decorator operations fail
|
|
25
|
+
*/
|
|
26
|
+
declare class DecoratorError extends Error {
|
|
27
|
+
constructor(message: string);
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Legacy property decorator type for methods, getters, and setters
|
|
31
|
+
*/
|
|
32
|
+
type LegacyPropertyDecorator<T> = (target: T, name: string | symbol, descriptor: PropertyDescriptor) => any;
|
|
33
|
+
/**
|
|
34
|
+
* Legacy class decorator type
|
|
35
|
+
*/
|
|
36
|
+
type LegacyClassDecorator<T> = (target: T) => any;
|
|
37
|
+
/**
|
|
38
|
+
* Modern method decorator type
|
|
39
|
+
*/
|
|
40
|
+
type ModernMethodDecorator<T> = (target: T, context: ClassMethodDecoratorContext) => any;
|
|
41
|
+
/**
|
|
42
|
+
* Modern getter decorator type
|
|
43
|
+
*/
|
|
44
|
+
type ModernGetterDecorator<T> = (target: T, context: ClassGetterDecoratorContext) => any;
|
|
45
|
+
/**
|
|
46
|
+
* Modern setter decorator type
|
|
47
|
+
*/
|
|
48
|
+
type ModernSetterDecorator<T> = (target: T, context: ClassSetterDecoratorContext) => any;
|
|
49
|
+
/**
|
|
50
|
+
* Modern accessor decorator type
|
|
51
|
+
*/
|
|
52
|
+
type ModernAccessorDecorator<T> = (target: T, context: ClassAccessorDecoratorContext) => any;
|
|
53
|
+
/**
|
|
54
|
+
* Modern class decorator type
|
|
55
|
+
*/
|
|
56
|
+
type ModernClassDecorator<T> = (target: T, context: ClassDecoratorContext) => any;
|
|
57
|
+
type DDMethod<T> = (original: (this: T, ...args: any[]) => any, target: any, name: PropertyKey) => ((this: T, ...args: any[]) => any) | void;
|
|
58
|
+
type DDGetter<T> = (original: (this: T) => any, target: any, name: PropertyKey) => ((this: T) => any) | void;
|
|
59
|
+
type DDSetter<T> = (original: (this: T, value: any) => void, target: any, name: PropertyKey) => ((this: T, value: any) => void) | void;
|
|
60
|
+
type DDClass<T> = <Ctor extends new (...args: any[]) => T = new (...args: any[]) => T>(target: Ctor) => Ctor | void;
|
|
61
|
+
/**
|
|
62
|
+
* Description object for creating decorators that work with both Legacy and Modern decorator proposals
|
|
63
|
+
*/
|
|
64
|
+
interface DecoratorDescription<T> {
|
|
65
|
+
/** Handler for method decorators */
|
|
66
|
+
method?: DDMethod<T>;
|
|
67
|
+
/** Handler for class decorators */
|
|
68
|
+
class?: DDClass<T>;
|
|
69
|
+
/** Handler for getter decorators */
|
|
70
|
+
getter?: DDGetter<T>;
|
|
71
|
+
/** Handler for setter decorators */
|
|
72
|
+
setter?: DDSetter<T>;
|
|
73
|
+
/** Default handler for any decorator type not explicitly defined */
|
|
74
|
+
default?: (...args: any[]) => any;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Type for decorators that work with both Legacy and Modern decorator proposals
|
|
78
|
+
* Automatically infers the correct decorator type based on the description
|
|
79
|
+
*/
|
|
80
|
+
type Decorator<T, Description extends DecoratorDescription<T>> = (Description extends {
|
|
81
|
+
method: DDMethod<T>;
|
|
82
|
+
} ? LegacyPropertyDecorator<T> & ModernMethodDecorator<T> : unknown) & (Description extends {
|
|
83
|
+
class: DDClass<new (...args: any[]) => T>;
|
|
84
|
+
} ? LegacyClassDecorator<new (...args: any[]) => T> & ModernClassDecorator<new (...args: any[]) => T> : unknown) & (Description extends {
|
|
85
|
+
getter: DDGetter<T>;
|
|
86
|
+
} ? LegacyPropertyDecorator<T> & ModernGetterDecorator<T> & ModernAccessorDecorator<T> : unknown) & (Description extends {
|
|
87
|
+
setter: DDSetter<T>;
|
|
88
|
+
} ? LegacyPropertyDecorator<T> & ModernSetterDecorator<T> & ModernAccessorDecorator<T> : unknown) & (Description extends {
|
|
89
|
+
default: infer Signature;
|
|
90
|
+
} ? Signature : unknown);
|
|
91
|
+
/**
|
|
92
|
+
* Factory type for creating decorators that work with both Legacy and Modern decorator proposals
|
|
93
|
+
*/
|
|
94
|
+
type DecoratorFactory<T> = <Description extends DecoratorDescription<T>>(description: Description) => (Description extends {
|
|
95
|
+
method: DDMethod<T>;
|
|
96
|
+
} ? LegacyPropertyDecorator<T> & ModernMethodDecorator<T> : unknown) & (Description extends {
|
|
97
|
+
class: DDClass<new (...args: any[]) => T>;
|
|
98
|
+
} ? LegacyClassDecorator<new (...args: any[]) => T> & ModernClassDecorator<new (...args: any[]) => T> : unknown) & (Description extends {
|
|
99
|
+
getter: DDGetter<T>;
|
|
100
|
+
} ? LegacyPropertyDecorator<T> & ModernGetterDecorator<T> & ModernAccessorDecorator<T> : unknown) & (Description extends {
|
|
101
|
+
setter: DDSetter<T>;
|
|
102
|
+
} ? LegacyPropertyDecorator<T> & ModernSetterDecorator<T> & ModernAccessorDecorator<T> : unknown) & (Description extends {
|
|
103
|
+
default: infer Signature;
|
|
104
|
+
} ? Signature : unknown);
|
|
105
|
+
/**
|
|
106
|
+
* Creates a decorator that works with Legacy decorator proposals
|
|
107
|
+
* @param description - The decorator description object
|
|
108
|
+
* @returns A decorator function compatible with Legacy decorators
|
|
109
|
+
*/
|
|
110
|
+
declare function legacyDecorator<T = any>(description: DecoratorDescription<T>): any;
|
|
111
|
+
/**
|
|
112
|
+
* Creates a decorator that works with Modern decorator proposals
|
|
113
|
+
* @param description - The decorator description object
|
|
114
|
+
* @returns A decorator function compatible with Modern decorators
|
|
115
|
+
*/
|
|
116
|
+
declare function modernDecorator<T = any>(description: DecoratorDescription<T>): any;
|
|
117
|
+
/**
|
|
118
|
+
* Main decorator factory that automatically detects and works with both Legacy and Modern decorator proposals
|
|
119
|
+
* @param description - The decorator description object
|
|
120
|
+
* @returns A decorator that works in both Legacy and Modern environments
|
|
121
|
+
*/
|
|
122
|
+
declare const decorator: DecoratorFactory<any>;
|
|
123
|
+
/**
|
|
124
|
+
* Generic class decorator type that works with both Legacy and Modern decorator proposals
|
|
125
|
+
*/
|
|
126
|
+
type GenericClassDecorator<T> = LegacyClassDecorator<abstract new (...args: any[]) => T> & ModernClassDecorator<abstract new (...args: any[]) => T>;
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Symbol for marking destructor methods
|
|
130
|
+
*/
|
|
131
|
+
declare const destructor: unique symbol;
|
|
132
|
+
/**
|
|
133
|
+
* Symbol for accessing allocated values in destroyable objects
|
|
134
|
+
*/
|
|
135
|
+
declare const allocatedValues: unique symbol;
|
|
136
|
+
/**
|
|
137
|
+
* Error thrown when attempting to access a destroyed object
|
|
138
|
+
*/
|
|
139
|
+
declare class DestructionError extends Error {
|
|
140
|
+
static throw<_T = void>(msg: string): () => never;
|
|
141
|
+
constructor(msg: string);
|
|
142
|
+
}
|
|
143
|
+
declare abstract class AbstractDestroyable<Allocated> {
|
|
144
|
+
abstract [destructor](allocated: Allocated): void;
|
|
145
|
+
[Symbol.dispose](): void;
|
|
146
|
+
}
|
|
147
|
+
interface Destructor<Allocated> {
|
|
148
|
+
destructor(allocated: Allocated): void;
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Creates a destroyable class with a base class and destructor object
|
|
152
|
+
* @param base - The base class to extend
|
|
153
|
+
* @param destructorObj - Object containing the destructor method
|
|
154
|
+
* @returns A destroyable class with static destroy and isDestroyable methods
|
|
155
|
+
*/
|
|
156
|
+
declare function Destroyable<T extends new (...args: any[]) => any, Allocated extends Partial<InstanceType<T>>>(base: T, destructorObj: Destructor<Allocated>): (new (...args: ConstructorParameters<T>) => InstanceType<T> & {
|
|
157
|
+
[allocatedValues]: Allocated;
|
|
158
|
+
}) & {
|
|
159
|
+
destroy(obj: InstanceType<T>): boolean;
|
|
160
|
+
isDestroyable(obj: InstanceType<T>): boolean;
|
|
161
|
+
};
|
|
162
|
+
/**
|
|
163
|
+
* Creates a destroyable class with only a destructor object (no base class)
|
|
164
|
+
* @param destructorObj - Object containing the destructor method
|
|
165
|
+
* @returns A destroyable class with static destroy and isDestroyable methods
|
|
166
|
+
*/
|
|
167
|
+
declare function Destroyable<Allocated extends Record<PropertyKey, any> = Record<PropertyKey, any>>(destructorObj: Destructor<Allocated>): (new () => {
|
|
168
|
+
[allocatedValues]: Allocated;
|
|
169
|
+
}) & {
|
|
170
|
+
destroy(obj: any): boolean;
|
|
171
|
+
isDestroyable(obj: any): boolean;
|
|
172
|
+
};
|
|
173
|
+
/**
|
|
174
|
+
* Creates a destroyable class with a base class (requires [destructor] method)
|
|
175
|
+
* @param base - The base class to extend
|
|
176
|
+
* @returns A destroyable class with static destroy and isDestroyable methods
|
|
177
|
+
*/
|
|
178
|
+
declare function Destroyable<T extends new (...args: any[]) => any, Allocated extends Record<PropertyKey, any> = Record<PropertyKey, any>>(base: T): (new (...args: ConstructorParameters<T>) => AbstractDestroyable<Allocated> & InstanceType<T> & {
|
|
179
|
+
[allocatedValues]: Allocated;
|
|
180
|
+
}) & {
|
|
181
|
+
destroy(obj: InstanceType<T>): boolean;
|
|
182
|
+
isDestroyable(obj: InstanceType<T>): boolean;
|
|
183
|
+
};
|
|
184
|
+
/**
|
|
185
|
+
* Creates an abstract destroyable base class
|
|
186
|
+
* @returns An abstract destroyable class with static destroy and isDestroyable methods
|
|
187
|
+
*/
|
|
188
|
+
declare function Destroyable<Allocated extends Record<PropertyKey, any> = Record<PropertyKey, any>>(): abstract new () => (AbstractDestroyable<Allocated> & {
|
|
189
|
+
[allocatedValues]: Allocated;
|
|
190
|
+
}) & {
|
|
191
|
+
destroy(obj: any): boolean;
|
|
192
|
+
isDestroyable(obj: any): boolean;
|
|
193
|
+
};
|
|
194
|
+
/**
|
|
195
|
+
* Decorator that marks properties to be stored in the allocated object and passed to the destructor
|
|
196
|
+
* Use with accessor properties or explicit get/set pairs
|
|
197
|
+
*/
|
|
198
|
+
declare const allocated: LegacyPropertyDecorator<any> & ModernSetterDecorator<any> & ModernAccessorDecorator<any>;
|
|
199
|
+
/**
|
|
200
|
+
* Registers a callback to be called when an object is garbage collected
|
|
201
|
+
* @param cb - The callback function to execute on garbage collection
|
|
202
|
+
* @returns The object whose reference can be collected
|
|
203
|
+
*/
|
|
204
|
+
declare function callOnGC(cb: () => void): () => void;
|
|
205
|
+
/**
|
|
206
|
+
* Context Manager Protocol for `using` statement integration
|
|
207
|
+
* Provides automatic resource cleanup when used with the `using` statement
|
|
208
|
+
*/
|
|
209
|
+
interface ContextManager<T = any> {
|
|
210
|
+
[Symbol.dispose](): void;
|
|
211
|
+
value?: T;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
interface ArrayDiffResult<T> {
|
|
215
|
+
indexA: number;
|
|
216
|
+
indexB: number;
|
|
217
|
+
sliceA: T[];
|
|
218
|
+
sliceB: T[];
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* Myers' diff producing grouped patches: `{indexA, indexB, sliceA, sliceB}[]`.
|
|
222
|
+
* - O(N) for identical or prefix/suffix-only differences
|
|
223
|
+
* - O(ND) for small D, with a hard bailout at D=BAILOUT_D → single replacement patch
|
|
224
|
+
*/
|
|
225
|
+
declare function arrayDiff<T>(A: readonly T[], B: readonly T[]): ArrayDiffResult<T>[];
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* Base type for event maps - all event handlers must be functions
|
|
229
|
+
*/
|
|
230
|
+
type EventsBase = Record<string, (...args: any[]) => void>;
|
|
231
|
+
declare const events: unique symbol;
|
|
232
|
+
declare const hooks: unique symbol;
|
|
233
|
+
/**
|
|
234
|
+
* A type-safe event system that provides a clean API for event handling
|
|
235
|
+
* @template Events - The event map defining event names and their handler signatures
|
|
236
|
+
*/
|
|
237
|
+
declare class Eventful<Events extends EventsBase> {
|
|
238
|
+
private readonly [events];
|
|
239
|
+
private readonly [hooks];
|
|
240
|
+
hook(cb: <EventType extends keyof Events>(event: EventType, ...args: Parameters<Events[EventType]>) => void): () => void;
|
|
241
|
+
on: ((events: Partial<Events>) => void) & (<EventType extends keyof Events>(event: EventType, cb: Events[EventType]) => () => void) & { [event in keyof Events]: (cb: Events[event]) => () => void; };
|
|
242
|
+
off: ((events: Partial<Events>) => void) & (<EventType extends keyof Events>(event: EventType, cb?: Events[EventType]) => void) & { [event in keyof Events]: (cb?: Events[event]) => void; };
|
|
243
|
+
emit: (<EventType extends keyof Events>(event: EventType, ...args: Parameters<Events[EventType]>) => void) & Events;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
type AnyFunction = (...args: any[]) => any;
|
|
247
|
+
type CaptionedOptions<T extends AnyFunction> = {
|
|
248
|
+
callbackIndex?: number;
|
|
249
|
+
name?: string;
|
|
250
|
+
rename?: (caption: string, callback: Function) => unknown;
|
|
251
|
+
warn?: (message: string) => void;
|
|
252
|
+
shouldWarnAnonymous?: (callback: Function, args: Parameters<T>) => boolean;
|
|
253
|
+
};
|
|
254
|
+
type Captioned<T extends AnyFunction> = T & ((strings: TemplateStringsArray, ...values: readonly unknown[]) => T);
|
|
255
|
+
/**
|
|
256
|
+
* Wraps a callback-first function so it also accepts a tagged-template call form.
|
|
257
|
+
*
|
|
258
|
+
* The template caption is applied to one callback argument before the base
|
|
259
|
+
* function runs. By default, `captioned` targets the first argument, but
|
|
260
|
+
* `callbackIndex` can point to any callback position.
|
|
261
|
+
*
|
|
262
|
+
* This is intended for APIs such as `effect`, `lift`, or `watch` where naming
|
|
263
|
+
* is useful but should remain separate from the flavor system.
|
|
264
|
+
*
|
|
265
|
+
* Plain calls still work:
|
|
266
|
+
* `run(callback)`
|
|
267
|
+
*
|
|
268
|
+
* Captioned calls add a runtime name to the first callback:
|
|
269
|
+
* `` run`task:${id}`(callback) ``
|
|
270
|
+
*
|
|
271
|
+
* Anonymous uncaptioned callbacks may trigger a warning depending on
|
|
272
|
+
* `shouldWarnAnonymous`.
|
|
273
|
+
*/
|
|
274
|
+
declare function captioned<T extends AnyFunction>(fn: T, options?: CaptionedOptions<T>): Captioned<T>;
|
|
275
|
+
declare function inheritCaption<T extends AnyFunction>(source: AnyFunction, target: T): T;
|
|
276
|
+
/**
|
|
277
|
+
* Creates a flavored (extensible) version of a function with chainable property modifiers.
|
|
278
|
+
*/
|
|
279
|
+
declare function flavored<T extends (...args: any[]) => any, F>(fn: T, flavors: F & ThisType<T & F>): T & F;
|
|
280
|
+
/**
|
|
281
|
+
* Creates a new flavored function that transforms arguments before calling the base.
|
|
282
|
+
*
|
|
283
|
+
* @param fn - The base flavored function
|
|
284
|
+
* @param transform - Function that receives the original arguments and returns transformed arguments
|
|
285
|
+
* @returns A new flavored function with the transformation applied
|
|
286
|
+
*
|
|
287
|
+
* @example
|
|
288
|
+
* ```typescript
|
|
289
|
+
* const loudGreet = createFlavor(greet, (name, opts) => [name, { ...opts, loud: true }])
|
|
290
|
+
* ```
|
|
291
|
+
*/
|
|
292
|
+
declare function createFlavor<T extends (...args: any[]) => any>(fn: T, transform: (...args: Parameters<T>) => Parameters<T>, name?: string): T;
|
|
293
|
+
/**
|
|
294
|
+
* Creates a new flavored function that merges options objects at a specific index.
|
|
295
|
+
* By default, uses the function's arity (length) as the index for options.
|
|
296
|
+
*
|
|
297
|
+
* @param fn - The base flavored function
|
|
298
|
+
* @param defaultOptions - Options to merge
|
|
299
|
+
* @param optionsIndex - Optional explicit index for options (defaults to fn.length)
|
|
300
|
+
* @param name - Optional name for the wrapper
|
|
301
|
+
* @returns A new flavored function
|
|
302
|
+
*/
|
|
303
|
+
declare function flavorOptions<T extends (...args: any[]) => any>(fn: T, defaultOptions: Record<string, any>, opts?: {
|
|
304
|
+
optionsIndex?: number;
|
|
305
|
+
name?: string;
|
|
306
|
+
}): T;
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* Symbol for defining custom getter logic for numeric index access
|
|
310
|
+
*/
|
|
311
|
+
declare const getAt: unique symbol;
|
|
312
|
+
/**
|
|
313
|
+
* Symbol for defining custom setter logic for numeric index access
|
|
314
|
+
*/
|
|
315
|
+
declare const setAt: unique symbol;
|
|
316
|
+
interface IndexingAt<Items = any> {
|
|
317
|
+
[getAt](index: number): Items;
|
|
318
|
+
}
|
|
319
|
+
interface Accessor<T, Items> {
|
|
320
|
+
get(this: T, index: number): Items;
|
|
321
|
+
set?(this: T, index: number, value: Items): void;
|
|
322
|
+
getLength?(this: T): number;
|
|
323
|
+
setLength?(this: T, value: number): void;
|
|
324
|
+
}
|
|
325
|
+
declare abstract class AbstractGetAt<Items = any> {
|
|
326
|
+
abstract [getAt](index: number): Items;
|
|
327
|
+
}
|
|
328
|
+
/**
|
|
329
|
+
* Creates an indexable class with a base class and accessor object
|
|
330
|
+
* @param base - The base class to extend
|
|
331
|
+
* @param accessor - Object containing get/set methods for numeric index access
|
|
332
|
+
* @returns A class that supports numeric index access
|
|
333
|
+
*/
|
|
334
|
+
declare function Indexable<Items, Base extends abstract new (...args: any[]) => any>(base: Base, accessor: Accessor<InstanceType<Base>, Items>): new (...args: ConstructorParameters<Base>) => InstanceType<Base> & {
|
|
335
|
+
[x: number]: Items;
|
|
336
|
+
};
|
|
337
|
+
/**
|
|
338
|
+
* Creates an indexable class with only an accessor object (no base class)
|
|
339
|
+
* @param accessor - Object containing get/set methods for numeric index access
|
|
340
|
+
* @returns A class that supports numeric index access
|
|
341
|
+
*/
|
|
342
|
+
declare function Indexable<Items>(accessor: Accessor<any, Items>): new () => {
|
|
343
|
+
[x: number]: Items;
|
|
344
|
+
};
|
|
345
|
+
/**
|
|
346
|
+
* Creates an indexable class with a base class that has [getAt] method
|
|
347
|
+
* @param base - The base class that implements [getAt] method
|
|
348
|
+
* @returns A class that supports numeric index access using the base class's [getAt] method
|
|
349
|
+
*/
|
|
350
|
+
declare function Indexable<Base extends new (...args: any[]) => IndexingAt>(base: Base): new (...args: ConstructorParameters<Base>) => InstanceType<Base> & {
|
|
351
|
+
[x: number]: AtReturnType<InstanceType<Base>>;
|
|
352
|
+
};
|
|
353
|
+
/**
|
|
354
|
+
* Creates an abstract indexable base class
|
|
355
|
+
* @returns An abstract class that supports numeric index access
|
|
356
|
+
*/
|
|
357
|
+
declare function Indexable<Items>(): abstract new (...args: any[]) => AbstractGetAt & {
|
|
358
|
+
[x: number]: Items;
|
|
359
|
+
};
|
|
360
|
+
type AtReturnType<T> = T extends {
|
|
361
|
+
[getAt](index: number): infer R;
|
|
362
|
+
} ? R : never;
|
|
363
|
+
/**
|
|
364
|
+
* Symbol for accessing the forwarded array in ArrayReadForward
|
|
365
|
+
*/
|
|
366
|
+
declare const forwardArray: unique symbol;
|
|
367
|
+
/**
|
|
368
|
+
* A read-only array forwarder that implements all reading/iterating methods of Array
|
|
369
|
+
* but does not implement modification methods.
|
|
370
|
+
*
|
|
371
|
+
* The constructor takes a callback that returns an array, and all methods forward
|
|
372
|
+
* their behavior to the result of that callback.
|
|
373
|
+
*/
|
|
374
|
+
declare class ArrayReadForward<T> {
|
|
375
|
+
protected get [forwardArray](): readonly T[];
|
|
376
|
+
/**
|
|
377
|
+
* Get the length of the array
|
|
378
|
+
*/
|
|
379
|
+
get length(): number;
|
|
380
|
+
/**
|
|
381
|
+
* Get an element at a specific index
|
|
382
|
+
*/
|
|
383
|
+
[index: number]: T | undefined;
|
|
384
|
+
/**
|
|
385
|
+
* Iterator protocol support
|
|
386
|
+
*/
|
|
387
|
+
[Symbol.iterator](): Iterator<T>;
|
|
388
|
+
/**
|
|
389
|
+
* Creates a new array with the results of calling a provided function on every element
|
|
390
|
+
*/
|
|
391
|
+
map<U>(callbackfn: (value: T, index: number, array: readonly T[]) => U, thisArg?: any): U[];
|
|
392
|
+
/**
|
|
393
|
+
* Creates a new array with all elements that pass the test implemented by the provided function
|
|
394
|
+
*/
|
|
395
|
+
filter<S extends T>(predicate: (value: T, index: number, array: readonly T[]) => value is S, thisArg?: any): S[];
|
|
396
|
+
filter(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): T[];
|
|
397
|
+
/**
|
|
398
|
+
* Executes a reducer function on each element of the array, resulting in a single output value
|
|
399
|
+
*/
|
|
400
|
+
reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: readonly T[]) => T): T;
|
|
401
|
+
reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: readonly T[]) => T, initialValue: T): T;
|
|
402
|
+
reduce<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: readonly T[]) => U, initialValue: U): U;
|
|
403
|
+
/**
|
|
404
|
+
* Executes a reducer function on each element of the array (right-to-left), resulting in a single output value
|
|
405
|
+
*/
|
|
406
|
+
reduceRight(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: readonly T[]) => T): T;
|
|
407
|
+
reduceRight(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: readonly T[]) => T, initialValue: T): T;
|
|
408
|
+
reduceRight<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: readonly T[]) => U, initialValue: U): U;
|
|
409
|
+
/**
|
|
410
|
+
* Executes a provided function once for each array element
|
|
411
|
+
*/
|
|
412
|
+
forEach(callbackfn: (value: T, index: number, array: readonly T[]) => void, thisArg?: any): void;
|
|
413
|
+
/**
|
|
414
|
+
* Returns the value of the first element in the array that satisfies the provided testing function
|
|
415
|
+
*/
|
|
416
|
+
find<S extends T>(predicate: (value: T, index: number, array: readonly T[]) => value is S, thisArg?: any): S | undefined;
|
|
417
|
+
find(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): T | undefined;
|
|
418
|
+
/**
|
|
419
|
+
* Returns the index of the first element in the array that satisfies the provided testing function
|
|
420
|
+
*/
|
|
421
|
+
findIndex(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): number;
|
|
422
|
+
/**
|
|
423
|
+
* Returns the value of the last element in the array that satisfies the provided testing function
|
|
424
|
+
*/
|
|
425
|
+
findLast<S extends T>(predicate: (value: T, index: number, array: readonly T[]) => value is S, thisArg?: any): S | undefined;
|
|
426
|
+
findLast(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): T | undefined;
|
|
427
|
+
/**
|
|
428
|
+
* Returns the index of the last element in the array that satisfies the provided testing function
|
|
429
|
+
*/
|
|
430
|
+
findLastIndex(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): number;
|
|
431
|
+
/**
|
|
432
|
+
* Determines whether an array includes a certain value among its entries
|
|
433
|
+
*/
|
|
434
|
+
includes(searchElement: T, fromIndex?: number): boolean;
|
|
435
|
+
/**
|
|
436
|
+
* Returns the first index at which a given element can be found in the array
|
|
437
|
+
*/
|
|
438
|
+
indexOf(searchElement: T, fromIndex?: number): number;
|
|
439
|
+
/**
|
|
440
|
+
* Returns the last index at which a given element can be found in the array
|
|
441
|
+
*/
|
|
442
|
+
lastIndexOf(searchElement: T, fromIndex?: number): number;
|
|
443
|
+
/**
|
|
444
|
+
* Returns a shallow copy of a portion of an array into a new array object
|
|
445
|
+
*/
|
|
446
|
+
slice(start?: number, end?: number): T[];
|
|
447
|
+
/**
|
|
448
|
+
* Returns a new array comprised of this array joined with other array(s) and/or value(s)
|
|
449
|
+
*/
|
|
450
|
+
concat(...items: ConcatArray<T>[]): T[];
|
|
451
|
+
concat(...items: (T | ConcatArray<T>)[]): T[];
|
|
452
|
+
/**
|
|
453
|
+
* Tests whether all elements in the array pass the test implemented by the provided function
|
|
454
|
+
*/
|
|
455
|
+
every(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): boolean;
|
|
456
|
+
/**
|
|
457
|
+
* Tests whether at least one element in the array passes the test implemented by the provided function
|
|
458
|
+
*/
|
|
459
|
+
some(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): boolean;
|
|
460
|
+
/**
|
|
461
|
+
* Joins all elements of an array into a string
|
|
462
|
+
*/
|
|
463
|
+
join(separator?: string): string;
|
|
464
|
+
/**
|
|
465
|
+
* Returns a new array iterator that contains the keys for each index in the array
|
|
466
|
+
*/
|
|
467
|
+
keys(): IterableIterator<number>;
|
|
468
|
+
/**
|
|
469
|
+
* Returns a new array iterator that contains the values for each index in the array
|
|
470
|
+
*/
|
|
471
|
+
values(): IterableIterator<T>;
|
|
472
|
+
/**
|
|
473
|
+
* Returns a new array iterator that contains the key/value pairs for each index in the array
|
|
474
|
+
*/
|
|
475
|
+
entries(): IterableIterator<[number, T]>;
|
|
476
|
+
/**
|
|
477
|
+
* Returns a string representation of the array
|
|
478
|
+
*/
|
|
479
|
+
toString(): string;
|
|
480
|
+
/**
|
|
481
|
+
* Returns a localized string representing the array
|
|
482
|
+
*/
|
|
483
|
+
toLocaleString(locales?: string | string[], options?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions): string;
|
|
484
|
+
/**
|
|
485
|
+
* Returns the element at the specified index, or undefined if the index is out of bounds
|
|
486
|
+
*/
|
|
487
|
+
at(index: number): T | undefined;
|
|
488
|
+
/**
|
|
489
|
+
* Returns a new array with all sub-array elements concatenated into it recursively up to the specified depth
|
|
490
|
+
*/
|
|
491
|
+
flat(depth?: number): T[];
|
|
492
|
+
/**
|
|
493
|
+
* Returns a new array formed by applying a given callback function to each element of the array,
|
|
494
|
+
* and then flattening the result by one level
|
|
495
|
+
*/
|
|
496
|
+
flatMap<U, This = undefined>(callback: (this: This, value: T, index: number, array: readonly T[]) => U | ReadonlyArray<U>, thisArg?: This): U[];
|
|
497
|
+
/**
|
|
498
|
+
* Returns a new array with elements in reversed order (ES2023)
|
|
499
|
+
*/
|
|
500
|
+
toReversed(): T[];
|
|
501
|
+
/**
|
|
502
|
+
* Returns a new array with elements sorted (ES2023)
|
|
503
|
+
*/
|
|
504
|
+
toSorted(compareFn?: ((a: T, b: T) => number) | undefined): T[];
|
|
505
|
+
/**
|
|
506
|
+
* Returns a new array with some elements removed and/or replaced at a given index (ES2023)
|
|
507
|
+
*/
|
|
508
|
+
toSpliced(start: number, deleteCount?: number, ...items: T[]): T[];
|
|
509
|
+
/**
|
|
510
|
+
* Returns a new array with the element at the given index replaced with the given value (ES2023)
|
|
511
|
+
*/
|
|
512
|
+
with(index: number, value: T): T[];
|
|
513
|
+
get [Symbol.unscopables](): {
|
|
514
|
+
readonly [x: number]: boolean;
|
|
515
|
+
readonly length?: boolean;
|
|
516
|
+
toString?: boolean;
|
|
517
|
+
toLocaleString?: boolean;
|
|
518
|
+
concat?: boolean;
|
|
519
|
+
join?: boolean;
|
|
520
|
+
slice?: boolean;
|
|
521
|
+
indexOf?: boolean;
|
|
522
|
+
lastIndexOf?: boolean;
|
|
523
|
+
every?: boolean;
|
|
524
|
+
some?: boolean;
|
|
525
|
+
forEach?: boolean;
|
|
526
|
+
map?: boolean;
|
|
527
|
+
filter?: boolean;
|
|
528
|
+
reduce?: boolean;
|
|
529
|
+
reduceRight?: boolean;
|
|
530
|
+
find?: boolean;
|
|
531
|
+
findIndex?: boolean;
|
|
532
|
+
entries?: boolean;
|
|
533
|
+
keys?: boolean;
|
|
534
|
+
values?: boolean;
|
|
535
|
+
includes?: boolean;
|
|
536
|
+
flatMap?: boolean;
|
|
537
|
+
flat?: boolean;
|
|
538
|
+
at?: boolean;
|
|
539
|
+
findLast?: boolean;
|
|
540
|
+
findLastIndex?: boolean;
|
|
541
|
+
toReversed?: boolean;
|
|
542
|
+
toSorted?: boolean;
|
|
543
|
+
toSpliced?: boolean;
|
|
544
|
+
with?: boolean;
|
|
545
|
+
[Symbol.iterator]?: boolean;
|
|
546
|
+
readonly [Symbol.unscopables]?: boolean;
|
|
547
|
+
};
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
/**
|
|
551
|
+
* Uses weak references but still may iterate through them
|
|
552
|
+
* Note: The behavior is highly dependant on the garbage collector - some entries are perhaps deemed to be collected: don't resuscitate them
|
|
553
|
+
*/
|
|
554
|
+
declare class IterableWeakMap<K extends WeakKey, V> implements Map<K, V> {
|
|
555
|
+
private uuids;
|
|
556
|
+
private refs;
|
|
557
|
+
private readonly registry;
|
|
558
|
+
constructor(entries?: Iterable<[K, V]>);
|
|
559
|
+
private createIterator;
|
|
560
|
+
clear(): void;
|
|
561
|
+
delete(key: K): boolean;
|
|
562
|
+
forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
|
|
563
|
+
get(key: K): V | undefined;
|
|
564
|
+
has(key: K): boolean;
|
|
565
|
+
set(key: K, value: V): this;
|
|
566
|
+
get size(): number;
|
|
567
|
+
entries(): MapIterator<[K, V]>;
|
|
568
|
+
keys(): MapIterator<K>;
|
|
569
|
+
values(): MapIterator<V>;
|
|
570
|
+
[Symbol.iterator](): MapIterator<[K, V]>;
|
|
571
|
+
readonly [Symbol.toStringTag]: string;
|
|
572
|
+
}
|
|
573
|
+
/**
|
|
574
|
+
* Uses weak references but still may iterate through them
|
|
575
|
+
* Note: The behavior is highly dependant on the garbage collector - some entries are perhaps deemed to be collected: don't resuscitate them
|
|
576
|
+
*/
|
|
577
|
+
declare class IterableWeakSet<K extends WeakKey> implements Set<K> {
|
|
578
|
+
private uuids;
|
|
579
|
+
private refs;
|
|
580
|
+
private readonly registry;
|
|
581
|
+
constructor(entries?: Iterable<K>);
|
|
582
|
+
private createIterator;
|
|
583
|
+
clear(): void;
|
|
584
|
+
add(value: K): this;
|
|
585
|
+
delete(value: K): boolean;
|
|
586
|
+
forEach(callbackfn: (value: K, value2: K, set: Set<K>) => void, thisArg?: any): void;
|
|
587
|
+
has(value: K): boolean;
|
|
588
|
+
get size(): number;
|
|
589
|
+
entries(): SetIterator<[K, K]>;
|
|
590
|
+
keys(): SetIterator<K>;
|
|
591
|
+
values(): SetIterator<K>;
|
|
592
|
+
[Symbol.iterator](): SetIterator<K>;
|
|
593
|
+
readonly [Symbol.toStringTag]: string;
|
|
594
|
+
union<U>(other: ReadonlySetLike<U>): Set<K | U>;
|
|
595
|
+
intersection<U>(other: ReadonlySetLike<U>): Set<K & U>;
|
|
596
|
+
difference<U>(other: ReadonlySetLike<U>): Set<K>;
|
|
597
|
+
symmetricDifference<U>(other: ReadonlySetLike<U>): Set<K | U>;
|
|
598
|
+
isSubsetOf(other: ReadonlySetLike<unknown>): boolean;
|
|
599
|
+
isSupersetOf(other: ReadonlySetLike<unknown>): boolean;
|
|
600
|
+
isDisjointFrom(other: ReadonlySetLike<unknown>): boolean;
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
/**
|
|
604
|
+
* A mixin function that takes a base class and returns a new class with mixed-in functionality
|
|
605
|
+
* @template Mixed - The functionality to be mixed in
|
|
606
|
+
*/
|
|
607
|
+
type MixinFunction<Mixed> = <Base>(base: new (...args: any[]) => Base) => new (...args: any[]) => Base & Mixed;
|
|
608
|
+
/**
|
|
609
|
+
* A mixin class that can be used both as a base class and as a mixin function
|
|
610
|
+
* @template Mixed - The functionality to be mixed in
|
|
611
|
+
*/
|
|
612
|
+
type MixinClass<Mixed> = new (...args: any[]) => Mixed;
|
|
613
|
+
/**
|
|
614
|
+
* Creates a mixin that can be used both as a class (extends) and as a function (mixin)
|
|
615
|
+
*
|
|
616
|
+
* This function supports:
|
|
617
|
+
* - Using mixins as base classes: `class MyClass extends MyMixin`
|
|
618
|
+
* - Using mixins as functions: `class MyClass extends MyMixin(SomeBase)`
|
|
619
|
+
* - Composing mixins: `const Composed = MixinA(MixinB)`
|
|
620
|
+
* - Type-safe property inference for all patterns
|
|
621
|
+
*
|
|
622
|
+
* @param mixinFunction - The function that creates the mixin
|
|
623
|
+
* @param unwrapFunction - Optional function to unwrap reactive objects for method calls
|
|
624
|
+
* @returns A mixin that can be used both as a class and as a function
|
|
625
|
+
*/
|
|
626
|
+
declare function mixin<MixinFn extends (base: any) => new (...args: any[]) => any>(mixinFunction: MixinFn, unwrapFunction?: (obj: any) => any): (new (...args: any[]) => InstanceType<ReturnType<MixinFn>>) & (<Base>(base: abstract new (...args: any[]) => Base) => new (...args: any[]) => InstanceType<ReturnType<MixinFn>> & Base);
|
|
627
|
+
|
|
628
|
+
type Resolved<T> = T extends Promise<infer U> ? Resolved<U> : T extends (...args: infer Args) => infer R ? (...args: Args) => Resolved<R> : T extends object ? {
|
|
629
|
+
[k in keyof T]: k extends 'then' | 'catch' | 'finally' ? T[k] : Resolved<T[k]>;
|
|
630
|
+
} : T;
|
|
631
|
+
type PromiseAnd<T> = Resolved<T> & Promise<Resolved<T>>;
|
|
632
|
+
/**
|
|
633
|
+
* Type that transforms promises into chainable objects
|
|
634
|
+
* Allows calling methods directly on promise results without awaiting them first
|
|
635
|
+
*/
|
|
636
|
+
type PromiseChain<T> = T extends (...args: infer Args) => infer R ? PromiseAnd<(...args: Args) => PromiseChain<Resolved<R>>> : T extends object ? PromiseAnd<{
|
|
637
|
+
[k in keyof T]: k extends 'then' | 'catch' | 'finally' ? T[k] : PromiseChain<Resolved<T[k]>>;
|
|
638
|
+
}> : Promise<Resolved<T>>;
|
|
639
|
+
/**
|
|
640
|
+
* Transforms a promise or value into a chainable object
|
|
641
|
+
* Allows calling methods directly on promise results without awaiting them first
|
|
642
|
+
* @param given - The promise or value to make chainable
|
|
643
|
+
* @returns A chainable version of the input
|
|
644
|
+
*/
|
|
645
|
+
declare function chainPromise<T>(given: Promise<T> | T): PromiseChain<T>;
|
|
646
|
+
|
|
647
|
+
/**
|
|
648
|
+
* Reactively attends to each entry of a collection or each key yielded by an
|
|
649
|
+
* enumeration callback. For each key, an inner effect runs the callback. When a
|
|
650
|
+
* key disappears, its inner effect is disposed. The callback may return a cleanup
|
|
651
|
+
* (like a regular effect closer).
|
|
652
|
+
*
|
|
653
|
+
* Accepts arrays, records, Maps, Sets, or a raw `() => Iterable<Key>` callback.
|
|
654
|
+
*
|
|
655
|
+
* @example
|
|
656
|
+
* ```typescript
|
|
657
|
+
* // Record shorthand
|
|
658
|
+
* attend(record, (key) => { console.log(key, record[key]) })
|
|
659
|
+
*
|
|
660
|
+
* // Array shorthand
|
|
661
|
+
* attend(array, (index) => { console.log(index, array[index]) })
|
|
662
|
+
*
|
|
663
|
+
* // Raw enumeration callback
|
|
664
|
+
* attend(() => Object.keys(record), (key) => { ... })
|
|
665
|
+
* ```
|
|
666
|
+
*/
|
|
667
|
+
interface Attend extends Captioned<(source: any, callback: (key: any, access: EffectAccess) => EffectCloser | void) => ScopedCallback> {
|
|
668
|
+
<T>(source: readonly T[], callback: (index: number, access: EffectAccess) => EffectCloser | void): ScopedCallback;
|
|
669
|
+
<K, V>(source: Map<K, V>, callback: (key: K, access: EffectAccess) => EffectCloser | void): ScopedCallback;
|
|
670
|
+
<T>(source: Set<T>, callback: (value: T, access: EffectAccess) => EffectCloser | void): ScopedCallback;
|
|
671
|
+
<S extends object>(source: S, callback: (key: keyof S & string, access: EffectAccess) => EffectCloser | void): ScopedCallback;
|
|
672
|
+
<Key>(enumerate: () => Iterable<Key>, callback: (key: Key, access: EffectAccess) => EffectCloser | void): ScopedCallback;
|
|
673
|
+
}
|
|
674
|
+
declare const attend: Attend;
|
|
675
|
+
/**
|
|
676
|
+
* Lifts a callback that returns an array into a reactive array that automatically
|
|
677
|
+
* synchronizes with the source array returned by the callback.
|
|
678
|
+
*
|
|
679
|
+
* The returned reactive array will update whenever the callback's dependencies change,
|
|
680
|
+
* efficiently syncing only the elements that differ from the previous result.
|
|
681
|
+
*
|
|
682
|
+
* @example
|
|
683
|
+
* ```typescript
|
|
684
|
+
* const items = reactive([1, 2, 3])
|
|
685
|
+
* const doubled = lift(() => items.map(x => x * 2))
|
|
686
|
+
*
|
|
687
|
+
* console.log([...doubled]) // [2, 4, 6]
|
|
688
|
+
*
|
|
689
|
+
* items.push(4)
|
|
690
|
+
* console.log([...doubled]) // [2, 4, 6, 8]
|
|
691
|
+
* ```
|
|
692
|
+
*
|
|
693
|
+
* @param cb Callback function that returns an array
|
|
694
|
+
* @returns A reactive array synchronized with the callback's result, with a [cleanup] property to stop tracking
|
|
695
|
+
*/
|
|
696
|
+
interface Lift {
|
|
697
|
+
<Output extends any[]>(cb: (access: EffectAccess) => Output): Output;
|
|
698
|
+
<Output extends object>(cb: (access: EffectAccess) => Output): Output;
|
|
699
|
+
(strings: TemplateStringsArray, ...values: readonly unknown[]): Lift;
|
|
700
|
+
}
|
|
701
|
+
/**
|
|
702
|
+
* Lifts a callback that returns an object into a reactive object that automatically
|
|
703
|
+
* synchronizes with the source object returned by the callback.
|
|
704
|
+
*
|
|
705
|
+
* The returned reactive object will update whenever the callback's dependencies change,
|
|
706
|
+
* efficiently syncing only the properties that differ from the previous result using
|
|
707
|
+
* Object.assign(). Properties that no longer exist in the source are automatically removed.
|
|
708
|
+
*
|
|
709
|
+
* @example
|
|
710
|
+
* ```typescript
|
|
711
|
+
* const user = reactive({ name: 'John', age: 30 })
|
|
712
|
+
* const profile = lift(() => ({
|
|
713
|
+
* displayName: user.name.toUpperCase(),
|
|
714
|
+
* isAdult: user.age >= 18,
|
|
715
|
+
* description: `${user.name} is ${user.age} years old`
|
|
716
|
+
* }))
|
|
717
|
+
*
|
|
718
|
+
* console.log(profile.displayName) // JOHN
|
|
719
|
+
* console.log(profile.isAdult) // true
|
|
720
|
+
*
|
|
721
|
+
* user.name = 'Jane'
|
|
722
|
+
* console.log(profile.displayName) // JANE
|
|
723
|
+
* console.log(profile.description) // Jane is 30 years old
|
|
724
|
+
* ```
|
|
725
|
+
*
|
|
726
|
+
* @param cb Callback function that returns an object
|
|
727
|
+
* @returns A reactive object synchronized with the callback's result, with a [cleanup] property to stop tracking
|
|
728
|
+
*/
|
|
729
|
+
declare const lift: Lift;
|
|
730
|
+
/**
|
|
731
|
+
* Options for `morph` and its variants.
|
|
732
|
+
*
|
|
733
|
+
* @property pure - When `true`, the mapping function is assumed pure (no reactive reads inside `fn`).
|
|
734
|
+
* Per-item effects are skipped and items are computed eagerly. When a predicate `(i) => boolean`,
|
|
735
|
+
* purity is evaluated per item — pure items skip the effect wrapper, non-pure items get their own.
|
|
736
|
+
*/
|
|
737
|
+
type MorphOptions<I> = {
|
|
738
|
+
pure?: boolean | ((i: I) => boolean);
|
|
739
|
+
};
|
|
740
|
+
/**
|
|
741
|
+
* Unified reactive collection mapper. Dispatches to `morphArray`, `morphMap`, or `morphRecord`
|
|
742
|
+
* based on the source type. Access `morph.pure(source, fn)` for the `{ pure: true }` shorthand.
|
|
743
|
+
*
|
|
744
|
+
* @see morphArray
|
|
745
|
+
* @see morphMap
|
|
746
|
+
* @see morphRecord
|
|
747
|
+
*/
|
|
748
|
+
type Morph = {
|
|
749
|
+
<I, O>(source: readonly I[] | (() => readonly I[]), fn: (arg: I, access?: EffectAccess) => O, options?: MorphOptions<I>): readonly O[];
|
|
750
|
+
<K, V, O>(source: Map<K, V>, fn: (arg: V, key: K, access?: EffectAccess) => O, options?: MorphOptions<V>): Map<K, O>;
|
|
751
|
+
<S extends Record<PropertyKey, any>, O>(source: S, fn: (arg: S[keyof S], key: keyof S, access?: EffectAccess) => O, options?: MorphOptions<S[keyof S]>): {
|
|
752
|
+
[K in keyof S]: O;
|
|
753
|
+
};
|
|
754
|
+
(strings: TemplateStringsArray, ...values: readonly unknown[]): Morph;
|
|
755
|
+
pure: Morph;
|
|
756
|
+
};
|
|
757
|
+
/**
|
|
758
|
+
* Reactively maps a collection (array, Map, or record) through a per-entry function.
|
|
759
|
+
*
|
|
760
|
+
* Each entry in the source gets its own reactive context — when only one entry's dependencies
|
|
761
|
+
* change, only that entry's projection recomputes. Structural changes (additions, removals,
|
|
762
|
+
* reorders) are detected via diffing and applied surgically.
|
|
763
|
+
*
|
|
764
|
+
* Use `morph.pure(source, fn)` when `fn` has no reactive reads (skips per-item effects).
|
|
765
|
+
*
|
|
766
|
+
* @example
|
|
767
|
+
* ```ts
|
|
768
|
+
* const users = reactive([{ name: 'John' }, { name: 'Jane' }])
|
|
769
|
+
* const names = morph(users, u => u.name.toUpperCase())
|
|
770
|
+
* // names[0] = 'JOHN', names[1] = 'JANE'
|
|
771
|
+
* // Changing users[0].name only recomputes names[0]
|
|
772
|
+
* ```
|
|
773
|
+
*/
|
|
774
|
+
declare const morph: Morph;
|
|
775
|
+
|
|
776
|
+
/**
|
|
777
|
+
* Gets the current state of a reactive object for evolution tracking
|
|
778
|
+
* @param obj - The reactive object
|
|
779
|
+
* @returns The current state object
|
|
780
|
+
*/
|
|
781
|
+
declare function getState(obj: any): State;
|
|
782
|
+
/**
|
|
783
|
+
* Triggers effects for a single property change
|
|
784
|
+
* @param obj - The object that changed
|
|
785
|
+
* @param evolution - The type of change
|
|
786
|
+
* @param prop - The property that changed
|
|
787
|
+
*/
|
|
788
|
+
declare function touched1(obj: any, evolution: Evolution, prop: any): void;
|
|
789
|
+
/**
|
|
790
|
+
* Triggers effects for property changes
|
|
791
|
+
* @param obj - The object that changed
|
|
792
|
+
* @param evolution - The type of change
|
|
793
|
+
* @param props - The properties that changed
|
|
794
|
+
*/
|
|
795
|
+
declare function touched(obj: any, evolution: Evolution, props?: Iterable<any>): void;
|
|
796
|
+
|
|
797
|
+
/**
|
|
798
|
+
* Deep watch an object and all its nested properties
|
|
799
|
+
* @param target - The object to watch deeply
|
|
800
|
+
* @param callback - The callback to call when any nested property changes
|
|
801
|
+
* @param options - Options for the deep watch
|
|
802
|
+
* @returns A cleanup function to stop watching
|
|
803
|
+
*/
|
|
804
|
+
/**
|
|
805
|
+
* Sets up deep watching for an object, tracking all nested property changes
|
|
806
|
+
* @param target - The object to watch
|
|
807
|
+
* @param callback - The callback to call when changes occur
|
|
808
|
+
* @param options - Options for deep watching
|
|
809
|
+
* @returns A cleanup function to stop deep watching
|
|
810
|
+
*/
|
|
811
|
+
declare function deepWatch<T extends object>(target: T, callback: (value: T) => void, { immediate }?: {
|
|
812
|
+
immediate?: boolean;
|
|
813
|
+
}): EffectCleanup | undefined;
|
|
814
|
+
|
|
815
|
+
/**
|
|
816
|
+
* Aggregator for zones that need to be tracked along effects.
|
|
817
|
+
* ie. in each effect, the active zone of the given zoning will be the one active at effect's definition
|
|
818
|
+
*/
|
|
819
|
+
declare const effectAggregator: ZoneAggregator;
|
|
820
|
+
declare function getActiveEffect(): ScopedCallback;
|
|
821
|
+
/**
|
|
822
|
+
* Opaque token representing a captured effect context.
|
|
823
|
+
* Obtained via `effectContext()`, consumed by `withEffectContext()`.
|
|
824
|
+
*/
|
|
825
|
+
type EffectContext = {
|
|
826
|
+
readonly __brand: unique symbol;
|
|
827
|
+
};
|
|
828
|
+
/**
|
|
829
|
+
* Captures the current effect context so that deferred code can later
|
|
830
|
+
* create child effects parented to this point in the effect tree.
|
|
831
|
+
*
|
|
832
|
+
* @returns An opaque token to pass to `withEffectContext()`
|
|
833
|
+
*
|
|
834
|
+
* @example
|
|
835
|
+
* ```ts
|
|
836
|
+
* const ctx = effectContext() // inside an effect or root()
|
|
837
|
+
* // later, in a deferred callback:
|
|
838
|
+
* withEffectContext(ctx, () => {
|
|
839
|
+
* effect(() => { /* child of the captured context */ })
|
|
840
|
+
* })
|
|
841
|
+
* ```
|
|
842
|
+
*/
|
|
843
|
+
declare function effectContext(): EffectContext | undefined;
|
|
844
|
+
/**
|
|
845
|
+
* Runs `fn` within a previously captured effect context.
|
|
846
|
+
* Any effects created inside `fn` become children of the captured parent.
|
|
847
|
+
*
|
|
848
|
+
* @param ctx - The context token from `effectContext()`, or `undefined` for root context
|
|
849
|
+
* @param fn - The function to execute within the restored context
|
|
850
|
+
* @returns The return value of `fn`
|
|
851
|
+
*/
|
|
852
|
+
declare function withEffectContext<R>(ctx: EffectContext | undefined, fn: () => R): R;
|
|
853
|
+
/**
|
|
854
|
+
* Attach cleanup dependencies to an object. When `unlink(obj)` is called,
|
|
855
|
+
* each dependency is disposed: functions are invoked with the cleanup reason,
|
|
856
|
+
* objects are recursively `unlink`ed. This forms a cleanup tree.
|
|
857
|
+
*
|
|
858
|
+
* @param obj - The owner object
|
|
859
|
+
* @param cleanupFns - Cleanup callbacks and/or child objects to unlink recursively
|
|
860
|
+
* @returns The owner object (for chaining)
|
|
861
|
+
*
|
|
862
|
+
* @example
|
|
863
|
+
* ```ts
|
|
864
|
+
* // Functions are called with CleanupReason
|
|
865
|
+
* link(parent, () => console.log('disposed'))
|
|
866
|
+
*
|
|
867
|
+
* // Objects are recursively unlinked
|
|
868
|
+
* link(parent, childA, childB)
|
|
869
|
+
*
|
|
870
|
+
* // Mixed
|
|
871
|
+
* link(parent, childObj, () => timer.clear())
|
|
872
|
+
*
|
|
873
|
+
* unlink(parent) // disposes childA, childB, calls the function
|
|
874
|
+
* ```
|
|
875
|
+
*/
|
|
876
|
+
declare function link<T extends object>(obj: T, ...cleanupFns: (ScopedCallback | object | undefined)[]): T;
|
|
877
|
+
/**
|
|
878
|
+
* Dispose an object's cleanup dependencies. Functions are called with the
|
|
879
|
+
* reason; linked objects are recursively unlinked. The cleanup set is removed
|
|
880
|
+
* so calling `unlink` twice is safe (second call is a no-op).
|
|
881
|
+
*
|
|
882
|
+
* @param obj - The object to dispose
|
|
883
|
+
* @param reason - Optional cleanup reason propagated to callbacks
|
|
884
|
+
*/
|
|
885
|
+
declare function unlink(obj: object, reason?: CleanupReason): void;
|
|
886
|
+
|
|
887
|
+
interface ActivationRecord {
|
|
888
|
+
effect: EffectTrigger;
|
|
889
|
+
obj: any;
|
|
890
|
+
evolution: Evolution;
|
|
891
|
+
prop: any;
|
|
892
|
+
batchId: number;
|
|
893
|
+
}
|
|
894
|
+
/**
|
|
895
|
+
* Returns the activation log containing recent effect activations for debugging.
|
|
896
|
+
* The log is a circular buffer of the last 100 activations.
|
|
897
|
+
*
|
|
898
|
+
* @returns Array of activation records
|
|
899
|
+
*/
|
|
900
|
+
declare function getActivationLog(): Omit<ActivationRecord, "batchId">[];
|
|
901
|
+
declare function caught(onThrow: CatchFunction, effect?: EffectTrigger): void;
|
|
902
|
+
/** @deprecated Use `caught` instead */
|
|
903
|
+
declare const onEffectThrow: typeof caught;
|
|
904
|
+
/**
|
|
905
|
+
* Adds a cleanup function to be called when the current batch of effects completes
|
|
906
|
+
* @param cleanup - The cleanup function to add
|
|
907
|
+
*/
|
|
908
|
+
declare function addBatchCleanup(cleanup: EffectCleanup): void;
|
|
909
|
+
/**
|
|
910
|
+
* Semantic alias for `addBatchCleanup` - defers work to the end of the current reactive batch.
|
|
911
|
+
*
|
|
912
|
+
* Use this when an effect needs to perform an action that would modify state the effect depends on,
|
|
913
|
+
* which would create a reactive cycle. The deferred callback runs after all effects complete.
|
|
914
|
+
*
|
|
915
|
+
* @param callback - The callback to defer until after the current batch completes
|
|
916
|
+
*
|
|
917
|
+
* @example
|
|
918
|
+
* ```typescript
|
|
919
|
+
* effect(() => {
|
|
920
|
+
* processData()
|
|
921
|
+
*
|
|
922
|
+
* // Defer to avoid cycle (createMovement modifies state this effect reads)
|
|
923
|
+
* defer(() => {
|
|
924
|
+
* createMovement(data)
|
|
925
|
+
* })
|
|
926
|
+
* })
|
|
927
|
+
* ```
|
|
928
|
+
*/
|
|
929
|
+
declare const defer: typeof addBatchCleanup;
|
|
930
|
+
/**
|
|
931
|
+
* Resets the reactive system to a consistent state.
|
|
932
|
+
* Call this after an unrecoverable error has set the system to "broken".
|
|
933
|
+
* This clears all batch state, effect dependency graphs, and watcher registrations.
|
|
934
|
+
* All existing effects become orphaned and must be recreated.
|
|
935
|
+
*/
|
|
936
|
+
declare function reset(): void;
|
|
937
|
+
|
|
938
|
+
/**
|
|
939
|
+
* Decorator that makes methods atomic - batches all effects triggered within the method
|
|
940
|
+
*/
|
|
941
|
+
declare const atomic: LegacyPropertyDecorator<any> & ModernMethodDecorator<any> & (<Args extends any[], Return>(original: (...args: Args) => Return) => (...args: Args) => Return);
|
|
942
|
+
/**
|
|
943
|
+
* Wraps `fn` so it runs within `effect`'s zone context when invoked later.
|
|
944
|
+
*
|
|
945
|
+
* Useful for deferred callbacks (event listeners, `DOMContentLoaded`, etc.)
|
|
946
|
+
* that need sub-effects parented to the original effect.
|
|
947
|
+
*
|
|
948
|
+
* @param prev - The effect whose context should be restored, or `undefined` for root context
|
|
949
|
+
* @param fn - The function to wrap
|
|
950
|
+
* @returns A function with the same signature that restores the effect context before calling `fn`
|
|
951
|
+
*/
|
|
952
|
+
declare function captured<Args extends any[], Return>(prev: HistoryValue<EffectTrigger> | undefined, fn: (...args: Args) => Return): (...args: Args) => Return;
|
|
953
|
+
/**
|
|
954
|
+
* Runs `fn` atomically and **always immediately**, batching all reactive effects
|
|
955
|
+
* triggered inside it so they fire only once after `fn` completes.
|
|
956
|
+
*
|
|
957
|
+
* Unlike `atomic(fn)` which **wraps** a function for later invocation,
|
|
958
|
+
* `atom(fn)` **executes** the function right away.
|
|
959
|
+
*
|
|
960
|
+
* @example
|
|
961
|
+
* ```ts
|
|
962
|
+
* const state = reactive({ a: 0, b: 0 })
|
|
963
|
+
* effect(() => console.log(state.a, state.b)) // logs once after atom completes
|
|
964
|
+
*
|
|
965
|
+
* atom(() => {
|
|
966
|
+
* state.a = 1
|
|
967
|
+
* state.b = 2
|
|
968
|
+
* })
|
|
969
|
+
* ```
|
|
970
|
+
*/
|
|
971
|
+
declare function atom<T>(fn: () => T): any;
|
|
972
|
+
/**
|
|
973
|
+
* @param fn - The effect function to run - provides the cleaner
|
|
974
|
+
* @returns The cleanup function
|
|
975
|
+
*/
|
|
976
|
+
/**
|
|
977
|
+
* Reactive effect function with chainable flavor modifiers.
|
|
978
|
+
*/
|
|
979
|
+
type EffectCallback = (access: EffectAccess) => EffectCloser | undefined | void | Promise<any>;
|
|
980
|
+
type EffectApplication = (fn: EffectCallback, effectOptions?: EffectOptions) => EffectCleanup;
|
|
981
|
+
interface Effect extends Captioned<EffectApplication> {
|
|
982
|
+
(fn: EffectCallback, effectOptions?: EffectOptions): EffectCleanup;
|
|
983
|
+
/** Opaque flavor: bypasses deep-touch optimizations */
|
|
984
|
+
readonly opaque: Effect;
|
|
985
|
+
/** @deprecated Use `effect\`name\`(fn)` instead. */
|
|
986
|
+
named(name: string): Effect;
|
|
987
|
+
}
|
|
988
|
+
/**
|
|
989
|
+
* Creates a reactive effect that automatically re-runs when dependencies change
|
|
990
|
+
* @param fn - The effect function that provides dependencies and may return a cleanup function or Promise
|
|
991
|
+
* @param options - Options for effect execution
|
|
992
|
+
* @returns A cleanup function to stop the effect
|
|
993
|
+
*/
|
|
994
|
+
declare const effect: Effect;
|
|
995
|
+
/**
|
|
996
|
+
* Executes a function without tracking dependencies but maintains parent cleanup relationship
|
|
997
|
+
* Effects created inside will still be cleaned up when the parent effect is destroyed
|
|
998
|
+
* @param fn - The function to execute
|
|
999
|
+
*/
|
|
1000
|
+
type RootRunner = <T>(fn: () => T) => T;
|
|
1001
|
+
declare const untracked: Captioned<RootRunner>;
|
|
1002
|
+
/**
|
|
1003
|
+
* Executes a function from a virgin/root context - no parent effect, no tracking
|
|
1004
|
+
* Creates completely independent effects that won't be cleaned up by any parent
|
|
1005
|
+
* @param fn - The function to execute
|
|
1006
|
+
*/
|
|
1007
|
+
declare const root: Captioned<RootRunner>;
|
|
1008
|
+
/**
|
|
1009
|
+
* Creates a bidirectional binding between a reactive value and a non-reactive external value
|
|
1010
|
+
* Prevents infinite loops by automatically suppressing circular notifications
|
|
1011
|
+
*
|
|
1012
|
+
* @param received - Function called when the reactive value changes (external setter)
|
|
1013
|
+
* @param get - Getter for the reactive value OR an object with `{ get, set }` properties
|
|
1014
|
+
* @param set - Setter for the reactive value (required if `get` is a function)
|
|
1015
|
+
* @returns A function to manually provide updates from the external side
|
|
1016
|
+
*
|
|
1017
|
+
* @example
|
|
1018
|
+
* ```typescript
|
|
1019
|
+
* const model = reactive({ value: '' })
|
|
1020
|
+
* const input = { value: '' }
|
|
1021
|
+
*
|
|
1022
|
+
* // Bidirectional binding
|
|
1023
|
+
* const provide = biDi(
|
|
1024
|
+
* (v) => input.value = v, // external setter
|
|
1025
|
+
* () => model.value, // reactive getter
|
|
1026
|
+
* (v) => model.value = v // reactive setter
|
|
1027
|
+
* )
|
|
1028
|
+
*
|
|
1029
|
+
* // External notification (e.g., from input event)
|
|
1030
|
+
* provide('new value') // Updates model.value, doesn't trigger circular loop
|
|
1031
|
+
* ```
|
|
1032
|
+
*
|
|
1033
|
+
* @example Using object syntax
|
|
1034
|
+
* ```typescript
|
|
1035
|
+
* const provide = biDi(
|
|
1036
|
+
* (v) => setHTMLValue(v),
|
|
1037
|
+
* { get: () => reactiveObj.value, set: (v) => reactiveObj.value = v }
|
|
1038
|
+
* )
|
|
1039
|
+
* ```
|
|
1040
|
+
*/
|
|
1041
|
+
declare function biDi<T>(received: (value: T) => void, value: {
|
|
1042
|
+
get: () => T;
|
|
1043
|
+
set: (value: T) => void;
|
|
1044
|
+
}): (value: T) => void;
|
|
1045
|
+
declare function biDi<T>(received: (value: T) => void, get: () => T, set: (value: T) => void): (value: T) => void;
|
|
1046
|
+
|
|
1047
|
+
type MemoizableArgument = object | any[] | ((...args: any[]) => any);
|
|
1048
|
+
type Memoizable = ((...args: MemoizableArgument[]) => unknown) | Record<string, any>;
|
|
1049
|
+
/**
|
|
1050
|
+
* Decorator and function wrapper for memoizing computed values based on reactive dependencies.
|
|
1051
|
+
*
|
|
1052
|
+
* When used as a decorator on getters or methods, it caches the result and automatically
|
|
1053
|
+
* invalidates the cache when reactive dependencies change.
|
|
1054
|
+
*
|
|
1055
|
+
* When used as a function wrapper, it memoizes based on object arguments (WeakMap-based cache).
|
|
1056
|
+
*
|
|
1057
|
+
* @example
|
|
1058
|
+
* ```typescript
|
|
1059
|
+
* class User {
|
|
1060
|
+
* @memoize
|
|
1061
|
+
* get fullName() {
|
|
1062
|
+
* return `${this.firstName} ${this.lastName}`
|
|
1063
|
+
* }
|
|
1064
|
+
* }
|
|
1065
|
+
*
|
|
1066
|
+
* // Or as a function wrapper
|
|
1067
|
+
* const expensive = memoize((obj: SomeObject) => {
|
|
1068
|
+
* return heavyComputation(obj)
|
|
1069
|
+
* })
|
|
1070
|
+
* ```
|
|
1071
|
+
*/
|
|
1072
|
+
declare function makeMemoizeDecorator(memoizeOpts?: {
|
|
1073
|
+
lenient?: boolean;
|
|
1074
|
+
}): LegacyPropertyDecorator<any> & ModernMethodDecorator<any> & ModernGetterDecorator<any> & ModernAccessorDecorator<any> & (<T extends Memoizable>(target: T) => T);
|
|
1075
|
+
declare const memoize: ReturnType<typeof makeMemoizeDecorator> & {
|
|
1076
|
+
readonly lenient: ReturnType<typeof makeMemoizeDecorator>;
|
|
1077
|
+
};
|
|
1078
|
+
|
|
1079
|
+
/**
|
|
1080
|
+
* Add unreactive properties to a prototype.
|
|
1081
|
+
* If no set is provided, marks the entire object/prototype as non-reactive (sets [unreactiveProperties] = true).
|
|
1082
|
+
* If a set is provided, merges with existing unreactive properties (never overrides true).
|
|
1083
|
+
*/
|
|
1084
|
+
declare function addUnreactiveProps<T extends object>(proto: T, set?: Iterable<PropertyKey>): T;
|
|
1085
|
+
declare function isNonReactive(obj: any): boolean;
|
|
1086
|
+
|
|
1087
|
+
type SubProxy = {
|
|
1088
|
+
get?(obj: any, prop: PropertyKey, receiver: any): any;
|
|
1089
|
+
has?(obj: any, prop: PropertyKey): boolean;
|
|
1090
|
+
ownKeys?(obj: any): ArrayLike<string | symbol>;
|
|
1091
|
+
getOwnPropertyDescriptor?(obj: any, prop: PropertyKey): PropertyDescriptor | undefined;
|
|
1092
|
+
};
|
|
1093
|
+
/**
|
|
1094
|
+
* Base mixin for reactive classes that provides proper constructor reactivity
|
|
1095
|
+
* Solves constructor reactivity issues in complex inheritance trees
|
|
1096
|
+
*/
|
|
1097
|
+
declare const ReactiveBase: (new (...args: any[]) => {
|
|
1098
|
+
[x: string]: any;
|
|
1099
|
+
}) & (<Base>(base: abstract new (...args: any[]) => Base) => new (...args: any[]) => {
|
|
1100
|
+
[x: string]: any;
|
|
1101
|
+
} & Base);
|
|
1102
|
+
declare function reactiveObject<T>(anyTarget: T, subProxy?: SubProxy): T;
|
|
1103
|
+
/**
|
|
1104
|
+
* Main decorator for making classes reactive
|
|
1105
|
+
* Automatically makes class instances reactive when created
|
|
1106
|
+
*/
|
|
1107
|
+
declare const reactive: LegacyClassDecorator<new (...args: any[]) => any> & ModernClassDecorator<new (...args: any[]) => any> & typeof reactiveObject;
|
|
1108
|
+
|
|
1109
|
+
/**
|
|
1110
|
+
* Provides type-safe access to a source object's property within the organized callback.
|
|
1111
|
+
* @template Source - The type of the source object
|
|
1112
|
+
* @template Key - The type of the property key in the source object
|
|
1113
|
+
*/
|
|
1114
|
+
type OrganizedAccess<Source extends Record<PropertyKey, any>, Key extends keyof Source> = {
|
|
1115
|
+
/** The property key being accessed */
|
|
1116
|
+
readonly key: Key;
|
|
1117
|
+
/**
|
|
1118
|
+
* Gets the current value of the property from the source object
|
|
1119
|
+
* @returns The current value of the property
|
|
1120
|
+
*/
|
|
1121
|
+
get(): Source[Key];
|
|
1122
|
+
/**
|
|
1123
|
+
* Updates the property value in the source object
|
|
1124
|
+
* @param value - The new value to set
|
|
1125
|
+
* @returns {boolean} True if the update was successful
|
|
1126
|
+
*/
|
|
1127
|
+
set(value: Source[Key]): boolean;
|
|
1128
|
+
/**
|
|
1129
|
+
* The current value of the property (equivalent to using get()/set() directly)
|
|
1130
|
+
*/
|
|
1131
|
+
value: Source[Key];
|
|
1132
|
+
};
|
|
1133
|
+
/**
|
|
1134
|
+
* Callback function type for the organized function that processes each source property.
|
|
1135
|
+
* @template Source - The type of the source object
|
|
1136
|
+
* @template Target - The type of the target object
|
|
1137
|
+
*/
|
|
1138
|
+
type OrganizedCallback<Source extends Record<PropertyKey, any>, Target extends object> = <Key extends keyof Source>(
|
|
1139
|
+
/**
|
|
1140
|
+
* Accessor object for the current source property
|
|
1141
|
+
*/
|
|
1142
|
+
access: OrganizedAccess<Source, Key>,
|
|
1143
|
+
/**
|
|
1144
|
+
* The target object where organized data will be stored
|
|
1145
|
+
*/
|
|
1146
|
+
target: Target) => EffectCloser | undefined;
|
|
1147
|
+
/**
|
|
1148
|
+
* The result type of the organized function, combining the target object with cleanup capability.
|
|
1149
|
+
* @template Target - The type of the target object
|
|
1150
|
+
*/
|
|
1151
|
+
type OrganizedResult<Target extends object> = Target;
|
|
1152
|
+
/**
|
|
1153
|
+
* Organizes a source object's properties into a target object using a callback function.
|
|
1154
|
+
* This creates a reactive mapping between source properties and a target object,
|
|
1155
|
+
* automatically handling property additions, updates, and removals.
|
|
1156
|
+
*
|
|
1157
|
+
* @template Source - The type of the source object
|
|
1158
|
+
* @template Target - The type of the target object (defaults to Record<PropertyKey, any>)
|
|
1159
|
+
*
|
|
1160
|
+
* @param {Source} source - The source object to organize
|
|
1161
|
+
* @param {OrganizedCallback<Source, Target>} apply - Callback function that defines how each source property is mapped to the target
|
|
1162
|
+
* @param {Target} [baseTarget={}] - Optional base target object to use (will be made reactive if not already)
|
|
1163
|
+
*
|
|
1164
|
+
* @returns {OrganizedResult<Target>} The target object with cleanup capability
|
|
1165
|
+
*
|
|
1166
|
+
* @example
|
|
1167
|
+
* // Organize user permissions into role-based access
|
|
1168
|
+
* const user = reactive({ isAdmin: true, canEdit: false });
|
|
1169
|
+
* const permissions = organized(
|
|
1170
|
+
* user,
|
|
1171
|
+
* (access, target) => {
|
|
1172
|
+
* if (access.key === 'isAdmin') {
|
|
1173
|
+
* target.hasFullAccess = access.value;
|
|
1174
|
+
* }
|
|
1175
|
+
* target[`can${access.key.charAt(0).toUpperCase() + access.key.slice(1)}`] = access.value;
|
|
1176
|
+
* }
|
|
1177
|
+
* );
|
|
1178
|
+
*
|
|
1179
|
+
* @example
|
|
1180
|
+
* // Transform object structure with cleanup
|
|
1181
|
+
* const source = reactive({ firstName: 'John', lastName: 'Doe' });
|
|
1182
|
+
* const formatted = organized(
|
|
1183
|
+
* source,
|
|
1184
|
+
* (access, target) => {
|
|
1185
|
+
* if (access.key === 'firstName' || access.key === 'lastName') {
|
|
1186
|
+
* target.fullName = `${source.firstName} ${source.lastName}`.trim();
|
|
1187
|
+
* }
|
|
1188
|
+
* }
|
|
1189
|
+
* );
|
|
1190
|
+
*
|
|
1191
|
+
* @example
|
|
1192
|
+
* // Using with cleanup in a component
|
|
1193
|
+
* effect(() => {
|
|
1194
|
+
* const data = fetchData();
|
|
1195
|
+
* const organizedData = organized(data, (access, target) => {
|
|
1196
|
+
* // Transform data
|
|
1197
|
+
* });
|
|
1198
|
+
*
|
|
1199
|
+
* // The cleanup will be called automatically when the effect is disposed
|
|
1200
|
+
* return () => organizedData[cleanup]();
|
|
1201
|
+
* });
|
|
1202
|
+
*/
|
|
1203
|
+
declare function organized<Source extends Record<PropertyKey, any>, Target extends object = Record<PropertyKey, any>>(source: Source, apply: OrganizedCallback<Source, Target>, baseTarget?: Target): OrganizedResult<Target>;
|
|
1204
|
+
/**
|
|
1205
|
+
* Organizes a property on a target object
|
|
1206
|
+
* Shortcut for defineProperty/delete with touched signal
|
|
1207
|
+
* @param target - The target object
|
|
1208
|
+
* @param property - The property to organize
|
|
1209
|
+
* @param access - The access object
|
|
1210
|
+
* @returns The property descriptor
|
|
1211
|
+
*/
|
|
1212
|
+
declare function organize<T>(target: object, property: PropertyKey, access: {
|
|
1213
|
+
get?(): T;
|
|
1214
|
+
set?(value: T): boolean;
|
|
1215
|
+
}): () => boolean;
|
|
1216
|
+
|
|
1217
|
+
/**
|
|
1218
|
+
* Options for the watch function
|
|
1219
|
+
*/
|
|
1220
|
+
interface WatchOptions {
|
|
1221
|
+
/** Whether to call the callback immediately */
|
|
1222
|
+
immediate?: boolean;
|
|
1223
|
+
/** Whether to watch nested properties */
|
|
1224
|
+
deep?: boolean;
|
|
1225
|
+
}
|
|
1226
|
+
/**
|
|
1227
|
+
* Watches a reactive value and calls a callback when it changes
|
|
1228
|
+
*/
|
|
1229
|
+
interface Watch {
|
|
1230
|
+
<T>(value: (dep: EffectAccess) => T, changed: (value: T, oldValue?: T) => void, options?: Omit<WatchOptions, 'deep'> & {
|
|
1231
|
+
deep?: false;
|
|
1232
|
+
}): EffectCleanup;
|
|
1233
|
+
/**
|
|
1234
|
+
* Watches a reactive value with deep watching enabled
|
|
1235
|
+
*/
|
|
1236
|
+
<T extends object | any[]>(value: (dep: EffectAccess) => T, changed: (value: T, oldValue?: T) => void, options?: Omit<WatchOptions, 'deep'> & {
|
|
1237
|
+
deep: true;
|
|
1238
|
+
}): EffectCleanup;
|
|
1239
|
+
/**
|
|
1240
|
+
* Watches a reactive object directly
|
|
1241
|
+
*/
|
|
1242
|
+
<T extends object | any[]>(value: T, changed: (value: T) => void, options?: WatchOptions): EffectCleanup;
|
|
1243
|
+
(strings: TemplateStringsArray, ...values: readonly unknown[]): Watch;
|
|
1244
|
+
/** Deep watch flavor */
|
|
1245
|
+
get deep(): Watch;
|
|
1246
|
+
/** Immediate watch flavor */
|
|
1247
|
+
get immediate(): Watch;
|
|
1248
|
+
}
|
|
1249
|
+
declare const watch: Watch;
|
|
1250
|
+
/**
|
|
1251
|
+
* Returns a promise that resolves when the predicate returns a truthy value.
|
|
1252
|
+
* The predicate is evaluated reactively — it re-runs whenever its dependencies change.
|
|
1253
|
+
* @param predicate - Reactive function that returns a value; resolves when truthy
|
|
1254
|
+
* @param timeout - Optional timeout in milliseconds — rejects if condition is not met within this duration
|
|
1255
|
+
* @returns Promise that resolves with the first truthy return value
|
|
1256
|
+
*/
|
|
1257
|
+
declare function when<T>(predicate: (dep: EffectAccess) => T, timeout?: number): Promise<T>;
|
|
1258
|
+
declare function unreactiveApplication<T extends object>(...args: (keyof T)[]): GenericClassDecorator<T>;
|
|
1259
|
+
declare function unreactiveApplication<T extends object>(obj: T): T;
|
|
1260
|
+
/**
|
|
1261
|
+
* Decorator that marks classes or properties as non-reactive
|
|
1262
|
+
* Prevents objects from being made reactive
|
|
1263
|
+
*/
|
|
1264
|
+
declare const unreactive: LegacyClassDecorator<new (...args: any[]) => any> & ModernClassDecorator<new (...args: any[]) => any> & typeof unreactiveApplication;
|
|
1265
|
+
interface Resource<T> {
|
|
1266
|
+
value: T | undefined;
|
|
1267
|
+
loading: boolean;
|
|
1268
|
+
error: any;
|
|
1269
|
+
latest: T | undefined;
|
|
1270
|
+
reload(): void;
|
|
1271
|
+
promise: Promise<void>;
|
|
1272
|
+
}
|
|
1273
|
+
/**
|
|
1274
|
+
* Creates a reactive resource that automatically tracks async state.
|
|
1275
|
+
* @param fetcher - Async function that returns the value. Reactive dependencies are tracked.
|
|
1276
|
+
* @param options - Resource options (initialValue)
|
|
1277
|
+
* @returns Reactive Resource object with value, loading, error, latest properties
|
|
1278
|
+
*/
|
|
1279
|
+
declare function resource<T>(fetcher: (access: EffectAccess) => Promise<T> | T, options?: {
|
|
1280
|
+
initialValue?: T;
|
|
1281
|
+
}): Resource<T>;
|
|
1282
|
+
|
|
1283
|
+
/**
|
|
1284
|
+
* Executes a function and throws if any reactive dependencies are tracked during execution.
|
|
1285
|
+
* Used to assert that code runs in an untracked context.
|
|
1286
|
+
*/
|
|
1287
|
+
declare function assertUntracked<T>(fn: () => T): T;
|
|
1288
|
+
|
|
1289
|
+
/**
|
|
1290
|
+
* Object containing internal reactive system state for debugging and profiling
|
|
1291
|
+
*/
|
|
1292
|
+
declare const profileInfo: any;
|
|
1293
|
+
|
|
1294
|
+
/**
|
|
1295
|
+
* Decorator that caches the result of a getter method and only recomputes when dependencies change
|
|
1296
|
+
* Prevents circular dependencies and provides automatic cache invalidation
|
|
1297
|
+
*/
|
|
1298
|
+
declare const cached: LegacyPropertyDecorator<any> & ModernGetterDecorator<any> & ModernAccessorDecorator<any>;
|
|
1299
|
+
/**
|
|
1300
|
+
* Checks if a property is cached (has a cached value)
|
|
1301
|
+
* @param object - The object to check
|
|
1302
|
+
* @param propertyKey - The property key to check
|
|
1303
|
+
* @returns True if the property has a cached value
|
|
1304
|
+
*/
|
|
1305
|
+
declare function isCached(object: Object, propertyKey: PropertyKey): boolean;
|
|
1306
|
+
/**
|
|
1307
|
+
* Caches a value for a property on an object
|
|
1308
|
+
* @param object - The object to cache the value on
|
|
1309
|
+
* @param propertyKey - The property key to cache
|
|
1310
|
+
* @param value - The value to cache
|
|
1311
|
+
*/
|
|
1312
|
+
declare function cache(object: Object, propertyKey: PropertyKey, value: any): void;
|
|
1313
|
+
type DescriptorShape = {
|
|
1314
|
+
enumerable?: boolean;
|
|
1315
|
+
configurable?: boolean;
|
|
1316
|
+
writable?: boolean;
|
|
1317
|
+
};
|
|
1318
|
+
type DescriptorDecorator = <T>(...properties: (keyof T)[]) => GenericClassDecorator<T>;
|
|
1319
|
+
type DescriptorBuilder = ((descriptor: DescriptorShape) => DescriptorDecorator) & {
|
|
1320
|
+
readonly enumerable: DescriptorDecorator;
|
|
1321
|
+
readonly hidden: DescriptorDecorator;
|
|
1322
|
+
readonly configurable: DescriptorDecorator;
|
|
1323
|
+
readonly frozen: DescriptorDecorator;
|
|
1324
|
+
readonly writable: DescriptorDecorator;
|
|
1325
|
+
readonly readonly: DescriptorDecorator;
|
|
1326
|
+
};
|
|
1327
|
+
/**
|
|
1328
|
+
* Creates a decorator that modifies property descriptors for specified properties
|
|
1329
|
+
* @param descriptor - The descriptor properties to apply
|
|
1330
|
+
* @returns A class decorator that applies the descriptor to specified properties
|
|
1331
|
+
*/
|
|
1332
|
+
declare const descriptor: DescriptorBuilder;
|
|
1333
|
+
/**
|
|
1334
|
+
* Decorator that marks methods, properties, or classes as deprecated
|
|
1335
|
+
* Provides warning messages when deprecated items are used
|
|
1336
|
+
*/
|
|
1337
|
+
declare const deprecated: LegacyPropertyDecorator<any> & ModernMethodDecorator<any> & LegacyClassDecorator<new (...args: any[]) => any> & ModernClassDecorator<new (...args: any[]) => any> & ModernGetterDecorator<any> & ModernAccessorDecorator<any> & ModernSetterDecorator<any> & ((message: string) => LegacyPropertyDecorator<any> & ModernMethodDecorator<any> & LegacyClassDecorator<new (...args: any[]) => any> & ModernClassDecorator<new (...args: any[]) => any> & ModernGetterDecorator<any> & ModernAccessorDecorator<any> & ModernSetterDecorator<any>) & {
|
|
1338
|
+
warn: (target: any, propertyKey: PropertyKey, message?: string) => void;
|
|
1339
|
+
};
|
|
1340
|
+
/**
|
|
1341
|
+
* Creates a debounced method decorator that delays execution until after the delay period has passed
|
|
1342
|
+
* @param delay - The delay in milliseconds
|
|
1343
|
+
* @returns A method decorator that debounces method calls
|
|
1344
|
+
*/
|
|
1345
|
+
declare function debounce(delay: number): LegacyPropertyDecorator<any> & ModernMethodDecorator<any>;
|
|
1346
|
+
/**
|
|
1347
|
+
* Creates a throttled method decorator that limits execution to once per delay period
|
|
1348
|
+
* @param delay - The delay in milliseconds
|
|
1349
|
+
* @returns A method decorator that throttles method calls
|
|
1350
|
+
*/
|
|
1351
|
+
declare function throttle(delay: number): LegacyPropertyDecorator<any> & ModernMethodDecorator<any>;
|
|
1352
|
+
|
|
1353
|
+
type ElementTypes<T extends readonly unknown[]> = {
|
|
1354
|
+
[K in keyof T]: T[K] extends readonly (infer U)[] ? U : T[K];
|
|
1355
|
+
};
|
|
1356
|
+
/**
|
|
1357
|
+
* Yields tuples containing elements from each input array, stopping at the longest array length
|
|
1358
|
+
* @param args - Arrays to zip together
|
|
1359
|
+
* @returns Generator yielding tuples containing elements from each input array
|
|
1360
|
+
*/
|
|
1361
|
+
declare function zip<T extends (readonly unknown[])[]>(...args: T): Generator<ElementTypes<T>>;
|
|
1362
|
+
/**
|
|
1363
|
+
* Checks if two arrays are strictly equal (shallow comparison)
|
|
1364
|
+
* @param a - First value
|
|
1365
|
+
* @param b - Second value
|
|
1366
|
+
* @returns True if arrays are equal or values are strictly equal
|
|
1367
|
+
*/
|
|
1368
|
+
declare function arrayEquals(a: any, b: any): boolean;
|
|
1369
|
+
/**
|
|
1370
|
+
* Checks if a function is a constructor (class or constructor function)
|
|
1371
|
+
* @param fn - The function to check
|
|
1372
|
+
* @returns True if the function is a constructor
|
|
1373
|
+
*/
|
|
1374
|
+
declare function isConstructor(fn: Function): boolean;
|
|
1375
|
+
/**
|
|
1376
|
+
* Checks if a value is an object
|
|
1377
|
+
* @param value - The value to check
|
|
1378
|
+
* @returns True if the value is an object
|
|
1379
|
+
*/
|
|
1380
|
+
declare function isObject(value: any): value is object;
|
|
1381
|
+
/**
|
|
1382
|
+
* Symbol used to provide custom comparison logic for an object.
|
|
1383
|
+
*/
|
|
1384
|
+
declare const CompareSymbol: unique symbol;
|
|
1385
|
+
/**
|
|
1386
|
+
*/
|
|
1387
|
+
declare function deepCompare(a: any, b: any, cache?: Map<object, Set<object>>): boolean;
|
|
1388
|
+
/**
|
|
1389
|
+
* Tags an object with a name
|
|
1390
|
+
* @param name - The name to tag the object with
|
|
1391
|
+
* @param obj - The object to tag
|
|
1392
|
+
* @returns The object with the tag
|
|
1393
|
+
*/
|
|
1394
|
+
declare function tag<T extends object>(name: string, obj: T): T;
|
|
1395
|
+
/**
|
|
1396
|
+
* Renames a function with a new name
|
|
1397
|
+
* @param name - The new name for the function
|
|
1398
|
+
* @param fn - The function to rename
|
|
1399
|
+
* @returns The function with the new name
|
|
1400
|
+
*/
|
|
1401
|
+
declare function named<T extends Function>(name: string, fn: T): T;
|
|
1402
|
+
declare const isDev: boolean;
|
|
1403
|
+
declare const isProd: boolean;
|
|
1404
|
+
declare const isTest: boolean;
|
|
1405
|
+
|
|
1406
|
+
export { ArrayReadForward, CleanupReason, CompareSymbol, DecoratorError, Destroyable, DestructionError, EffectAccess, EffectCleanup, EffectCloser, EffectOptions, EffectTrigger, Eventful, Evolution, HistoryValue, Indexable, IterableWeakMap, IterableWeakSet, ReactiveBase, ScopedCallback, ZoneAggregator, addBatchCleanup, addUnreactiveProps, allocated, allocatedValues, arrayDiff, arrayEquals, assertUntracked, asyncHook, asyncHooks, atom, atomic, attend, biDi, cache, cached, callOnGC, captioned, captured, caught, chainPromise, createFlavor, debounce, decorator, deepCompare, deepWatch, defer, deprecated, descriptor, destructor, effect, effectAggregator, effectContext, flavorOptions, flavored, forwardArray, getActivationLog, getActiveEffect, getAt, getState, hooks$1 as hooks, inheritCaption, isCached, isConstructor, isDev, isNonReactive, isObject, isProd, isTest, legacyDecorator, lift, link, memoize, mixin, modernDecorator, morph, named, onEffectThrow, organize, organized, profileInfo, reactive, reset, resource, root, setAt, tag, throttle, touched, touched1, unlink, unreactive, untracked, watch, when, withEffectContext, zip };
|
|
1407
|
+
export type { ArrayDiffResult, Captioned, ContextManager, Decorator, DecoratorDescription, DecoratorFactory, EffectContext, EventsBase, GenericClassDecorator, Hook, LegacyClassDecorator, LegacyPropertyDecorator, Memoizable, MemoizableArgument, MixinClass, MixinFunction, ModernAccessorDecorator, ModernClassDecorator, ModernGetterDecorator, ModernMethodDecorator, ModernSetterDecorator, PromiseChain, Resource, Restorer };
|