target-supabase-sdk 0.1.8 → 0.1.9

package/src/core.api.ts

@@ -1,7 +1,11 @@
 import { generateResponse, Target, TargetPayload } from "./core.interface";
-import { supabase } from ".";
+import { SupabaseInitializer } from "./supabase";
+
+const supabase = SupabaseInitializer.getInstance();
 import { BaseValidator, handleSupabaseError } from "./core.utils";
 import { PostgrestFilterBuilder } from "@supabase/postgrest-js";
+import type { ZodType } from "zod";
+import { ZodError } from "zod";
 
 export interface QueryFilter {
   field: string;
@@ -9,6 +13,85 @@ export interface QueryFilter {
   value: unknown;
 }
 
+export const MAX_TARGET_LIST_PAGE_SIZE = 100;
+
+/** Alias for {@link pollTargetList} batch size cap. */
+export const MAX_POLL_TARGET_LIST_SIZE = MAX_TARGET_LIST_PAGE_SIZE;
+
+const TARGET_LIST_ORDER_FIELDS = new Set<string>(["created_at", "name", "value", "category"]);
+
+// biome-ignore lint/suspicious/noExplicitAny: PostgrestFilterBuilder is generic over schema
+export type TargetFilterBuilder = PostgrestFilterBuilder<any, any, any[], "target", unknown>;
+
+function validateTargetListPagination(pageNum: number, pageSize: number): void {
+  if (!Number.isInteger(pageNum) || pageNum < 0) {
+    throw new Error(`[getTargetList] pageNum must be a non-negative integer, got ${pageNum}`);
+  }
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > MAX_TARGET_LIST_PAGE_SIZE) {
+    throw new Error(
+      `[getTargetList] pageSize must be an integer between 1 and ${MAX_TARGET_LIST_PAGE_SIZE}, got ${pageSize}`
+    );
+  }
+}
+
+function resolveTargetListPagination(params: {
+  pageNum?: number;
+  pageSize?: number;
+  limit?: number;
+}): {
+  pageNum: number;
+  pageSize: number;
+} {
+  if (params.limit != null) {
+    validateTargetListPagination(0, params.limit);
+    return { pageNum: 0, pageSize: params.limit };
+  }
+  if (params.pageNum === undefined || params.pageSize === undefined) {
+    throw new Error("[getTargetList] Provide pageNum and pageSize, or limit.");
+  }
+  validateTargetListPagination(params.pageNum, params.pageSize);
+  return { pageNum: params.pageNum, pageSize: params.pageSize };
+}
+
+function validateTargetListOrderBy(orderBy: QueryOrderBy): void {
+  if (!TARGET_LIST_ORDER_FIELDS.has(orderBy.field)) {
+    throw new Error(
+      `[getTargetList] Unsupported orderBy.field "${orderBy.field}"; allowed: ${[...TARGET_LIST_ORDER_FIELDS].join(", ")}`
+    );
+  }
+}
+
+/**
+ * 构建带 category 作用域的 target 查询（供 getTargetList / getTargetTotalCount / pollTargetList 共用）。
+ *
+ * 必要性：
+ * 1. category 是 target 表的分区维度，所有列表/计数/出队都必须限定 category，避免跨类型扫表。
+ * 2. 传入 filterBuilder 时仍强制 `.eq("category", category)`，防止自定义 builder 漏加 category 导致误查或安全问题。
+ * 3. 统一 select 普通列表与 count head 两种查询形态，再叠加 filterList，避免三处复制分支逻辑。
+ */
+function buildCategoryScopedQuery({
+  category,
+  filterList,
+  filterBuilder,
+  select,
+  selectOptions,
+}: {
+  category: Target["category"];
+  filterList: QueryFilter[];
+  filterBuilder?: TargetFilterBuilder;
+  select: string;
+  selectOptions?: { count: "exact"; head: true };
+}) {
+  const base =
+    filterBuilder != null
+      ? filterBuilder.eq("category", category)
+      : selectOptions != null
+        ? supabase.client.from("target").select(select, selectOptions).eq("category", category)
+        : supabase.client.from("target").select(select).eq("category", category);
+
+  return applyQueryFilters(base, filterList);
+}
+
 // biome-ignore lint/suspicious/noExplicitAny: PostgrestFilterBuilder is generic over schema
 function applyQueryFilter<Q extends PostgrestFilterBuilder<any, any, any, any, any>>(
   query: Q,
@@ -21,8 +104,10 @@ function applyQueryFilter<Q extends PostgrestFilterBuilder<any, any, any, any, a
       return query.neq(filter.field, filter.value) as Q;
     case "in":
       return query.in(filter.field, filter.value as unknown[]) as Q;
-    default:
-      return query;
+    default: {
+      const unsupportedOperator: never = filter.operator;
+      throw new Error(`[applyQueryFilter] Unsupported operator: ${unsupportedOperator}`);
+    }
   }
 }
 
