@svadmin/core 0.83.0 → 0.84.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/src/cursor-list-controller.ts +209 -0
- package/src/index.ts +3 -1
package/package.json
CHANGED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
import { createCursorPageCache, type CursorPage, type CursorPageCache, type CursorProvider } from './cursor-provider';
|
|
2
|
+
|
|
3
|
+
export interface CursorListRequestOptions {
|
|
4
|
+
signal: AbortSignal;
|
|
5
|
+
bypassCache: boolean;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
export interface CursorListState<TQuery, TItem> {
|
|
9
|
+
/** 最近成功应用的查询;范围变更后的首次成功读取之前 initialized 为 false。 */
|
|
10
|
+
readonly query: TQuery;
|
|
11
|
+
readonly queryKey: string;
|
|
12
|
+
readonly scopeKey: string;
|
|
13
|
+
readonly items: readonly TItem[];
|
|
14
|
+
readonly page: number;
|
|
15
|
+
readonly initialized: boolean;
|
|
16
|
+
readonly hasPrevious: boolean;
|
|
17
|
+
readonly hasNext: boolean;
|
|
18
|
+
readonly loading: boolean;
|
|
19
|
+
readonly requestedPage: number | null;
|
|
20
|
+
readonly error: unknown;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** code 可供宿主本地化;message 仅作为 provider 协议错误的诊断。 */
|
|
24
|
+
export class CursorListError extends Error {
|
|
25
|
+
readonly code = 'CURSOR_NOT_ADVANCING';
|
|
26
|
+
constructor() {
|
|
27
|
+
super('The provider returned a non-advancing cursor.');
|
|
28
|
+
this.name = 'CursorListError';
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface CursorListController<TQuery, TItem> {
|
|
33
|
+
readonly state: CursorListState<TQuery, TItem>;
|
|
34
|
+
/** Svelte store-compatible subscription; the first snapshot is synchronous. */
|
|
35
|
+
subscribe(listener: (state: CursorListState<TQuery, TItem>) => void): () => void;
|
|
36
|
+
next(): Promise<boolean>;
|
|
37
|
+
previous(): Promise<boolean>;
|
|
38
|
+
/** queryKey 包含有效筛选、排序和每页条数;scopeKey 变化立即清除旧范围。 */
|
|
39
|
+
setQuery(query: TQuery, queryKey: string, scopeKey?: string): Promise<boolean>;
|
|
40
|
+
/** 显式查询/清除入口:即使条件不变也重新读取第一页。 */
|
|
41
|
+
resetQuery(query: TQuery, queryKey: string, scopeKey?: string): Promise<boolean>;
|
|
42
|
+
refresh(options?: { resetToFirstPage?: boolean }): Promise<boolean>;
|
|
43
|
+
retry(): Promise<boolean>;
|
|
44
|
+
cancel(): void;
|
|
45
|
+
dispose(): void;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
interface PageRequest<TQuery, TItem> {
|
|
49
|
+
query: TQuery;
|
|
50
|
+
queryKey: string;
|
|
51
|
+
scopeKey: string;
|
|
52
|
+
page: number;
|
|
53
|
+
bypassCache: boolean;
|
|
54
|
+
cache: CursorPageCache<TItem>;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* An opt-in cursor list store, independent of Svelte, transport and DOM APIs.
|
|
59
|
+
* Query values must be immutable; callers own the semantic query and scope keys.
|
|
60
|
+
* Returns true only when a request or cached navigation commits a page.
|
|
61
|
+
*/
|
|
62
|
+
export function createCursorListController<TQuery, TItem>(options: {
|
|
63
|
+
provider: CursorProvider<TQuery, TItem, CursorListRequestOptions>;
|
|
64
|
+
query: TQuery;
|
|
65
|
+
queryKey: string;
|
|
66
|
+
/** 资源、provider 或授权范围变化时必须更换此键。 */
|
|
67
|
+
scopeKey: string;
|
|
68
|
+
}): CursorListController<TQuery, TItem> {
|
|
69
|
+
let cache = createCursorPageCache<TItem>();
|
|
70
|
+
const listeners = new Set<(state: CursorListState<TQuery, TItem>) => void>();
|
|
71
|
+
let state: CursorListState<TQuery, TItem> = {
|
|
72
|
+
query: options.query, queryKey: options.queryKey, scopeKey: options.scopeKey,
|
|
73
|
+
items: [], page: 1, initialized: false, hasPrevious: false, hasNext: false,
|
|
74
|
+
loading: false, requestedPage: null, error: null,
|
|
75
|
+
};
|
|
76
|
+
let generation = 0;
|
|
77
|
+
let pending: { controller: AbortController; cancel: () => void; intent: PageRequest<TQuery, TItem> } | null = null;
|
|
78
|
+
let failedRequest: PageRequest<TQuery, TItem> | null = null;
|
|
79
|
+
let disposed = false;
|
|
80
|
+
|
|
81
|
+
function publish(patch: Partial<CursorListState<TQuery, TItem>>): void {
|
|
82
|
+
state = { ...state, ...patch };
|
|
83
|
+
for (const listener of listeners) listener(state);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
function abort(): void {
|
|
87
|
+
generation += 1;
|
|
88
|
+
const request = pending;
|
|
89
|
+
pending = null;
|
|
90
|
+
request?.cancel();
|
|
91
|
+
request?.controller.abort();
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function currentPageRequest(page: number, bypassCache = false): PageRequest<TQuery, TItem> {
|
|
95
|
+
return { query: state.query, queryKey: state.queryKey, scopeKey: state.scopeKey, page, bypassCache, cache };
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function matchesApplied(intent: PageRequest<TQuery, TItem>): boolean {
|
|
99
|
+
return intent.queryKey === state.queryKey && intent.scopeKey === state.scopeKey;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
async function load(intent: PageRequest<TQuery, TItem>): Promise<boolean> {
|
|
103
|
+
if (disposed || state.loading) return false;
|
|
104
|
+
const { query, queryKey, scopeKey, page, bypassCache } = intent;
|
|
105
|
+
const cursor = intent.cache.cursorForPage(page);
|
|
106
|
+
if (cursor === undefined) return false;
|
|
107
|
+
const request = new AbortController();
|
|
108
|
+
const currentGeneration = ++generation;
|
|
109
|
+
let settleCancellation: () => void = () => {};
|
|
110
|
+
const cancelled = new Promise<null>(resolve => { settleCancellation = () => resolve(null); });
|
|
111
|
+
const current = () => !disposed && currentGeneration === generation && !request.signal.aborted;
|
|
112
|
+
pending = { controller: request, cancel: settleCancellation, intent };
|
|
113
|
+
failedRequest = null;
|
|
114
|
+
publish({ loading: true, requestedPage: page, error: null });
|
|
115
|
+
try {
|
|
116
|
+
if (!current()) return false;
|
|
117
|
+
const cached = bypassCache ? undefined : intent.cache.page(page);
|
|
118
|
+
// 取消先结束控制器动作;迟到的 provider 响应或异常仍由 race 接收,不提交状态。
|
|
119
|
+
const result: CursorPage<TItem> | null = cached ?? await Promise.race([
|
|
120
|
+
options.provider.getList({ query, cursor, options: { signal: request.signal, bypassCache } }),
|
|
121
|
+
cancelled,
|
|
122
|
+
]);
|
|
123
|
+
if (!result || !current()) return false;
|
|
124
|
+
if (result.nextCursor !== null && result.nextCursor === cursor) throw new CursorListError();
|
|
125
|
+
if (!cached) intent.cache.save(page, result);
|
|
126
|
+
cache = intent.cache;
|
|
127
|
+
// 页码、查询、记录与游标链在同一有效成功响应后一起提交。
|
|
128
|
+
publish({
|
|
129
|
+
query, queryKey, scopeKey, items: result.items, page, initialized: true,
|
|
130
|
+
hasPrevious: page > 1, hasNext: Boolean(result.nextCursor),
|
|
131
|
+
loading: false, requestedPage: null, error: null,
|
|
132
|
+
});
|
|
133
|
+
return true;
|
|
134
|
+
} catch (error) {
|
|
135
|
+
if (!current()) return false;
|
|
136
|
+
failedRequest = intent;
|
|
137
|
+
publish({ loading: false, requestedPage: null, error });
|
|
138
|
+
return false;
|
|
139
|
+
} finally {
|
|
140
|
+
if (currentGeneration === generation) pending = null;
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function applyQuery(query: TQuery, queryKey: string, scopeKey: string, force = false): Promise<boolean> {
|
|
145
|
+
if (disposed) return Promise.resolve(false);
|
|
146
|
+
if (pending?.intent.queryKey === queryKey && pending.intent.scopeKey === scopeKey
|
|
147
|
+
&& (!force || pending.intent.page === 1)) return Promise.resolve(false);
|
|
148
|
+
if (!force && queryKey === state.queryKey && scopeKey === state.scopeKey) {
|
|
149
|
+
// 用户回到已应用查询时取消另一个在途查询,不让其稍后覆盖当前结果。
|
|
150
|
+
if ((pending && !matchesApplied(pending.intent)) || (failedRequest && !matchesApplied(failedRequest))) {
|
|
151
|
+
abort();
|
|
152
|
+
failedRequest = null;
|
|
153
|
+
publish({ loading: false, requestedPage: null, error: null });
|
|
154
|
+
}
|
|
155
|
+
return Promise.resolve(false);
|
|
156
|
+
}
|
|
157
|
+
abort();
|
|
158
|
+
const nextCache = createCursorPageCache<TItem>();
|
|
159
|
+
failedRequest = null;
|
|
160
|
+
if (scopeKey !== state.scopeKey) {
|
|
161
|
+
cache = nextCache;
|
|
162
|
+
publish({ query, queryKey, scopeKey, items: [], page: 1, initialized: false,
|
|
163
|
+
hasPrevious: false, hasNext: false, loading: false, requestedPage: null, error: null });
|
|
164
|
+
} else {
|
|
165
|
+
publish({ loading: false, requestedPage: null, error: null });
|
|
166
|
+
}
|
|
167
|
+
return load({ query, queryKey, scopeKey, page: 1, bypassCache: force, cache: nextCache });
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
return {
|
|
171
|
+
get state() { return state; },
|
|
172
|
+
subscribe(listener) {
|
|
173
|
+
if (disposed) return () => {};
|
|
174
|
+
listeners.add(listener);
|
|
175
|
+
listener(state);
|
|
176
|
+
return () => { listeners.delete(listener); };
|
|
177
|
+
},
|
|
178
|
+
next() {
|
|
179
|
+
return state.hasNext ? load(currentPageRequest(state.page + 1)) : Promise.resolve(false);
|
|
180
|
+
},
|
|
181
|
+
previous() {
|
|
182
|
+
return state.hasPrevious ? load(currentPageRequest(state.page - 1)) : Promise.resolve(false);
|
|
183
|
+
},
|
|
184
|
+
setQuery(query, queryKey, scopeKey = state.scopeKey) {
|
|
185
|
+
return applyQuery(query, queryKey, scopeKey);
|
|
186
|
+
},
|
|
187
|
+
resetQuery(query, queryKey, scopeKey = state.scopeKey) {
|
|
188
|
+
return applyQuery(query, queryKey, scopeKey, true);
|
|
189
|
+
},
|
|
190
|
+
refresh(refreshOptions = {}) {
|
|
191
|
+
return load(currentPageRequest(refreshOptions.resetToFirstPage ? 1 : state.page, true));
|
|
192
|
+
},
|
|
193
|
+
retry() {
|
|
194
|
+
return failedRequest ? load(failedRequest) : Promise.resolve(false);
|
|
195
|
+
},
|
|
196
|
+
cancel() {
|
|
197
|
+
if (disposed) return;
|
|
198
|
+
abort();
|
|
199
|
+
publish({ loading: false, requestedPage: null });
|
|
200
|
+
},
|
|
201
|
+
dispose() {
|
|
202
|
+
if (disposed) return;
|
|
203
|
+
disposed = true;
|
|
204
|
+
abort();
|
|
205
|
+
listeners.clear();
|
|
206
|
+
state = { ...state, loading: false, requestedPage: null };
|
|
207
|
+
},
|
|
208
|
+
};
|
|
209
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -247,6 +247,8 @@ export type { AdminOptions, TextTransformers, OvertimeConfig } from './options.s
|
|
|
247
247
|
export { checkError } from './hook-utils.svelte';
|
|
248
248
|
export type { NotificationConfig, OvertimeOptions, OvertimeResult, LiveSubscriptionParams } from './hook-utils.svelte';
|
|
249
249
|
export { createCursorPageCache, createCursorProvider } from './cursor-provider';
|
|
250
|
+
export { createCursorListController, CursorListError } from './cursor-list-controller';
|
|
251
|
+
export type { CursorListController, CursorListState, CursorListRequestOptions } from './cursor-list-controller';
|
|
250
252
|
export type { CursorPage, CursorPageCache, CursorPageFetcher, CursorProvider, CursorProviderInput } from './cursor-provider';
|
|
251
253
|
|
|
252
254
|
export { CRUD_FIELD_OPERATORS, DeleteManyPartialError, HttpError, UndoError, isCrudFieldOperator } from './types';
|
|
@@ -318,7 +320,7 @@ export type { UseExportOptions } from './export-hooks.svelte';
|
|
|
318
320
|
export { useImport } from './import-hooks.svelte';
|
|
319
321
|
export type { ImportArtifact, ImportArtifactProvider, ImportTaskResult, ImportPreviewFailure, ImportPreviewResult } from './import-contract';
|
|
320
322
|
export { snapshotImportArtifact, snapshotImportTaskResult, invalidImportPreviewFailure } from './import-contract';
|
|
321
|
-
export { IMPORT_LIMITS } from './import-contract';
|
|
323
|
+
export { IMPORT_LIMITS, parseImportRows } from './import-contract';
|
|
322
324
|
export type { UseImportOptions, ImportProgress, ImportResult } from './import-hooks.svelte';
|
|
323
325
|
export type { ExportFormat } from './data-transfer.svelte';
|
|
324
326
|
export {
|