@asaidimu/utils-cache 3.0.6 → 3.1.1
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 +370 -299
- package/index.d.mts +17 -64
- package/index.d.ts +17 -64
- package/package.json +2 -2
package/index.d.mts
CHANGED
|
@@ -1,51 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
/**
|
|
3
|
-
* Persists data to storage.
|
|
4
|
-
*
|
|
5
|
-
* @param id The **unique identifier of the *consumer instance*** making the change. This is NOT the ID of the data (`T`) itself.
|
|
6
|
-
* Think of it as the ID of the specific browser tab, component, or module that's currently interacting with the persistence layer.
|
|
7
|
-
* It should typically be a **UUID** generated once at the consumer instance's instantiation.
|
|
8
|
-
* This `id` is crucial for the `subscribe` method, helping to differentiate updates originating from the current instance versus other instances/tabs, thereby preventing self-triggered notification loops.
|
|
9
|
-
* @param state The state (of type T) to persist. This state is generally considered the **global or shared state** that all instances interact with.
|
|
10
|
-
* @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations (like `IndexedDBPersistence`), this returns a `Promise<boolean>`.
|
|
11
|
-
*/
|
|
12
|
-
set(id: string, state: T): boolean | Promise<boolean>;
|
|
13
|
-
/**
|
|
14
|
-
* Retrieves the global persisted data from storage.
|
|
15
|
-
*
|
|
16
|
-
* @returns The retrieved state of type `T`, or `null` if no data is found or if an error occurs during retrieval/parsing.
|
|
17
|
-
* For asynchronous implementations, this returns a `Promise<T | null>`.
|
|
18
|
-
*/
|
|
19
|
-
get(): (T | null) | Promise<T | null>;
|
|
20
|
-
/**
|
|
21
|
-
* Subscribes to changes in the global persisted data that originate from *other* instances of your application (e.g., other tabs or independent components using the same persistence layer).
|
|
22
|
-
*
|
|
23
|
-
* @param id The **unique identifier of the *consumer instance* subscribing**. This allows the persistence implementation to filter out notifications that were initiated by the subscribing instance itself.
|
|
24
|
-
* @param callback The function to call when the global persisted data changes from *another* source. The new state (`T`) is passed as an argument to this callback.
|
|
25
|
-
* @returns A function that, when called, will unsubscribe the provided callback from future updates. Call this when your component or instance is no longer active to prevent memory leaks.
|
|
26
|
-
*/
|
|
27
|
-
subscribe(id: string, callback: (state: T) => void): () => void;
|
|
28
|
-
/**
|
|
29
|
-
* Clears (removes) the entire global persisted data from storage.
|
|
30
|
-
*
|
|
31
|
-
* @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations, this returns a `Promise<boolean>`.
|
|
32
|
-
*/
|
|
33
|
-
clear(): boolean | Promise<boolean>;
|
|
34
|
-
/**
|
|
35
|
-
* Returns metadata about the persistence layer.
|
|
36
|
-
*
|
|
37
|
-
* This is useful for distinguishing between multiple apps running on the same host
|
|
38
|
-
* (e.g., several apps served at `localhost:3000` that share the same storage key).
|
|
39
|
-
*
|
|
40
|
-
* @returns An object containing:
|
|
41
|
-
* - `version`: The semantic version string of the persistence schema or application.
|
|
42
|
-
* - `id`: A unique identifier for the application using this persistence instance.
|
|
43
|
-
*/
|
|
44
|
-
stats(): {
|
|
45
|
-
version: string;
|
|
46
|
-
id: string;
|
|
47
|
-
};
|
|
48
|
-
}
|
|
1
|
+
import { SimplePersistence } from '@core/persistence';
|
|
49
2
|
|
|
50
3
|
interface CacheOptions {
|
|
51
4
|
staleTime?: number;
|
|
@@ -97,51 +50,51 @@ type CacheEventBase<Type extends string, Payload = {}> = {
|
|
|
97
50
|
key: string;
|
|
98
51
|
timestamp: number;
|
|
99
52
|
} & Payload;
|
|
100
|
-
type CacheReadHitEvent<T = any> = CacheEventBase<
|
|
53
|
+
type CacheReadHitEvent<T = any> = CacheEventBase<"cache:read:hit", {
|
|
101
54
|
data: T;
|
|
102
55
|
isStale: boolean;
|
|
103
56
|
}>;
|
|
104
|
-
type CacheReadMissEvent = CacheEventBase<
|
|
105
|
-
type CacheFetchStartEvent = CacheEventBase<
|
|
57
|
+
type CacheReadMissEvent = CacheEventBase<"cache:read:miss">;
|
|
58
|
+
type CacheFetchStartEvent = CacheEventBase<"cache:fetch:start", {
|
|
106
59
|
attempt: number;
|
|
107
60
|
}>;
|
|
108
|
-
type CacheFetchSuccessEvent<T = any> = CacheEventBase<
|
|
61
|
+
type CacheFetchSuccessEvent<T = any> = CacheEventBase<"cache:fetch:success", {
|
|
109
62
|
data: T;
|
|
110
63
|
}>;
|
|
111
|
-
type CacheFetchErrorEvent = CacheEventBase<
|
|
64
|
+
type CacheFetchErrorEvent = CacheEventBase<"cache:fetch:error", {
|
|
112
65
|
error: Error;
|
|
113
66
|
attempt: number;
|
|
114
67
|
}>;
|
|
115
|
-
type CacheDataEvictEvent = CacheEventBase<
|
|
68
|
+
type CacheDataEvictEvent = CacheEventBase<"cache:data:evict", {
|
|
116
69
|
reason?: string;
|
|
117
70
|
}>;
|
|
118
|
-
type CacheDataInvalidateEvent = CacheEventBase<
|
|
119
|
-
type CacheDataSetEvent<T = any> = CacheEventBase<
|
|
71
|
+
type CacheDataInvalidateEvent = CacheEventBase<"cache:data:invalidate">;
|
|
72
|
+
type CacheDataSetEvent<T = any> = CacheEventBase<"cache:data:set", {
|
|
120
73
|
newData: T;
|
|
121
74
|
oldData?: T;
|
|
122
75
|
}>;
|
|
123
|
-
type CachePersistenceLoadSuccessEvent = CacheEventBase<
|
|
76
|
+
type CachePersistenceLoadSuccessEvent = CacheEventBase<"cache:persistence:load:success", {
|
|
124
77
|
message?: string;
|
|
125
78
|
}>;
|
|
126
|
-
type CachePersistenceLoadErrorEvent = CacheEventBase<
|
|
79
|
+
type CachePersistenceLoadErrorEvent = CacheEventBase<"cache:persistence:load:error", {
|
|
127
80
|
message?: string;
|
|
128
81
|
error?: any;
|
|
129
82
|
}>;
|
|
130
|
-
type CachePersistenceSaveSuccessEvent = CacheEventBase<
|
|
131
|
-
type CachePersistenceSaveErrorEvent = CacheEventBase<
|
|
83
|
+
type CachePersistenceSaveSuccessEvent = CacheEventBase<"cache:persistence:save:success">;
|
|
84
|
+
type CachePersistenceSaveErrorEvent = CacheEventBase<"cache:persistence:save:error", {
|
|
132
85
|
message?: string;
|
|
133
86
|
error?: any;
|
|
134
87
|
}>;
|
|
135
|
-
type CachePersistenceClearSuccessEvent = CacheEventBase<
|
|
136
|
-
type CachePersistenceClearErrorEvent = CacheEventBase<
|
|
88
|
+
type CachePersistenceClearSuccessEvent = CacheEventBase<"cache:persistence:clear:success">;
|
|
89
|
+
type CachePersistenceClearErrorEvent = CacheEventBase<"cache:persistence:clear:error", {
|
|
137
90
|
message?: string;
|
|
138
91
|
error?: any;
|
|
139
92
|
}>;
|
|
140
|
-
type CachePersistenceSyncEvent = CacheEventBase<
|
|
93
|
+
type CachePersistenceSyncEvent = CacheEventBase<"cache:persistence:sync", {
|
|
141
94
|
message?: string;
|
|
142
95
|
}>;
|
|
143
96
|
type CacheEvent = CacheReadHitEvent | CacheReadMissEvent | CacheFetchStartEvent | CacheFetchSuccessEvent | CacheFetchErrorEvent | CacheDataEvictEvent | CacheDataInvalidateEvent | CacheDataSetEvent | CachePersistenceLoadSuccessEvent | CachePersistenceLoadErrorEvent | CachePersistenceSaveSuccessEvent | CachePersistenceSaveErrorEvent | CachePersistenceClearSuccessEvent | CachePersistenceClearErrorEvent | CachePersistenceSyncEvent;
|
|
144
|
-
type CacheEventType = CacheEvent[
|
|
97
|
+
type CacheEventType = CacheEvent["type"];
|
|
145
98
|
|
|
146
99
|
declare class QueryCache {
|
|
147
100
|
private cache;
|
package/index.d.ts
CHANGED
|
@@ -1,51 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
/**
|
|
3
|
-
* Persists data to storage.
|
|
4
|
-
*
|
|
5
|
-
* @param id The **unique identifier of the *consumer instance*** making the change. This is NOT the ID of the data (`T`) itself.
|
|
6
|
-
* Think of it as the ID of the specific browser tab, component, or module that's currently interacting with the persistence layer.
|
|
7
|
-
* It should typically be a **UUID** generated once at the consumer instance's instantiation.
|
|
8
|
-
* This `id` is crucial for the `subscribe` method, helping to differentiate updates originating from the current instance versus other instances/tabs, thereby preventing self-triggered notification loops.
|
|
9
|
-
* @param state The state (of type T) to persist. This state is generally considered the **global or shared state** that all instances interact with.
|
|
10
|
-
* @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations (like `IndexedDBPersistence`), this returns a `Promise<boolean>`.
|
|
11
|
-
*/
|
|
12
|
-
set(id: string, state: T): boolean | Promise<boolean>;
|
|
13
|
-
/**
|
|
14
|
-
* Retrieves the global persisted data from storage.
|
|
15
|
-
*
|
|
16
|
-
* @returns The retrieved state of type `T`, or `null` if no data is found or if an error occurs during retrieval/parsing.
|
|
17
|
-
* For asynchronous implementations, this returns a `Promise<T | null>`.
|
|
18
|
-
*/
|
|
19
|
-
get(): (T | null) | Promise<T | null>;
|
|
20
|
-
/**
|
|
21
|
-
* Subscribes to changes in the global persisted data that originate from *other* instances of your application (e.g., other tabs or independent components using the same persistence layer).
|
|
22
|
-
*
|
|
23
|
-
* @param id The **unique identifier of the *consumer instance* subscribing**. This allows the persistence implementation to filter out notifications that were initiated by the subscribing instance itself.
|
|
24
|
-
* @param callback The function to call when the global persisted data changes from *another* source. The new state (`T`) is passed as an argument to this callback.
|
|
25
|
-
* @returns A function that, when called, will unsubscribe the provided callback from future updates. Call this when your component or instance is no longer active to prevent memory leaks.
|
|
26
|
-
*/
|
|
27
|
-
subscribe(id: string, callback: (state: T) => void): () => void;
|
|
28
|
-
/**
|
|
29
|
-
* Clears (removes) the entire global persisted data from storage.
|
|
30
|
-
*
|
|
31
|
-
* @returns `true` if the operation was successful, `false` if an error occurred. For asynchronous implementations, this returns a `Promise<boolean>`.
|
|
32
|
-
*/
|
|
33
|
-
clear(): boolean | Promise<boolean>;
|
|
34
|
-
/**
|
|
35
|
-
* Returns metadata about the persistence layer.
|
|
36
|
-
*
|
|
37
|
-
* This is useful for distinguishing between multiple apps running on the same host
|
|
38
|
-
* (e.g., several apps served at `localhost:3000` that share the same storage key).
|
|
39
|
-
*
|
|
40
|
-
* @returns An object containing:
|
|
41
|
-
* - `version`: The semantic version string of the persistence schema or application.
|
|
42
|
-
* - `id`: A unique identifier for the application using this persistence instance.
|
|
43
|
-
*/
|
|
44
|
-
stats(): {
|
|
45
|
-
version: string;
|
|
46
|
-
id: string;
|
|
47
|
-
};
|
|
48
|
-
}
|
|
1
|
+
import { SimplePersistence } from '@core/persistence';
|
|
49
2
|
|
|
50
3
|
interface CacheOptions {
|
|
51
4
|
staleTime?: number;
|
|
@@ -97,51 +50,51 @@ type CacheEventBase<Type extends string, Payload = {}> = {
|
|
|
97
50
|
key: string;
|
|
98
51
|
timestamp: number;
|
|
99
52
|
} & Payload;
|
|
100
|
-
type CacheReadHitEvent<T = any> = CacheEventBase<
|
|
53
|
+
type CacheReadHitEvent<T = any> = CacheEventBase<"cache:read:hit", {
|
|
101
54
|
data: T;
|
|
102
55
|
isStale: boolean;
|
|
103
56
|
}>;
|
|
104
|
-
type CacheReadMissEvent = CacheEventBase<
|
|
105
|
-
type CacheFetchStartEvent = CacheEventBase<
|
|
57
|
+
type CacheReadMissEvent = CacheEventBase<"cache:read:miss">;
|
|
58
|
+
type CacheFetchStartEvent = CacheEventBase<"cache:fetch:start", {
|
|
106
59
|
attempt: number;
|
|
107
60
|
}>;
|
|
108
|
-
type CacheFetchSuccessEvent<T = any> = CacheEventBase<
|
|
61
|
+
type CacheFetchSuccessEvent<T = any> = CacheEventBase<"cache:fetch:success", {
|
|
109
62
|
data: T;
|
|
110
63
|
}>;
|
|
111
|
-
type CacheFetchErrorEvent = CacheEventBase<
|
|
64
|
+
type CacheFetchErrorEvent = CacheEventBase<"cache:fetch:error", {
|
|
112
65
|
error: Error;
|
|
113
66
|
attempt: number;
|
|
114
67
|
}>;
|
|
115
|
-
type CacheDataEvictEvent = CacheEventBase<
|
|
68
|
+
type CacheDataEvictEvent = CacheEventBase<"cache:data:evict", {
|
|
116
69
|
reason?: string;
|
|
117
70
|
}>;
|
|
118
|
-
type CacheDataInvalidateEvent = CacheEventBase<
|
|
119
|
-
type CacheDataSetEvent<T = any> = CacheEventBase<
|
|
71
|
+
type CacheDataInvalidateEvent = CacheEventBase<"cache:data:invalidate">;
|
|
72
|
+
type CacheDataSetEvent<T = any> = CacheEventBase<"cache:data:set", {
|
|
120
73
|
newData: T;
|
|
121
74
|
oldData?: T;
|
|
122
75
|
}>;
|
|
123
|
-
type CachePersistenceLoadSuccessEvent = CacheEventBase<
|
|
76
|
+
type CachePersistenceLoadSuccessEvent = CacheEventBase<"cache:persistence:load:success", {
|
|
124
77
|
message?: string;
|
|
125
78
|
}>;
|
|
126
|
-
type CachePersistenceLoadErrorEvent = CacheEventBase<
|
|
79
|
+
type CachePersistenceLoadErrorEvent = CacheEventBase<"cache:persistence:load:error", {
|
|
127
80
|
message?: string;
|
|
128
81
|
error?: any;
|
|
129
82
|
}>;
|
|
130
|
-
type CachePersistenceSaveSuccessEvent = CacheEventBase<
|
|
131
|
-
type CachePersistenceSaveErrorEvent = CacheEventBase<
|
|
83
|
+
type CachePersistenceSaveSuccessEvent = CacheEventBase<"cache:persistence:save:success">;
|
|
84
|
+
type CachePersistenceSaveErrorEvent = CacheEventBase<"cache:persistence:save:error", {
|
|
132
85
|
message?: string;
|
|
133
86
|
error?: any;
|
|
134
87
|
}>;
|
|
135
|
-
type CachePersistenceClearSuccessEvent = CacheEventBase<
|
|
136
|
-
type CachePersistenceClearErrorEvent = CacheEventBase<
|
|
88
|
+
type CachePersistenceClearSuccessEvent = CacheEventBase<"cache:persistence:clear:success">;
|
|
89
|
+
type CachePersistenceClearErrorEvent = CacheEventBase<"cache:persistence:clear:error", {
|
|
137
90
|
message?: string;
|
|
138
91
|
error?: any;
|
|
139
92
|
}>;
|
|
140
|
-
type CachePersistenceSyncEvent = CacheEventBase<
|
|
93
|
+
type CachePersistenceSyncEvent = CacheEventBase<"cache:persistence:sync", {
|
|
141
94
|
message?: string;
|
|
142
95
|
}>;
|
|
143
96
|
type CacheEvent = CacheReadHitEvent | CacheReadMissEvent | CacheFetchStartEvent | CacheFetchSuccessEvent | CacheFetchErrorEvent | CacheDataEvictEvent | CacheDataInvalidateEvent | CacheDataSetEvent | CachePersistenceLoadSuccessEvent | CachePersistenceLoadErrorEvent | CachePersistenceSaveSuccessEvent | CachePersistenceSaveErrorEvent | CachePersistenceClearSuccessEvent | CachePersistenceClearErrorEvent | CachePersistenceSyncEvent;
|
|
144
|
-
type CacheEventType = CacheEvent[
|
|
97
|
+
type CacheEventType = CacheEvent["type"];
|
|
145
98
|
|
|
146
99
|
declare class QueryCache {
|
|
147
100
|
private cache;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@asaidimu/utils-cache",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.1.1",
|
|
4
4
|
"description": "Resource and cache management utilities for @asaidimu applications.",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"module": "index.mjs",
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"access": "public"
|
|
31
31
|
},
|
|
32
32
|
"dependencies": {
|
|
33
|
-
"@asaidimu/utils-persistence": "
|
|
33
|
+
"@asaidimu/utils-persistence": "6.1.0",
|
|
34
34
|
"uuid": "^11.1.0",
|
|
35
35
|
"@asaidimu/events": "^1.1.1"
|
|
36
36
|
},
|