@@ -68,55 +153,149 @@ export const getPossibleTarget = async ({ filterList }: { filterList: QueryFilte
 };
 
 export interface GetTargetListParams extends BaseQueryParams {
-  pageNum: number;
-  pageSize: number;
   category: Target["category"];
+  /** 0-based page index. Required with pageSize unless `limit` is set. */
+  pageNum?: number;
+  pageSize?: number;
+  /** Shorthand for `{ pageNum: 0, pageSize: limit }`. Max {@link MAX_TARGET_LIST_PAGE_SIZE}. */
+  limit?: number;
+  /** PostgREST select clause; defaults to `"*"`. */
+  selectFields?: string;
+  /** Custom query builder; `category` and `filterList` are still applied. */
+  filterBuilder?: TargetFilterBuilder;
 }
 
-export const getTargetList = async ({
+/**
+ * Paginated target list by category. Failures throw via `handleSupabaseError` (no `{ error }` envelope).
+ */
+export const getTargetList = async <T extends Target = Target>({
   pageNum,
   pageSize,
+  limit,
   category,
   filterList = [],
   orderBy = { field: "created_at", ascending: false },
+  selectFields = "*",
   filterBuilder,
-}: GetTargetListParams & {
-  // biome-ignore lint/suspicious/noExplicitAny: PostgrestFilterBuilder is generic over schema
-  filterBuilder?: PostgrestFilterBuilder<any, any, any[], "target", unknown>;
-}) => {
-  const query =
-    filterBuilder ??
-    applyQueryFilters(supabase.client.from("target").select("*").eq("category", category), filterList);
+}: GetTargetListParams) => {
+  const { pageNum: resolvedPageNum, pageSize: resolvedPageSize } = resolveTargetListPagination({
+    pageNum,
+    pageSize,
+    limit,
+  });
+  validateTargetListOrderBy(orderBy);
+
+  const query = buildCategoryScopedQuery({
+    category,
+    filterList,
+    filterBuilder,
+    select: selectFields,
+  });
 
   const { data, error } = await query
     .order(orderBy.field, { ascending: orderBy.ascending })
-    .range(pageNum * pageSize, (pageNum + 1) * pageSize - 1);
+    .range(resolvedPageNum * resolvedPageSize, (resolvedPageNum + 1) * resolvedPageSize - 1);
 
   if (error) {
     handleSupabaseError("getTargetList", error, "Failed to fetch target list.");
   }
-  return generateResponse.success<Target[]>(data);
+  return generateResponse.success<T[]>((data ?? []) as T[]);
+};
+
+export interface ScanTargetListParams {
+  category: Target["category"];
+  filterList?: QueryFilter[];
+  orderBy?: QueryOrderBy;
+  selectFields?: string;
+  filterBuilder?: TargetFilterBuilder;
+  /** Stop after this many rows (optional guard against runaway scans). */
+  maxRows?: number;
+}
+
+/**
+ * Scan all rows matching `category` + `filterList` by paging until exhausted.
+ *
+ * Use for worker bootstrap / sync jobs that need the full matching set.
+ * For UI pagination, use {@link getTargetList} (single page, explicit pageNum).
+ *
+ * Internal batch size is fixed at {@link MAX_TARGET_LIST_PAGE_SIZE} (PostgREST max-rows).
+ * Callers receive the full merged result; they do not pass a per-request page size.
+ *
+ * Uses offset pagination (`.range`). Stable enough for small catalogs (e.g. Repo registry);
+ * for large tables under concurrent writes, consider a DB RPC or keyset pagination later.
+ */
+export const scanTargetList = async <T extends Target = Target>({
+  category,
+  filterList = [],
+  orderBy = { field: "created_at", ascending: false },
+  selectFields = "*",
+  filterBuilder,
+  maxRows,
+}: ScanTargetListParams) => {
+  const batchSize = MAX_TARGET_LIST_PAGE_SIZE;
+  validateTargetListOrderBy(orderBy);
+  if (maxRows != null && (!Number.isInteger(maxRows) || maxRows < 1)) {
+    throw new Error(`[scanTargetList] maxRows must be a positive integer, got ${maxRows}`);
+  }
+
+  const rows: T[] = [];
+  let pageNum = 0;
+
+  while (true) {
+    const query = buildCategoryScopedQuery({
+      category,
+      filterList,
+      filterBuilder,
+      select: selectFields,
+    });
+
+    const { data, error } = await query
+      .order(orderBy.field, { ascending: orderBy.ascending })
+      .range(pageNum * batchSize, (pageNum + 1) * batchSize - 1);
+
+    if (error) {
+      handleSupabaseError("scanTargetList", error, "Failed to scan target list.");
+    }
+
+    const page = (data ?? []) as T[];
+    if (page.length === 0) {
+      break;
+    }
+
+    rows.push(...page);
+
+    if (maxRows != null && rows.length >= maxRows) {
+      rows.length = maxRows;
+      break;
+    }
+
+    if (page.length < batchSize) {
+      break;
+    }
+
+    pageNum += 1;
+  }
+
+  return generateResponse.success(rows);
 };
 
 export interface GetTargetTotalCountParams extends BaseQueryParams {
   category: Target["category"];
-  // biome-ignore lint/suspicious/noExplicitAny: PostgrestFilterBuilder is generic over schema
-  filterBuilder?: PostgrestFilterBuilder<any, any, any[], "target", unknown>;
+  /** Custom query builder; `category` and `filterList` are still applied. */
+  filterBuilder?: TargetFilterBuilder;
 }
 export const getTargetTotalCount = async ({
   category,
   filterList = [],
   filterBuilder,
 }: GetTargetTotalCountParams) => {
-  const query =
-    filterBuilder ??
-    applyQueryFilters(
-      supabase.client
-        .from("target")
-        .select("id", { count: "exact", head: true })
-        .eq("category", category),
-      filterList
-    );
+  const query = buildCategoryScopedQuery({
+    category,
+    filterList,
+    filterBuilder,
+    select: "id",
+    selectOptions: { count: "exact", head: true },
+  });
 
   const { count, error } = await query;
 
@@ -126,6 +305,76 @@ export const getTargetTotalCount = async ({
   return generateResponse.success<number>(count ?? 0);
 };
 
+function validatePollTargetListSize(size: number): void {
+  if (!Number.isInteger(size) || size < 1 || size > MAX_POLL_TARGET_LIST_SIZE) {
+    throw new Error(
+      `[pollTargetList] size must be an integer between 1 and ${MAX_POLL_TARGET_LIST_SIZE}, got ${size}`
+    );
+  }
+}
+
+export interface PollTargetListParams {
+  category: Target["category"];
+  /** Max rows to read and attempt dequeue (not offset pagination). */
+  size: number;
+  filterList?: QueryFilter[];
+  /** Order by `created_at`. Default `true` (oldest first). */
+  ascending?: boolean;
+  selectFields?: string;
+}
+
+/**
+ * Queue poll: SELECT up to `size` rows matching `category` + `filterList`, ordered by
+ * `created_at`, then DELETE each by `id`. Returns only dequeued rows (at-most-once).
+ *
+ * Delete failures (concurrent consumer) are skipped silently.
+ * Failures on the initial SELECT throw via `handleSupabaseError`.
+ *
+ * TODO(concurrency): 当前为 SELECT → 逐条 DELETE，非 DB 原子出队，多 consumer 并发时可能：
+ * - 重叠读取：两个 worker 同一批 SELECT 命中相同行，靠 DELETE 竞速，后者 skip（多数 at-most-once）
+ * - TOCTOU：SELECT 与 DELETE 之间无锁，极端情况下 DELETE 0 行仍不报错 → 可能重复计入 polled
+ * - 非 exactly-once：行已删但 worker 崩溃未处理 → 消息丢失
+ * 若同一 filter 多实例 poll（或多 worker 同 nodeId），需改为 DB 侧原子方案，例如：
+ * - RPC：`DELETE … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED) RETURNING *`
+ * - 或 claim 状态机：UPDATE … WHERE pending → DELETE/标记已消费（类似 patchClaimTask 乐观锁）
+ * - 短期加固：DELETE 后校验影响行数，0 行则不 push 到 polled
+ */
+export const pollTargetList = async <T extends Target = Target>({
+  category,
+  size,
+  filterList = [],
+  ascending = true,
+  selectFields = "*",
+}: PollTargetListParams) => {
+  validatePollTargetListSize(size);
+
+  const query = buildCategoryScopedQuery({
+    category,
+    filterList,
+    select: selectFields,
+  });
+
+  const { data, error } = await query.order("created_at", { ascending }).limit(size);
+
+  if (error) {
+    handleSupabaseError("pollTargetList", error, "Failed to fetch targets for poll.");
+  }
+
+  const candidates = (data ?? []) as T[];
+  const polled: T[] = [];
+
+  for (const row of candidates) {
+    try {
+      await deleteTarget({ id: row.id });
+      polled.push(row);
+    } catch {
+      // Concurrent dequeue — row already removed
+    }
+  }
+
+  return generateResponse.success<T[]>(polled);
+};
+
 export const deleteTarget = async ({ id, filterList }: { id: string; filterList?: QueryFilter[] }) => {
   // Check whether the target exists given filterList
   if (filterList != null && filterList.length > 0) {
@@ -413,3 +662,33 @@ export function validateWith<P extends object, V extends BaseValidator<P>>(Valid
     };
   };
 }
+
+function formatZodValidationError(schemaName: string, error: ZodError): Error {
+  const errorList = error.issues
+    .map((issue, index) => {
+      const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+      return `  ${index + 1}. ${path}: ${issue.message}`;
+    })
+    .join("\n");
+  const errorCount = error.issues.length;
+  return new Error(
+    `[${schemaName}] Validation failed (${errorCount} error${errorCount > 1 ? "s" : ""}):\n${errorList}`
+  );
+}
+
+/** Zod-based counterpart to {@link validateWith} — requires `zod` as a peer dependency. */
+export function validateWithSchema<T extends ZodType>(
+  schema: T,
+  schemaName = "Schema"
+) {
+  type Parsed = T["_output"];
+  return <R>(fn: (validPayload: Parsed) => R | Promise<R>) => {
+    return (payload: Parsed): R | Promise<R> => {
+      const result = schema.safeParse(payload);
+      if (!result.success) {
+        throw formatZodValidationError(schemaName, result.error);
+      }
+      return fn(result.data);
+    };
+  };
+}

package/src/file/file-manager.ts

@@ -142,4 +142,4 @@ const FileManager = {
     verifyFileHash,
 };
 
-export default FileManager;
+export { FileManager };

package/src/index.ts

@@ -24,7 +24,7 @@ export type {
   LifecycleStatus as ParcelLifecycleStatus,
   Lifecycle as ParcelLifecycle,
 } from "./parcel/parcel.interface";
-export { default as ParcelManager } from "./parcel/parcel-manager";
+export { ParcelManager } from "./parcel/parcel-manager";
 export type { StorageAdapter, ParcelTargetBase } from "./parcel/parcel-manager";
 
 export * from "./file/file.interface";
@@ -60,5 +60,20 @@ export * from "./list/list.api";
 export * from "./word/word.interface";
 
 export * from "./task/task.interface";
-
-export * from "./repo/repo.interface";
+export * from "./task/task.api";
+export { TaskManager } from "./task/task-manager";
+export type {
+    RegisterTasksOptions,
+    RegisterTasksResult,
+    PrepareTaskResponse,
+    PrepareTaskParams,
+    PrepareTaskFailureReason,
+} from "./task/task-manager";
+
+export * from "./node/node.interface";
+export * from "./node/node.api";
+export { NodeManager } from "./node/node-manager";
+
+export * from "./repo/repo.interface";
+export * from "./repo/repo.api";
+export { RepoManager } from "./repo/repo-manager";