@classytic/arc-next 0.4.1 → 0.5.0

package/dist/api.d.ts

@@ -67,7 +67,7 @@ interface BulkDeleteResponse {
 }
 type SortDirection = 1 | -1 | 'asc' | 'desc';
 type SortSpec = Record<string, SortDirection> | string;
-type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'regex' | 'like' | 'exists' | 'size' | 'type';
+type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'regex' | 'like' | 'exists' | 'size' | 'type' | 'between' | 'near' | 'nearSphere' | 'geoWithin' | 'withinRadius';
 interface QueryParams {
   page?: number;
   limit?: number;
@@ -97,6 +97,18 @@ interface RequestOptions {
   responseType?: 'json' | 'blob' | 'text';
   signal?: AbortSignal;
 }
+/**
+ * Common args every BaseApi-style method accepts: `token`, `organizationId`,
+ * and `options` (per-request RequestOptions minus the auth fields).
+ *
+ * Preset method signatures extend this so the auth-injection contract stays
+ * uniform across every call (BaseApi method, preset method, custom user wrapper).
+ */
+interface ScopedArgs {
+  token?: string | null;
+  organizationId?: string | null;
+  options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+}
 interface BaseApiConfig {
   basePath?: string;
   defaultParams?: {
@@ -187,154 +199,79 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     id,
     path,
     options
-  }: {
-    token?: string | null;
-    organizationId?: string | null;
+  }: ScopedArgs & {
     data: FormData; /** Resource ID — shorthand for path, appended as `baseUrl/{id}/upload` */
     id?: string; /** Custom sub-path appended as `baseUrl/{path}`. Takes precedence over `id`. */
     path?: string;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
   }): Promise<ApiResponse<TDoc>>;
-  search({
-    token,
-    organizationId,
-    searchParams,
-    params,
-    options
-  }?: {
-    token?: string | null;
-    organizationId?: string | null;
-    searchParams?: Record<string, unknown>;
-    params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<PaginatedResponse<TDoc>>;
-  findBy({
-    token,
-    organizationId,
-    field,
-    value,
-    operator,
-    params,
-    options
-  }: {
-    token?: string | null;
-    organizationId?: string | null;
-    field: string;
-    value: unknown;
-    operator?: FilterOperator;
-    params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<PaginatedResponse<TDoc>>;
   request<TResponse = unknown>(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', endpoint: string, {
     token,
     organizationId,
     data,
     params,
     options
-  }?: {
-    token?: string | null;
-    organizationId?: string | null;
+  }?: ScopedArgs & {
     data?: unknown;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
   }): Promise<TResponse>;
-  getDeleted({
+  /**
+   * Invoke a custom route mounted on this resource (e.g. `/todos/stats`,
+   * `/todos/recent`). Resource-relative wrapper around {@link request} that
+   * prepends `this.baseUrl` so callers don't have to remember the prefix.
+   *
+   * Use this for `defineResource({ routes: [{ method, path, handler }] })` —
+   * Arc's escape hatch for endpoints that don't fit CRUD or actions.
+   *
+   * For aggregates / reports, prefer the response-aware {@link useApiQuery} hook
+   * (which auto-unwraps `{ success, data }`) and pass `invokeRoute` as the queryFn.
+   *
+   * @example
+   * // GET /todos/stats → { success, data: { total, byStatus } }
+   * const stats = await api.invokeRoute<{ total: number; byStatus: Record<string, number> }>({
+   *   method: 'GET',
+   *   path: '/stats',
+   * });
+   *
+   * // GET /todos/recent?limit=5 → paginated shape spread to root
+   * const recent = await api.invokeRoute<PaginatedResponse<Todo>>({
+   *   method: 'GET',
+   *   path: '/recent',
+   *   params: { limit: 5 },
+   * });
+   *
+   * // POST /products/import — body + path
+   * await api.invokeRoute({
+   *   method: 'POST',
+   *   path: '/import',
+   *   data: { source: 'csv', items: [...] },
+   * });
+   */
+  invokeRoute<TResponse = unknown>({
     token,
     organizationId,
+    method,
+    path,
+    data,
     params,
     options
-  }?: {
-    token?: string | null;
-    organizationId?: string | null;
+  }: ScopedArgs & {
+    method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'; /** Path relative to the resource baseUrl. Leading slash optional. */
+    path: string;
+    data?: unknown;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<PaginatedResponse<TDoc>>;
-  restore({
+  }): Promise<TResponse>;
+  dispatchAction<TResult = unknown, TBody extends Record<string, unknown> = Record<string, unknown>>({
     token,
     organizationId,
     id,
-    options
-  }: {
-    token?: string | null;
-    organizationId?: string | null;
-    id: string;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<ApiResponse<TDoc>>;
-  bulkCreate({
-    token,
-    organizationId,
-    data,
-    options
-  }: {
-    token?: string | null;
-    organizationId?: string | null;
-    data: TCreate[];
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<BulkCreateResponse<TDoc>>;
-  bulkUpdate({
-    token,
-    organizationId,
-    filter,
+    action,
     data,
     options
-  }: {
-    token?: string | null;
-    organizationId?: string | null;
-    filter: Record<string, unknown>;
-    data: TUpdate;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<BulkUpdateResponse>;
-  bulkDelete({
-    token,
-    organizationId,
-    filter,
-    options
-  }: {
-    token?: string | null;
-    organizationId?: string | null;
-    filter: Record<string, unknown>;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<BulkDeleteResponse>;
-  getBySlug({
-    token,
-    organizationId,
-    slug,
-    params,
-    options
-  }: {
-    token?: string | null;
-    organizationId?: string | null;
-    slug: string;
-    params?: {
-      select?: string;
-      populate?: string | string[];
-    };
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<ApiResponse<TDoc>>;
-  getTree({
-    token,
-    organizationId,
-    params,
-    options
-  }?: {
-    token?: string | null;
-    organizationId?: string | null;
-    params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<ApiResponse<TDoc[]>>;
-  getChildren({
-    token,
-    organizationId,
-    parentId,
-    params,
-    options
-  }: {
-    token?: string | null;
-    organizationId?: string | null;
-    parentId: string;
-    params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<PaginatedResponse<TDoc>>;
+  }: ScopedArgs & {
+    id: string;
+    action: string;
+    data?: TBody;
+  }): Promise<ApiResponse<TResult>>;
 }
 declare function createCrudApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>>(entity: string, config?: BaseApiConfig): BaseApi<TDoc, TCreate, TUpdate>;
 type ExtractDoc<T> = T extends PaginatedResponse<infer D> ? D : never;
@@ -342,4 +279,4 @@ declare function isOffsetPagination<T>(response: PaginatedResponse<T>): response
 declare function isKeysetPagination<T>(response: PaginatedResponse<T>): response is KeysetPaginationResponse<T>;
 declare function isAggregatePagination<T>(response: PaginatedResponse<T>): response is AggregatePaginationResponse<T>;
 //#endregion
-export { AggregatePaginationResponse, ApiResponse, BaseApi, BaseApiConfig, BulkCreateResponse, BulkDeleteResponse, BulkUpdateResponse, DeleteResponse, ExtractDoc, FilterOperator, KeysetPaginationResponse, OffsetPaginationResponse, PaginatedResponse, PopulateOption, QueryParams, RequestOptions, SortDirection, SortSpec, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };
+export { AggregatePaginationResponse, ApiResponse, BaseApi, BaseApiConfig, BulkCreateResponse, BulkDeleteResponse, BulkUpdateResponse, DeleteResponse, ExtractDoc, FilterOperator, KeysetPaginationResponse, OffsetPaginationResponse, PaginatedResponse, PopulateOption, QueryParams, RequestOptions, ScopedArgs, SortDirection, SortSpec, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };

package/dist/api.js

@@ -63,7 +63,8 @@ var BaseApi = class {
 			}
 			if (value !== void 0 && value !== "") if (["page", "limit"].includes(key)) result[key] = parseInt(String(value)) || (key === "page" ? 1 : 10);
 			else if (Array.isArray(value)) {
-				if (value.length > 1) result[`${key}[in]`] = value.join(",");
+				if (/\[([^\]]+)\]$/.test(key)) result[key] = value.join(",");
+				else if (value.length > 1) result[`${key}[in]`] = value.join(",");
 				else if (value.length === 1) result[key] = value[0];
 			} else result[key] = value;
 		});
@@ -133,40 +134,6 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("POST", url, this.withHeaders(requestOptions));
 	}
-	async search({ token = null, organizationId = null, searchParams = {}, params = {}, options = {} } = {}) {
-		const queryParams = {
-			...this.config.defaultParams,
-			...params,
-			...searchParams
-		};
-		const processedParams = this.prepareParams(queryParams);
-		const queryString = this.createQueryString(processedParams);
-		const requestOptions = {
-			cache: this.config.cache,
-			...options
-		};
-		if (token) requestOptions.token = token;
-		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("GET", `${this.baseUrl}?${queryString}`, this.withHeaders(requestOptions));
-	}
-	async findBy({ token = null, organizationId = null, field, value, operator, params = {}, options = {} }) {
-		if (!field || value === void 0) throw new Error("Field and value are required");
-		const queryParams = {
-			...this.config.defaultParams,
-			...params
-		};
-		if (operator) queryParams[`${field}[${operator}]`] = Array.isArray(value) ? value.join(",") : value;
-		else queryParams[field] = value;
-		const processedParams = this.prepareParams(queryParams);
-		const queryString = this.createQueryString(processedParams);
-		const requestOptions = {
-			cache: this.config.cache,
-			...options
-		};
-		if (token) requestOptions.token = token;
-		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("GET", `${this.baseUrl}?${queryString}`, this.withHeaders(requestOptions));
-	}
 	async request(method, endpoint, { token = null, organizationId = null, data, params, options = {} } = {}) {
 		let url = endpoint;
 		if (params) {
@@ -182,96 +149,63 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn(method, url, this.withHeaders(requestOptions));
 	}
-	async getDeleted({ token = null, organizationId = null, params = {}, options = {} } = {}) {
-		const mergedParams = {
-			...this.config.defaultParams,
-			...params
-		};
-		const processedParams = this.prepareParams(mergedParams);
-		const queryString = this.createQueryString(processedParams);
-		const requestOptions = {
-			cache: this.config.cache,
-			...options
-		};
-		if (token) requestOptions.token = token;
-		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("GET", `${this.baseUrl}/deleted?${queryString}`, this.withHeaders(requestOptions));
+	/**
+	* Invoke a custom route mounted on this resource (e.g. `/todos/stats`,
+	* `/todos/recent`). Resource-relative wrapper around {@link request} that
+	* prepends `this.baseUrl` so callers don't have to remember the prefix.
+	*
+	* Use this for `defineResource({ routes: [{ method, path, handler }] })` —
+	* Arc's escape hatch for endpoints that don't fit CRUD or actions.
+	*
+	* For aggregates / reports, prefer the response-aware {@link useApiQuery} hook
+	* (which auto-unwraps `{ success, data }`) and pass `invokeRoute` as the queryFn.
+	*
+	* @example
+	* // GET /todos/stats → { success, data: { total, byStatus } }
+	* const stats = await api.invokeRoute<{ total: number; byStatus: Record<string, number> }>({
+	*   method: 'GET',
+	*   path: '/stats',
+	* });
+	*
+	* // GET /todos/recent?limit=5 → paginated shape spread to root
+	* const recent = await api.invokeRoute<PaginatedResponse<Todo>>({
+	*   method: 'GET',
+	*   path: '/recent',
+	*   params: { limit: 5 },
+	* });
+	*
+	* // POST /products/import — body + path
+	* await api.invokeRoute({
+	*   method: 'POST',
+	*   path: '/import',
+	*   data: { source: 'csv', items: [...] },
+	* });
+	*/
+	async invokeRoute({ token = null, organizationId = null, method = "GET", path, data, params, options = {} }) {
+		if (!path) throw new Error("path is required");
+		const normalized = path.startsWith("/") ? path : `/${path}`;
+		const endpoint = `${this.baseUrl}${normalized}`;
+		return this.request(method, endpoint, {
+			token,
+			organizationId,
+			data,
+			params,
+			options
+		});
 	}
-	async restore({ token = null, organizationId = null, id, options = {} }) {
+	async dispatchAction({ token = null, organizationId = null, id, action, data, options = {} }) {
 		if (!id) throw new Error("ID is required");
-		const requestOptions = { ...options };
-		if (token) requestOptions.token = token;
-		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("POST", `${this.baseUrl}/${id}/restore`, this.withHeaders(requestOptions));
-	}
-	async bulkCreate({ token = null, organizationId = null, data, options = {} }) {
-		const requestOptions = {
-			body: data,
-			...options
-		};
-		if (token) requestOptions.token = token;
-		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("POST", `${this.baseUrl}/bulk`, this.withHeaders(requestOptions));
-	}
-	async bulkUpdate({ token = null, organizationId = null, filter, data, options = {} }) {
+		if (!action) throw new Error("Action name is required");
 		const requestOptions = {
 			body: {
-				filter,
-				data
+				action,
+				...data ?? {}
 			},
 			...options
 		};
 		if (token) requestOptions.token = token;
 		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("PATCH", `${this.baseUrl}/bulk`, this.withHeaders(requestOptions));
-	}
-	async bulkDelete({ token = null, organizationId = null, filter, options = {} }) {
-		const requestOptions = {
-			body: { filter },
-			...options
-		};
-		if (token) requestOptions.token = token;
-		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("DELETE", `${this.baseUrl}/bulk`, this.withHeaders(requestOptions));
-	}
-	async getBySlug({ token = null, organizationId = null, slug, params = {}, options = {} }) {
-		if (!slug) throw new Error("Slug is required");
-		const queryString = this.createQueryString(params);
-		const url = queryString ? `${this.baseUrl}/slug/${slug}?${queryString}` : `${this.baseUrl}/slug/${slug}`;
-		const requestOptions = {
-			cache: this.config.cache,
-			...options
-		};
-		if (token) requestOptions.token = token;
-		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("GET", url, this.withHeaders(requestOptions));
-	}
-	async getTree({ token = null, organizationId = null, params = {}, options = {} } = {}) {
-		const processedParams = this.prepareParams(params);
-		const queryString = this.createQueryString(processedParams);
-		const requestOptions = {
-			cache: this.config.cache,
-			...options
-		};
-		if (token) requestOptions.token = token;
-		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("GET", `${this.baseUrl}/tree?${queryString}`, this.withHeaders(requestOptions));
-	}
-	async getChildren({ token = null, organizationId = null, parentId, params = {}, options = {} }) {
-		if (!parentId) throw new Error("Parent ID is required");
-		const mergedParams = {
-			...this.config.defaultParams,
-			...params
-		};
-		const processedParams = this.prepareParams(mergedParams);
-		const queryString = this.createQueryString(processedParams);
-		const requestOptions = {
-			cache: this.config.cache,
-			...options
-		};
-		if (token) requestOptions.token = token;
-		if (organizationId) requestOptions.organizationId = organizationId;
-		return this.requestFn("GET", `${this.baseUrl}/${parentId}/children?${queryString}`, this.withHeaders(requestOptions));
+		return this.requestFn("POST", `${this.baseUrl}/${id}/action`, this.withHeaders(requestOptions));
 	}
 };
 function createCrudApi(entity, config = {}) {

package/dist/cache.d.ts

@@ -0,0 +1,108 @@
+import { QueryClient, QueryKey } from "@tanstack/react-query";
+
+//#region src/cache.d.ts
+interface PaginationData {
+  /** Pagination method detected from response (offset | keyset | aggregate) */
+  method: 'offset' | 'keyset' | 'aggregate' | null;
+  total: number;
+  pages: number;
+  page: number;
+  limit: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+  /** Keyset cursor for next page (keyset pagination only) */
+  next?: string | null;
+}
+declare const DEFAULT_QUERY_CONFIG: {
+  readonly staleTime: number;
+  readonly gcTime: number;
+  readonly refetchOnWindowFocus: false;
+  readonly retry: 0;
+};
+/** Pre-built query config presets for common data freshness patterns. */
+declare const QUERY_CONFIGS: {
+  /** Live data: 20s stale, 30s polling */readonly realtime: {
+    readonly staleTime: 20000;
+    readonly refetchInterval: 30000;
+  }; /** Frequently updated: 60s stale */
+  readonly frequent: {
+    readonly staleTime: 60000;
+  }; /** Stable data: 5min stale (same as default) */
+  readonly stable: {
+    readonly staleTime: 300000;
+  }; /** Rarely changes: 10min stale */
+  readonly static: {
+    readonly staleTime: 600000;
+  };
+};
+/**
+ * Extract `_id` or `id` from any item. Returns `null` if neither exists.
+ * Coerces numeric IDs to strings so cache keys stay consistent.
+ */
+declare function getItemId(item: unknown): string | null;
+/**
+ * Normalize any pagination response shape (offset / keyset / aggregate) to a
+ * uniform `PaginationData` object. Returns `null` when no pagination signal
+ * is present.
+ */
+declare function normalizePagination(data: unknown): PaginationData | null;
+/**
+ * Permissive list extractor. Checks well-known keys (`docs`, `data`, `items`,
+ * `results`) then falls back to *any* top-level array — so `{ products: [...] }`
+ * and `{ users: [...] }` work without per-resource configuration.
+ */
+declare function extractItems<T>(data: unknown): T[];
+/**
+ * Strict detail extractor. Checks well-known keys (`data`, `doc`, `item`,
+ * `result`); falls back to returning the response as-is. Primitive responses
+ * (string/number/boolean) pass through.
+ */
+declare function extractItem<T>(data: unknown): T | null;
+/**
+ * Optimistic-update helper that mutates the items array of a list cache
+ * regardless of which key holds it. Auto-adjusts `total`/`totalDocs` when
+ * the array length changes.
+ */
+declare function updateListCache<T>(listData: unknown, updater: (items: T[]) => T[]): unknown;
+interface QueryKeys {
+  all: string[];
+  lists: () => QueryKey;
+  list: (params?: unknown) => QueryKey;
+  details: () => QueryKey;
+  detail: (id: string) => QueryKey;
+  /** Tenant-scoped detail key. Use when IDs are only unique within an org. */
+  scopedDetail: (id: string, organizationId: string | null) => QueryKey;
+  custom: (key: string, ...args: unknown[]) => QueryKey;
+  scopedList: (scope: string, params?: unknown) => QueryKey;
+}
+/**
+ * Build a hierarchical query-key factory for a resource. The returned shape
+ * is identical between server (prefetch) and client (hooks), so RSC SSR
+ * hydration matches what client-side `useList`/`useDetail` produce.
+ */
+declare function createQueryKeys(entityKey: string): QueryKeys;
+interface CacheUtils<T> {
+  invalidateAll: (client: QueryClient) => Promise<void>;
+  invalidateLists: (client: QueryClient) => Promise<void>;
+  /** Invalidate detail by ID (prefix-matches all scoped/parameterized variants). */
+  invalidateDetail: (client: QueryClient, id: string) => Promise<void>;
+  setDetail: (client: QueryClient, id: string, data: T) => void;
+  getDetail: (client: QueryClient, id: string) => T | undefined;
+  removeDetail: (client: QueryClient, id: string) => void;
+  /** Invalidate tenant-scoped detail (prefix-matches parameterized variants within org). */
+  invalidateScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => Promise<void>;
+  /** Set tenant-scoped detail cache. */
+  setScopedDetail: (client: QueryClient, id: string, organizationId: string | null, data: T) => void;
+  /** Get tenant-scoped detail from cache. */
+  getScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => T | undefined;
+  /** Remove tenant-scoped detail from cache. */
+  removeScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => void;
+}
+/**
+ * Build cache read/write/invalidate helpers bound to the given key factory.
+ * Server-safe — operates on a `QueryClient` instance which can be a per-request
+ * server client (during prefetch) or the browser singleton.
+ */
+declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
+//#endregion
+export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache };