api-core-lib 12.11.4 → 12.12.100
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 +1 -0
- package/bin/cli-launcher.cjs +14 -0
- package/dist/apiModule.types-dbmnauAt.d.cts +294 -0
- package/dist/apiModule.types-dbmnauAt.d.ts +294 -0
- package/dist/chunk-25UFVV4F.cjs +381 -0
- package/dist/chunk-KPZ7BF52.js +381 -0
- package/dist/cli.cjs +346 -0
- package/dist/client.cjs +547 -0
- package/dist/client.d.cts +50 -0
- package/dist/client.d.ts +50 -0
- package/dist/client.js +547 -0
- package/dist/index.cjs +298 -0
- package/dist/index.d.cts +241 -0
- package/dist/index.d.ts +66 -401
- package/dist/index.js +298 -1
- package/dist/server.cjs +56 -0
- package/dist/server.d.cts +25 -0
- package/dist/server.d.ts +25 -0
- package/dist/server.js +56 -0
- package/dist/useApiRecord.types-C06B5p4U.d.ts +90 -0
- package/dist/useApiRecord.types-HrabvzEQ.d.cts +90 -0
- package/package.json +50 -20
- package/dist/index.d.mts +0 -576
- package/dist/index.mjs +0 -1
package/dist/index.d.mts
DELETED
|
@@ -1,576 +0,0 @@
|
|
|
1
|
-
import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method, AxiosError } from 'axios';
|
|
2
|
-
import * as React$1 from 'react';
|
|
3
|
-
import React__default, { Dispatch, SetStateAction } from 'react';
|
|
4
|
-
|
|
5
|
-
/**
|
|
6
|
-
* يمثل معلومات الترقيم (Pagination) التي قد تعود من ה-API.
|
|
7
|
-
*/
|
|
8
|
-
interface PaginationMeta {
|
|
9
|
-
itemsPerPage: number;
|
|
10
|
-
totalItems: number;
|
|
11
|
-
currentPage: number;
|
|
12
|
-
totalPages: number;
|
|
13
|
-
[key: string]: any;
|
|
14
|
-
}
|
|
15
|
-
/**
|
|
16
|
-
* يمثل خطأ تحقق واحد لحقل معين.
|
|
17
|
-
*/
|
|
18
|
-
interface ValidationError {
|
|
19
|
-
field: string;
|
|
20
|
-
message: string;
|
|
21
|
-
}
|
|
22
|
-
/**
|
|
23
|
-
* يمثل كائن الخطأ الموحد الذي تنتجه المكتبة.
|
|
24
|
-
*/
|
|
25
|
-
interface ApiError {
|
|
26
|
-
message: string;
|
|
27
|
-
status: number;
|
|
28
|
-
code?: string;
|
|
29
|
-
errors?: ValidationError[];
|
|
30
|
-
requestId?: string;
|
|
31
|
-
}
|
|
32
|
-
/**
|
|
33
|
-
* الكائن القياسي والموحد الذي تعيده جميع دوال المكتبة.
|
|
34
|
-
* هذا هو النوع الأساسي الذي سيتعامل معه المطورون.
|
|
35
|
-
* @template T نوع البيانات الأساسية.
|
|
36
|
-
*/
|
|
37
|
-
interface StandardResponse<T> {
|
|
38
|
-
data: T | null;
|
|
39
|
-
links?: Record<string, string | null>;
|
|
40
|
-
meta?: PaginationMeta | Record<string, any>;
|
|
41
|
-
rawResponse: any;
|
|
42
|
-
error: ApiError | null;
|
|
43
|
-
loading: boolean;
|
|
44
|
-
success: boolean;
|
|
45
|
-
message?: string;
|
|
46
|
-
validationErrors?: ValidationError[];
|
|
47
|
-
}
|
|
48
|
-
interface Tokens {
|
|
49
|
-
accessToken: string | null;
|
|
50
|
-
refreshToken: string | null;
|
|
51
|
-
expiresAt?: number;
|
|
52
|
-
tokenType?: string;
|
|
53
|
-
}
|
|
54
|
-
interface TokenManager {
|
|
55
|
-
getTokens(): Promise<Tokens>;
|
|
56
|
-
setTokens(tokens: Tokens): Promise<void>;
|
|
57
|
-
clearTokens(): Promise<void>;
|
|
58
|
-
isHttpOnly(): boolean;
|
|
59
|
-
}
|
|
60
|
-
interface MiddlewareContext {
|
|
61
|
-
req: InternalAxiosRequestConfig;
|
|
62
|
-
res?: AxiosResponse;
|
|
63
|
-
error?: any;
|
|
64
|
-
custom?: Record<string, any>;
|
|
65
|
-
}
|
|
66
|
-
type Middleware = (context: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
|
|
67
|
-
type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
|
|
68
|
-
interface RefreshTokenConfig {
|
|
69
|
-
path: string;
|
|
70
|
-
buildRequestBody?: (refreshToken: string) => Record<string, any>;
|
|
71
|
-
buildRequestHeaders?: (currentTokens: Tokens) => Record<string, string>;
|
|
72
|
-
extractTokens: (responseData: any) => {
|
|
73
|
-
accessToken: string;
|
|
74
|
-
refreshToken?: string;
|
|
75
|
-
expiresIn: number;
|
|
76
|
-
tokenType?: string;
|
|
77
|
-
};
|
|
78
|
-
}
|
|
79
|
-
interface ApiClientConfig {
|
|
80
|
-
baseURL?: string;
|
|
81
|
-
tokenManager: TokenManager;
|
|
82
|
-
timeout?: number;
|
|
83
|
-
headers?: Record<string, string>;
|
|
84
|
-
withCredentials?: boolean;
|
|
85
|
-
refreshTokenConfig?: RefreshTokenConfig;
|
|
86
|
-
onRefreshError?: (error: any) => void;
|
|
87
|
-
middleware?: Middleware[];
|
|
88
|
-
logLevel?: LogLevel;
|
|
89
|
-
defaultIsPublic?: boolean;
|
|
90
|
-
maxTokenRefreshRetries?: number;
|
|
91
|
-
maxQueueSize?: number;
|
|
92
|
-
}
|
|
93
|
-
interface RequestConfig extends AxiosRequestConfig {
|
|
94
|
-
isPublic?: boolean;
|
|
95
|
-
cancelTokenKey?: string;
|
|
96
|
-
onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;
|
|
97
|
-
onDownloadProgress?: (progressEvent: AxiosProgressEvent) => void;
|
|
98
|
-
}
|
|
99
|
-
interface QueryOptions {
|
|
100
|
-
page?: number;
|
|
101
|
-
limit?: number;
|
|
102
|
-
search?: string;
|
|
103
|
-
sortBy?: {
|
|
104
|
-
key: string;
|
|
105
|
-
direction: 'asc' | 'desc';
|
|
106
|
-
}[];
|
|
107
|
-
filter?: Record<string, any>;
|
|
108
|
-
[key: string]: any;
|
|
109
|
-
}
|
|
110
|
-
interface ActionOptions extends RequestConfig {
|
|
111
|
-
endpoint?: string;
|
|
112
|
-
refetch?: boolean;
|
|
113
|
-
}
|
|
114
|
-
/**
|
|
115
|
-
* يمثل إعدادات إجراء واحد داخل الموديول.
|
|
116
|
-
*/
|
|
117
|
-
interface ActionConfig<TInput = any, TOutput = any> {
|
|
118
|
-
method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
|
|
119
|
-
path: string;
|
|
120
|
-
description?: string;
|
|
121
|
-
isList?: boolean;
|
|
122
|
-
invalidates?: string[];
|
|
123
|
-
}
|
|
124
|
-
/**
|
|
125
|
-
* [مُحدَّث] يمثل الحالة التفاعلية الكاملة لإجراء واحد.
|
|
126
|
-
* هذا هو النوع الذي يتم إرجاعه في `states` من الهوك.
|
|
127
|
-
*/
|
|
128
|
-
interface ActionStateModule<TOutput> {
|
|
129
|
-
data: TOutput | null;
|
|
130
|
-
links?: Record<string, string | null>;
|
|
131
|
-
meta?: PaginationMeta | Record<string, any>;
|
|
132
|
-
error: ApiError | null;
|
|
133
|
-
loading: boolean;
|
|
134
|
-
success: boolean;
|
|
135
|
-
called: boolean;
|
|
136
|
-
message?: string;
|
|
137
|
-
validationErrors?: ValidationError[];
|
|
138
|
-
rawResponse: any | null;
|
|
139
|
-
isStale?: boolean;
|
|
140
|
-
lastSuccessAt?: number;
|
|
141
|
-
}
|
|
142
|
-
/**
|
|
143
|
-
* الكائن الموحد الذي يتم إرجاعه لكل إجراء، ويحتوي على حالته ومنفذه وأدوات التحكم.
|
|
144
|
-
*/
|
|
145
|
-
interface ExecutableAction<TInput, TOutput> {
|
|
146
|
-
state: ActionStateModule<TOutput>;
|
|
147
|
-
execute: (input?: TInput, options?: {
|
|
148
|
-
pathParams?: Record<string, any>;
|
|
149
|
-
config?: AxiosRequestConfig;
|
|
150
|
-
query?: QueryOptions;
|
|
151
|
-
}) => Promise<StandardResponse<TOutput>>;
|
|
152
|
-
reset: () => void;
|
|
153
|
-
query?: UseApiQuery;
|
|
154
|
-
}
|
|
155
|
-
type UseApiState<T> = StandardResponse<T>;
|
|
156
|
-
interface UseApiQuery {
|
|
157
|
-
/** The current query options state. */
|
|
158
|
-
options: QueryOptions;
|
|
159
|
-
/** A function to set the entire query options object at once. */
|
|
160
|
-
setOptions: React__default.Dispatch<React__default.SetStateAction<QueryOptions>>;
|
|
161
|
-
/** Sets the current page number. */
|
|
162
|
-
setPage: (page: number) => void;
|
|
163
|
-
/** Sets the number of items per page and resets to the first page. */
|
|
164
|
-
setLimit: (limit: number) => void;
|
|
165
|
-
/** Sets the search term and resets to the first page. */
|
|
166
|
-
setSearchTerm: (search: string) => void;
|
|
167
|
-
/** Sets the sorting configuration. */
|
|
168
|
-
setSorting: (sortBy: {
|
|
169
|
-
key: string;
|
|
170
|
-
direction: 'asc' | 'desc';
|
|
171
|
-
}[]) => void;
|
|
172
|
-
/** Sets the filter object and resets to the first page. */
|
|
173
|
-
setFilters: (filter: Record<string, any>) => void;
|
|
174
|
-
/** Sets a single, custom query parameter. */
|
|
175
|
-
setQueryParam: (key: string, value: any) => void;
|
|
176
|
-
/** Resets the query options to their initial state. */
|
|
177
|
-
reset: () => void;
|
|
178
|
-
}
|
|
179
|
-
interface UseApiConfig<T> {
|
|
180
|
-
endpoint: string;
|
|
181
|
-
initialData?: T | null;
|
|
182
|
-
initialQuery?: QueryOptions;
|
|
183
|
-
enabled?: boolean;
|
|
184
|
-
refetchAfterChange?: boolean;
|
|
185
|
-
requestConfig?: RequestConfig;
|
|
186
|
-
pathParams?: Record<string, string | number>;
|
|
187
|
-
encodeQuery?: boolean;
|
|
188
|
-
onSuccess?: (message: string, data?: T) => void;
|
|
189
|
-
onError?: (message: string, error?: ApiError) => void;
|
|
190
|
-
}
|
|
191
|
-
|
|
192
|
-
declare function createApiClient(config: ApiClientConfig): AxiosInstance;
|
|
193
|
-
|
|
194
|
-
/** @description Extends the base ActionState with an `isStale` flag for automatic refetching. */
|
|
195
|
-
interface ActionState<TOutput> extends ActionStateModule<TOutput> {
|
|
196
|
-
isStale?: boolean;
|
|
197
|
-
}
|
|
198
|
-
/** @description Defines the configuration for a single API action within a module. */
|
|
199
|
-
interface ActionConfigModule<TInput = unknown, TOutput = unknown> {
|
|
200
|
-
method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
|
|
201
|
-
path: string;
|
|
202
|
-
description?: string;
|
|
203
|
-
hasQuery?: boolean;
|
|
204
|
-
autoFetch?: boolean;
|
|
205
|
-
invalidates?: string[];
|
|
206
|
-
_input?: TInput;
|
|
207
|
-
_output?: TOutput;
|
|
208
|
-
}
|
|
209
|
-
/** @description Defines the complete structure of an API module. */
|
|
210
|
-
interface ApiModuleConfig<TActions extends Record<string, ActionConfigModule<any, any>>> {
|
|
211
|
-
baseEndpoint: string;
|
|
212
|
-
actions: TActions;
|
|
213
|
-
}
|
|
214
|
-
/** @description Configuration options passed directly to the `useApiModule` hook. */
|
|
215
|
-
interface UseApiModuleOptions {
|
|
216
|
-
onSuccess?: (actionName: string, message: string, data: unknown) => void;
|
|
217
|
-
onError?: (actionName: string, message: string, error?: ApiError | null) => void;
|
|
218
|
-
refetchOnWindowFocus?: boolean;
|
|
219
|
-
pathParams?: Record<string, any>;
|
|
220
|
-
enabled?: boolean;
|
|
221
|
-
}
|
|
222
|
-
/** A utility type to infer the Input type (`TInput`) from an ActionConfigModule. */
|
|
223
|
-
type InputOf<TActionConfig> = TActionConfig extends ActionConfigModule<infer TInput, any> ? TInput : never;
|
|
224
|
-
/** A utility type to infer the Output type (`TOutput`) from an ActionConfigModule. */
|
|
225
|
-
type OutputOf<TActionConfig> = TActionConfig extends ActionConfigModule<any, infer TOutput> ? TOutput : never;
|
|
226
|
-
/** @description Defines the options for the `execute` function, enabling optimistic updates. */
|
|
227
|
-
interface ExecuteOptions<TInput, TOutput, TContext = unknown> {
|
|
228
|
-
pathParams?: Record<string, any>;
|
|
229
|
-
config?: AxiosRequestConfig;
|
|
230
|
-
onMutate?: (variables: TInput) => TContext | Promise<TContext>;
|
|
231
|
-
onSuccess?: (data: TOutput, context?: TContext) => void;
|
|
232
|
-
onError?: (error: ApiError, context?: TContext) => void;
|
|
233
|
-
}
|
|
234
|
-
/** @description A fully-typed object representing the callable actions for a module. */
|
|
235
|
-
type ModuleActions<TActions extends Record<string, ActionConfigModule<any, any>>> = {
|
|
236
|
-
[K in keyof TActions]: {
|
|
237
|
-
execute: <TContext = unknown>(input?: InputOf<TActions[K]>, options?: ExecuteOptions<InputOf<TActions[K]>, OutputOf<TActions[K]>, TContext>) => Promise<StandardResponse<OutputOf<TActions[K]>>>;
|
|
238
|
-
reset: (input?: InputOf<TActions[K]>, options?: {
|
|
239
|
-
pathParams?: Record<string, any>;
|
|
240
|
-
}) => void;
|
|
241
|
-
};
|
|
242
|
-
};
|
|
243
|
-
/** @description A fully-typed object representing the reactive states for each action in a module. */
|
|
244
|
-
type ModuleStates<TActions extends Record<string, ActionConfigModule<any, any>>> = {
|
|
245
|
-
[K in keyof TActions]: ActionState<OutputOf<TActions[K]>>;
|
|
246
|
-
};
|
|
247
|
-
/** @description The complete, fully-typed return object of the `useApiModule` hook. */
|
|
248
|
-
interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<any, any>>> {
|
|
249
|
-
states: ModuleStates<TActions>;
|
|
250
|
-
actions: ModuleActions<TActions>;
|
|
251
|
-
queries: {
|
|
252
|
-
[K in keyof TActions]?: TActions[K] extends {
|
|
253
|
-
hasQuery: true;
|
|
254
|
-
} ? UseApiQuery : never;
|
|
255
|
-
};
|
|
256
|
-
}
|
|
257
|
-
|
|
258
|
-
/**
|
|
259
|
-
* A factory function to create a reusable set of API services for a specific endpoint.
|
|
260
|
-
* It provides full CRUD operations plus advanced features like bulk deletion and file uploads,
|
|
261
|
-
* with intelligent, dynamic URL building.
|
|
262
|
-
*/
|
|
263
|
-
declare function createApiServices<T>(axiosInstance: AxiosInstance, baseEndpoint: string): {
|
|
264
|
-
get: (id?: string | number, config?: ActionOptions) => Promise<StandardResponse<T>>;
|
|
265
|
-
getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T>>;
|
|
266
|
-
post: (data: Partial<T>, config?: ActionOptions) => Promise<StandardResponse<T>>;
|
|
267
|
-
put: (id: string | number, data: T, config?: ActionOptions) => Promise<StandardResponse<T>>;
|
|
268
|
-
patch: (id: string | number, data: Partial<T>, config?: ActionOptions) => Promise<StandardResponse<T>>;
|
|
269
|
-
remove: (id: string | number, config?: ActionOptions) => Promise<StandardResponse<any>>;
|
|
270
|
-
bulkDelete: (ids: Array<string | number>, config?: ActionOptions) => Promise<StandardResponse<any>>;
|
|
271
|
-
upload: (file: File, additionalData?: Record<string, any>, config?: ActionOptions) => Promise<StandardResponse<any>>;
|
|
272
|
-
};
|
|
273
|
-
/**
|
|
274
|
-
* [نسخة محدثة ومحسّنة]
|
|
275
|
-
* دالة عامة وصريحة لتنفيذ أي طلب API.
|
|
276
|
-
* تستقبل وسائط منظمة بدلاً من محاولة تخمينها.
|
|
277
|
-
*
|
|
278
|
-
* @param axiosInstance - نسخة Axios.
|
|
279
|
-
* @param baseEndpoint - نقطة النهاية الأساسية للموديول.
|
|
280
|
-
* @param actionConfig - إعدادات الإجراء المحدد.
|
|
281
|
-
* @param params - كائن يحتوي على جميع البارامترات اللازمة للطلب.
|
|
282
|
-
* @returns Promise<StandardResponse<any>>
|
|
283
|
-
*/
|
|
284
|
-
declare function callDynamicApi(axiosInstance: AxiosInstance, baseEndpoint: string, actionConfig: ActionConfigModule<any, any>, params: {
|
|
285
|
-
pathParams?: Record<string, string | number>;
|
|
286
|
-
body?: any;
|
|
287
|
-
config?: AxiosRequestConfig;
|
|
288
|
-
}): Promise<StandardResponse<any>>;
|
|
289
|
-
|
|
290
|
-
/**
|
|
291
|
-
* [نسخة مطورة] يبني سلسلة استعلام (query string) من كائن الخيارات.
|
|
292
|
-
* يدعم الآن الفلاتر المتداخلة (filter[key]=value) والترتيب المتعدد.
|
|
293
|
-
* @param options - كائن خيارات الاستعلام (فلترة, ترتيب, ...).
|
|
294
|
-
* @returns سلسلة استعلام جاهزة للإضافة للرابط.
|
|
295
|
-
*/
|
|
296
|
-
declare function buildPaginateQuery(options: QueryOptions): string;
|
|
297
|
-
|
|
298
|
-
/**
|
|
299
|
-
* Defines a single custom API action.
|
|
300
|
-
* @template TRequest - The type of the data sent in the request body/params.
|
|
301
|
-
* @template TResponse - The type of the data expected in the successful API response.
|
|
302
|
-
*/
|
|
303
|
-
type ApiAction<TRequest, TResponse> = (payload: TRequest, config?: RequestConfig) => Promise<StandardResponse<TResponse>>;
|
|
304
|
-
/**
|
|
305
|
-
* A factory function to create a collection of typed, custom API actions.
|
|
306
|
-
*
|
|
307
|
-
* @template TActions - An object type where keys are action names and values are objects
|
|
308
|
-
* defining the endpoint, method, and types for that action.
|
|
309
|
-
* @param axiosInstance - The configured Axios instance from `createApiClient`.
|
|
310
|
-
* @param actionsConfig - An object defining the configuration for each custom action.
|
|
311
|
-
* @returns A fully-typed object of executable API action functions.
|
|
312
|
-
*
|
|
313
|
-
* @example
|
|
314
|
-
* const authActions = createApiActions(apiClient, {
|
|
315
|
-
* login: { method: 'POST', endpoint: '/auth/login', requestType: {} as LoginCredentials, responseType: {} as AuthResponse },
|
|
316
|
-
* getProfile: { method: 'GET', endpoint: '/user/profile', requestType: {} as void, responseType: {} as UserProfile }
|
|
317
|
-
* });
|
|
318
|
-
*
|
|
319
|
-
* // Usage:
|
|
320
|
-
* const result = await authActions.login({ email: '..', password: '..' });
|
|
321
|
-
*/
|
|
322
|
-
declare function createApiActions<TActions extends Record<string, {
|
|
323
|
-
method: Method;
|
|
324
|
-
endpoint: string;
|
|
325
|
-
requestType: any;
|
|
326
|
-
responseType: any;
|
|
327
|
-
log?: boolean;
|
|
328
|
-
}>>(axiosInstance: AxiosInstance, actionsConfig: TActions): {
|
|
329
|
-
[K in keyof TActions]: ApiAction<TActions[K]['requestType'], TActions[K]['responseType']>;
|
|
330
|
-
};
|
|
331
|
-
|
|
332
|
-
interface CacheItem<T> {
|
|
333
|
-
data: T;
|
|
334
|
-
timestamp: number;
|
|
335
|
-
duration: number;
|
|
336
|
-
}
|
|
337
|
-
declare class CacheManager {
|
|
338
|
-
private cache;
|
|
339
|
-
private defaultDuration;
|
|
340
|
-
set<T>(key: string, data: T, duration?: number): void;
|
|
341
|
-
get<T>(key: string): T | null;
|
|
342
|
-
/**
|
|
343
|
-
* [FIX] تم تحويلها إلى دالة عامة (generic) لتعيد النوع الصحيح.
|
|
344
|
-
* الآن بدلًا من إرجاع CacheItem<unknown>، ستُرجع CacheItem<T>.
|
|
345
|
-
*/
|
|
346
|
-
getWithMeta<T>(key: string): CacheItem<T> | null;
|
|
347
|
-
delete(key: string): void;
|
|
348
|
-
clear(): void;
|
|
349
|
-
invalidateByPrefix(prefix: string): void;
|
|
350
|
-
}
|
|
351
|
-
declare const cacheManager: CacheManager;
|
|
352
|
-
|
|
353
|
-
/**
|
|
354
|
-
* [النسخة النهائية والمضمونة]
|
|
355
|
-
* تستخدم دوال حماية النوع المخصصة للقضاء على أخطاء 'never' بشكل نهائي.
|
|
356
|
-
*/
|
|
357
|
-
declare const processResponse: <T>(responseOrError: AxiosResponse<any> | AxiosError) => StandardResponse<T>;
|
|
358
|
-
|
|
359
|
-
declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): any;
|
|
360
|
-
|
|
361
|
-
/**
|
|
362
|
-
* Represents the internal state of the `useApiRecord` hook.
|
|
363
|
-
* It mirrors the `StandardResponse` structure, which is the unified response format
|
|
364
|
-
* used across the library.
|
|
365
|
-
* @template T The data type of the record.
|
|
366
|
-
*/
|
|
367
|
-
type UseApiRecordState<T> = StandardResponse<T>;
|
|
368
|
-
/**
|
|
369
|
-
* Defines the action methods provided by the `useApiRecord` hook to interact with
|
|
370
|
-
* a single API resource.
|
|
371
|
-
* @template T The data type of the record.
|
|
372
|
-
*/
|
|
373
|
-
interface UseApiRecordActions<T> {
|
|
374
|
-
/**
|
|
375
|
-
* Manually fetches or refetches the record from the API.
|
|
376
|
-
*/
|
|
377
|
-
fetch: () => Promise<void>;
|
|
378
|
-
/**
|
|
379
|
-
* Partially updates the record using an HTTP PATCH request.
|
|
380
|
-
* @param updatedItem An object containing the fields to update.
|
|
381
|
-
* @param options Additional request options, allowing overrides for this specific action.
|
|
382
|
-
* @returns A promise that resolves to the standard response object for the updated record.
|
|
383
|
-
*/
|
|
384
|
-
update: (updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
|
|
385
|
-
/**
|
|
386
|
-
* Replaces the entire record with a new one using an HTTP PUT request.
|
|
387
|
-
* @param item The complete new record object.
|
|
388
|
-
* @param options Additional request options.
|
|
389
|
-
* @returns A promise that resolves to the standard response object for the replaced record.
|
|
390
|
-
*/
|
|
391
|
-
put: (item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
|
|
392
|
-
/**
|
|
393
|
-
* Deletes the record using an HTTP DELETE request.
|
|
394
|
-
* @param options Additional request options.
|
|
395
|
-
* @returns A promise that resolves to a standard response object with a null data payload.
|
|
396
|
-
*/
|
|
397
|
-
remove: (options?: ActionOptions) => Promise<StandardResponse<null>>;
|
|
398
|
-
/**
|
|
399
|
-
* Resets the hook's state to its initial value.
|
|
400
|
-
*/
|
|
401
|
-
resetState: () => void;
|
|
402
|
-
}
|
|
403
|
-
/**
|
|
404
|
-
* Defines the configuration options for the `useApiRecord` hook.
|
|
405
|
-
* @template T The data type of the record.
|
|
406
|
-
*/
|
|
407
|
-
interface UseApiRecordConfig<T> {
|
|
408
|
-
/**
|
|
409
|
-
* The base API endpoint template for the resource.
|
|
410
|
-
* Can contain placeholders like `{endpointName}`.
|
|
411
|
-
* @example 'v1/dynamic/{endpointName}'
|
|
412
|
-
*/
|
|
413
|
-
endpoint: string;
|
|
414
|
-
/**
|
|
415
|
-
* An object containing key-value pairs to replace placeholders in the endpoint template.
|
|
416
|
-
* @example { endpointName: 'products' }
|
|
417
|
-
*/
|
|
418
|
-
pathParams?: Record<string, string | number>;
|
|
419
|
-
/** The unique identifier of the record to fetch or modify. */
|
|
420
|
-
recordId?: string | number | null;
|
|
421
|
-
/** Optional initial data to populate the state before the first fetch is complete. */
|
|
422
|
-
initialData?: T | null;
|
|
423
|
-
/** If `false`, the hook will not automatically fetch data on mount. Defaults to `true`. */
|
|
424
|
-
enabled?: boolean;
|
|
425
|
-
/** If `true`, the record will be refetched after a successful `update`, `put`, or `remove` action. Defaults to `true`. */
|
|
426
|
-
refetchAfterChange?: boolean;
|
|
427
|
-
/** Default `RequestConfig` to apply to the initial GET request made by the hook. */
|
|
428
|
-
requestConfig?: RequestConfig;
|
|
429
|
-
/** A callback function executed on a successful API action. */
|
|
430
|
-
onSuccess?: (message: string, data?: any) => void;
|
|
431
|
-
/** A callback function executed on a failed API action. */
|
|
432
|
-
onError?: (message: string, error?: ApiError) => void;
|
|
433
|
-
}
|
|
434
|
-
/**
|
|
435
|
-
* The return value of the `useApiRecord` hook.
|
|
436
|
-
* @template T The data type of the record.
|
|
437
|
-
*/
|
|
438
|
-
interface UseApiRecordReturn<T> {
|
|
439
|
-
/** The current state of the API request, including data, loading, and error status. */
|
|
440
|
-
state: UseApiRecordState<T>;
|
|
441
|
-
/** Action methods to manipulate the record. */
|
|
442
|
-
actions: UseApiRecordActions<T>;
|
|
443
|
-
/** A React dispatch function to manually set the hook's state. Use with caution. */
|
|
444
|
-
setState: Dispatch<SetStateAction<UseApiRecordState<T>>>;
|
|
445
|
-
}
|
|
446
|
-
|
|
447
|
-
/**
|
|
448
|
-
* A React hook for managing the lifecycle of a single API resource (a record).
|
|
449
|
-
* It handles fetching, updating, replacing, and deleting a record, while managing
|
|
450
|
-
* loading, error, and data states. It supports dynamic path parameters for flexible API routing.
|
|
451
|
-
*
|
|
452
|
-
* @template T The data type of the record being managed.
|
|
453
|
-
* @param {AxiosInstance} axiosInstance - The configured Axios instance for making API calls.
|
|
454
|
-
* @param {UseApiRecordConfig<T>} config - Configuration options for the hook.
|
|
455
|
-
* @returns {UseApiRecordReturn<T>} An object containing the state, actions, and setState function.
|
|
456
|
-
*/
|
|
457
|
-
declare function useApiRecord<T>(axiosInstance: AxiosInstance, config: UseApiRecordConfig<T>): UseApiRecordReturn<T>;
|
|
458
|
-
|
|
459
|
-
type EffectCallback = () => (void | (() => void));
|
|
460
|
-
type DependencyList = readonly any[];
|
|
461
|
-
declare function useDeepCompareEffect(callback: EffectCallback, dependencies: DependencyList): void;
|
|
462
|
-
|
|
463
|
-
declare const ApiModuleProvider: React$1.Provider<UseApiModuleReturn<any> | null>;
|
|
464
|
-
declare function useModuleContext<TActions extends Record<string, ActionConfigModule<any, any>>>(): UseApiModuleReturn<TActions>;
|
|
465
|
-
declare function useApiModule<TActions extends Record<string, ActionConfigModule<any, any>>>(axiosInstance: AxiosInstance, moduleConfig: ApiModuleConfig<TActions>, options?: UseApiModuleOptions): UseApiModuleReturn<TActions>;
|
|
466
|
-
|
|
467
|
-
declare class GlobalStateManager {
|
|
468
|
-
private store;
|
|
469
|
-
/**
|
|
470
|
-
* يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
|
|
471
|
-
*/
|
|
472
|
-
getSnapshot<T>(key: string): ActionStateModule<T>;
|
|
473
|
-
/**
|
|
474
|
-
* يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
|
|
475
|
-
* @returns دالة لإلغاء الاشتراك.
|
|
476
|
-
*/
|
|
477
|
-
subscribe(key: string, callback: () => void): () => void;
|
|
478
|
-
/**
|
|
479
|
-
* يحدّث الحالة لمفتاح معين ويقوم بإعلام جميع المشتركين.
|
|
480
|
-
*/
|
|
481
|
-
setState<T>(key: string, updater: (prevState: ActionStateModule<T>) => ActionStateModule<T>): void;
|
|
482
|
-
/**
|
|
483
|
-
* يجعل البيانات المرتبطة بمفتاح معين "قديمة" (stale).
|
|
484
|
-
*/
|
|
485
|
-
invalidate(key: string): void;
|
|
486
|
-
/**
|
|
487
|
-
* [نسخة محدثة وأكثر قوة]
|
|
488
|
-
* يجعل كل البيانات التي تبدأ بمفتاح معين "قديمة" (stale).
|
|
489
|
-
* @example invalidateByPrefix('myModule/list::') سيبطل كل صفحات القائمة.
|
|
490
|
-
*/
|
|
491
|
-
invalidateByPrefix(prefix: string): void;
|
|
492
|
-
}
|
|
493
|
-
declare const globalStateManager: GlobalStateManager;
|
|
494
|
-
|
|
495
|
-
/**
|
|
496
|
-
* @file src/hooks/useApi.types.ts
|
|
497
|
-
* @description This file defines the professional, publicly-facing types for the `useApi` hook,
|
|
498
|
-
* providing a clean and stable contract for consumers.
|
|
499
|
-
*/
|
|
500
|
-
|
|
501
|
-
/**
|
|
502
|
-
* Configuration object for the `useApi` hook.
|
|
503
|
-
* @template T The type of the data entity.
|
|
504
|
-
*/
|
|
505
|
-
/**
|
|
506
|
-
* A collection of callable functions for performing CRUD and other operations.
|
|
507
|
-
* These actions automatically handle state updates like loading and refetching.
|
|
508
|
-
* @template T The type of the data entity being managed.
|
|
509
|
-
*/
|
|
510
|
-
interface UseApiActions<T, TListItem = T extends (infer U)[] ? U : T> {
|
|
511
|
-
fetch: (querryOptions?: QueryOptions) => Promise<void>;
|
|
512
|
-
create: (newItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
|
|
513
|
-
put: (id: string | number, item: TListItem, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
|
|
514
|
-
update: (id: string | number, updatedItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
|
|
515
|
-
remove: (id: string | number, options?: ActionOptions) => Promise<StandardResponse<any>>;
|
|
516
|
-
bulkRemove: (ids: Array<string | number>, options?: ActionOptions) => Promise<StandardResponse<any>>;
|
|
517
|
-
}
|
|
518
|
-
/**
|
|
519
|
-
* The complete return type of the `useApi` hook.
|
|
520
|
-
* It encapsulates the state, actions, and query controls for a given API resource.
|
|
521
|
-
* @template T The type of the data entity being managed.
|
|
522
|
-
*/
|
|
523
|
-
interface UseApiReturn<T> {
|
|
524
|
-
state: StandardResponse<T>;
|
|
525
|
-
setState: React.Dispatch<React.SetStateAction<StandardResponse<T>>>;
|
|
526
|
-
actions: UseApiActions<T>;
|
|
527
|
-
query: UseApiQuery;
|
|
528
|
-
}
|
|
529
|
-
|
|
530
|
-
type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
|
|
531
|
-
interface UseApiResourceState<T> {
|
|
532
|
-
data: T | T[] | null;
|
|
533
|
-
error: ApiError | null;
|
|
534
|
-
status: ApiResourceStatus;
|
|
535
|
-
isFetching: boolean;
|
|
536
|
-
isMutating: boolean;
|
|
537
|
-
isSuccess: boolean;
|
|
538
|
-
lastResponse?: StandardResponse<any>;
|
|
539
|
-
}
|
|
540
|
-
interface UseApiResourceActions<T, TCreate, TUpdate, TPathParams> {
|
|
541
|
-
fetch: (pathParams?: TPathParams, queryOptions?: QueryOptions) => Promise<StandardResponse<T[]>>;
|
|
542
|
-
fetchOne: (pathParams: TPathParams & {
|
|
543
|
-
id: string | number;
|
|
544
|
-
}, queryOptions?: QueryOptions) => Promise<StandardResponse<T>>;
|
|
545
|
-
create: (newItem: TCreate, pathParams?: TPathParams, options?: ActionOptions) => Promise<StandardResponse<T>>;
|
|
546
|
-
update: (id: string | number, updatedItem: TUpdate, pathParams?: TPathParams, options?: ActionOptions) => Promise<StandardResponse<T>>;
|
|
547
|
-
remove: (id: string | number, pathParams?: TPathParams, options?: ActionOptions) => Promise<StandardResponse<any>>;
|
|
548
|
-
reset: () => void;
|
|
549
|
-
}
|
|
550
|
-
interface UseApiResourceConfig<TPathParams> {
|
|
551
|
-
/**
|
|
552
|
-
* The API endpoint template. Can be a static string or a function
|
|
553
|
-
* that builds the URL from parameters.
|
|
554
|
-
* @example '/users'
|
|
555
|
-
* @example (params) => `/modules/${params.moduleName}/records`
|
|
556
|
-
*/
|
|
557
|
-
endpoint: string | ((params: TPathParams) => string);
|
|
558
|
-
/** Initial data to populate the state. */
|
|
559
|
-
initialData?: any;
|
|
560
|
-
/** Controls the verbosity of console logs for debugging. */
|
|
561
|
-
logLevel?: LogLevel;
|
|
562
|
-
/** Unique identifier for this hook instance, used in logging. */
|
|
563
|
-
logKey?: string;
|
|
564
|
-
/** Callback for success */
|
|
565
|
-
onSuccess?: (message: string, data?: any) => void;
|
|
566
|
-
/** Callback for error */
|
|
567
|
-
onError?: (message: string, error?: ApiError) => void;
|
|
568
|
-
}
|
|
569
|
-
interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
|
|
570
|
-
state: UseApiResourceState<T>;
|
|
571
|
-
actions: UseApiResourceActions<T, TCreate, TUpdate, TPathParams>;
|
|
572
|
-
query: UseApiQuery;
|
|
573
|
-
setQuery: React.Dispatch<React.SetStateAction<QueryOptions>>;
|
|
574
|
-
}
|
|
575
|
-
|
|
576
|
-
export { type ActionConfig, type ActionConfigModule, type ActionOptions, type ActionState, type ActionStateModule, type ApiClientConfig, type ApiError, type ApiModuleConfig, ApiModuleProvider, type ApiResourceStatus, type ExecutableAction, type ExecuteOptions, type InputOf, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, type ModuleStates, type OutputOf, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiModuleReturn, type UseApiQuery, type UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, callDynamicApi, createApiActions, createApiClient, createApiServices, globalStateManager, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect, useModuleContext };
|