target-supabase-sdk 0.2.0 → 0.2.2

package/src/task/task-post-validated.api.ts

@@ -0,0 +1,47 @@
+import { validateWithSchema } from "../core.api";
+import { generateResponse, type SupabaseResponse } from "../core.interface";
+import { createLogger, logManager } from "../shared/log";
+import type { Task } from "./task.interface";
+import { createTaskRow, postTaskSchema } from "./task-post.api";
+import { TaskRepoValidation } from "./task-repo-validation";
+
+/**
+ * Create a task row with publish-time Repo + params validation.
+ * **Node entry only** — requires local Repo bootstrap and {@link TaskRepoValidation}.
+ *
+ * @see target-supabase-sdk/node
+ */
+export const postTaskWithValidation = validateWithSchema(
+    postTaskSchema,
+    "postTaskSchema",
+)(async ({ name, value, params, taskStatus, tagList, extra, traceId, traceParentId }) => {
+    const taskTraceId = traceId?.trim() || logManager.generateTraceId();
+    const logger = createLogger({
+        module: "postTaskWithValidation",
+        traceId: taskTraceId,
+        traceParentId: traceParentId ?? null,
+    });
+
+    const validation = await TaskRepoValidation.validate({
+        logger,
+        taskTypeKey: value,
+        params,
+        bootstrapLocal: true,
+    });
+    if (!validation.isValid) {
+        logger.warn(validation.message, {
+            topic: "task",
+            data: {
+                taskTypeKey: value,
+                reason: validation.reason,
+                step: validation.step,
+            },
+        });
+        return generateResponse.error(validation.message, undefined, String(validation.code)) as SupabaseResponse<Task>;
+    }
+
+    return createTaskRow(
+        { name, value, params, taskStatus, tagList, extra, traceId, traceParentId, taskTraceId },
+        logger,
+    );
+});

package/src/task/task-post.api.ts

@@ -1,116 +1,99 @@
-import { createTarget, validateWithSchema } from "../core.api";
-import { generateResponse, type SupabaseResponse } from "../core.interface";
-import { createApiLogger, logManager } from "../shared/log";
 import { z } from "zod";
-import { CategoryTask, ResultCode, Task, TaskStatus } from "./task.interface";
-import { TaskRepoValidation } from "./task-repo-validation";
+import { createTarget, validateWithSchema } from "../core.api";
+import type { SupabaseResponse } from "../core.interface";
+import { createLogger, type LoggerWithScope, logManager } from "../shared/log";
+import { CategoryTask, type Task, TaskStatus } from "./task.interface";
 
 const traceIdSchema = z.string().trim().min(1).optional();
 const traceParentIdSchema = z.string().trim().min(1).nullable().optional();
 
 /** Initial status for a new task — OPEN (draft) or TODO (claimable by workers). */
 const postTaskInitialStatusSchema = z
-	.union([z.literal(TaskStatus.OPEN), z.literal(TaskStatus.TODO)])
-	.optional()
-	.default(TaskStatus.TODO);
+    .union([z.literal(TaskStatus.OPEN), z.literal(TaskStatus.TODO)])
+    .optional()
+    .default(TaskStatus.TODO);
 
 export const postTaskSchema = z.object({
-	name: z.string().trim().min(1),
-	/** Task type key — matches `task.value`, {@link patchClaimTask}, {@link Repo.value}, and local Repo registry. */
-	value: z.string().trim().min(1),
-	params: z.unknown(),
-	taskStatus: postTaskInitialStatusSchema,
-	tagList: z.array(z.string()).optional().default([]),
-	extra: z.string().optional(),
-	traceId: traceIdSchema,
-	traceParentId: traceParentIdSchema,
+    name: z.string().trim().min(1),
+    /** Task type key — matches `task.value`, {@link patchClaimTask}, {@link Repo.value}, and local Repo registry. */
+    value: z.string().trim().min(1),
+    params: z.unknown(),
+    taskStatus: postTaskInitialStatusSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+    traceId: traceIdSchema,
+    traceParentId: traceParentIdSchema,
 });
 
 export type PostTaskPayload = z.infer<typeof postTaskSchema>;
 
-/**
- * Create a task row (scheduler / admin). **Node entry only** — requires local Repo bootstrap.
- *
- * @see target-supabase-sdk/node
- */
-export const postTask = validateWithSchema(
-	postTaskSchema,
-	"postTaskSchema",
-)(async ({
-	name,
-	value,
-	params,
-	taskStatus,
-	tagList,
-	extra,
-	traceId,
-	traceParentId,
-}) => {
-	const taskTraceId = traceId?.trim() || logManager.generateTraceId();
-	const logger = createApiLogger("postTask", {
-		traceId: taskTraceId,
-		traceParentId: traceParentId ?? null,
-	});
+export type CreateTaskRowInput = PostTaskPayload & {
+    taskTraceId: string;
+};
 
-	const validation = await TaskRepoValidation.validate({
-		logger,
-		taskTypeKey: value,
-		params,
-		bootstrapLocal: true,
-	});
-	if (!validation.isValid) {
-		logger.warn(validation.message, {
-			topic: "task",
-			data: {
-				taskTypeKey: value,
-				reason: validation.reason,
-				step: validation.step,
-			},
-		});
-		return generateResponse.error(
-			validation.message,
-			undefined,
-			String(validation.code),
-		) as SupabaseResponse<Task>;
-	}
+/** Shared DB insert for {@link postTask} and {@link postTaskWithValidation}. */
+export async function createTaskRow(
+    { name, value, params, taskStatus, tagList, extra, taskTraceId, traceParentId }: CreateTaskRowInput,
+    logger: LoggerWithScope,
+): Promise<SupabaseResponse<Task>> {
+    const result = await createTarget<Task, PostTaskPayload>({
+        payload: {
+            name,
+            value,
+            params,
+            taskStatus,
+            tagList,
+            extra,
+            traceId: taskTraceId,
+            traceParentId,
+        },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryTask.TASK,
+            tagList,
+            extra,
+            details: {
+                manifestVersion: 0,
+                status: taskStatus,
+                params,
+                progress: 0,
+                nodeId: null,
+                traceId: taskTraceId,
+            },
+        }),
+    });
 
-	const result = await createTarget<Task, PostTaskPayload>({
-		payload: {
-			name,
-			value,
-			params,
-			taskStatus,
-			tagList,
-			extra,
-			traceId: taskTraceId,
-			traceParentId,
-		},
-		createFn: () => ({
-			name,
-			value,
-			category: CategoryTask.TASK,
-			tagList,
-			extra,
-			details: {
-				manifestVersion: 0,
-				status: taskStatus,
-				params,
-				progress: 0,
-				nodeId: null,
-				traceId: taskTraceId,
-			},
-		}),
-	});
+    logger.info("任務已創建", {
+        topic: "task",
+        data: {
+            taskId: result.data?.id,
+            taskTypeKey: value,
+            status: taskStatus,
+            traceId: taskTraceId,
+        },
+    });
 
-	logger.info("任務已創建", {
-		topic: "task",
-		data: {
-			taskId: result.data?.id,
-			taskTypeKey: value,
-			status: taskStatus,
-			traceId: taskTraceId,
-		},
-	});
+    return result;
+}
+
+/**
+ * Create a task row (scheduler / admin). **Browser and Node** — no Repo or params validation.
+ * Execution-time checks live in {@link TaskManager.prepareTask}.
+ */
+export const postTask = validateWithSchema(
+    postTaskSchema,
+    "postTaskSchema",
+)(async ({ name, value, params, taskStatus, tagList, extra, traceId, traceParentId }) => {
+    const taskTraceId = traceId?.trim() || logManager.generateTraceId();
+    const logger = createLogger({
+        module: "postTask",
+        traceId: taskTraceId,
+        traceParentId: traceParentId ?? null,
+    });
 
-	return result;
+    return createTaskRow(
+        { name, value, params, taskStatus, tagList, extra, traceId, traceParentId, taskTraceId },
+        logger,
+    );
 });

package/src/task/task-queue.ts

@@ -0,0 +1,18 @@
+import type { Task, TaskStatus } from "./task.interface";
+
+export type TaskStatusCount = Partial<Record<TaskStatus, number>>;
+
+/** Count tasks of `taskType` grouped by each requested status. */
+export function countTasksByType(tasks: Task[], taskType: string, statuses: TaskStatus[]): TaskStatusCount {
+    const filtered = tasks.filter((task) => task.value === taskType);
+    const counts: TaskStatusCount = {};
+    for (const status of statuses) {
+        counts[status] = filtered.filter((task) => task.details.status === status).length;
+    }
+    return counts;
+}
+
+/** Total tasks of `taskType` whose status is in `statuses`. */
+export function summarizeTaskQueue(tasks: Task[], taskType: string, statuses: TaskStatus[]): number {
+    return tasks.filter((task) => task.value === taskType && statuses.includes(task.details.status)).length;
+}

package/src/task/task-repo-context.ts

@@ -96,7 +96,8 @@ export const TASK_RUNNER_CONFIG_DIR = "config" as const;
 export const TASK_RUNNER_ROOT_CONFIG_FILENAME = "task.config.js" as const;
 
 /** Default root config path: `config/task.config.js` */
-export const TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH = `${TASK_RUNNER_CONFIG_DIR}/${TASK_RUNNER_ROOT_CONFIG_FILENAME}` as const;
+export const TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH =
+    `${TASK_RUNNER_CONFIG_DIR}/${TASK_RUNNER_ROOT_CONFIG_FILENAME}` as const;
 
 /** Legacy fallback at project root */
 export const TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH = TASK_RUNNER_ROOT_CONFIG_FILENAME;

package/src/task/task-repo-validation.ts

@@ -1,6 +1,6 @@
-import { RepoManager, type RepoContextFailureReason } from "../repo/repo-manager";
-import { LoggerWithScope } from "../shared/log";
-import { bootstrapLocalTasks, type BootstrapLocalTasksOptions } from "./local-task-registry";
+import { type RepoContextFailureReason, RepoManager } from "../repo/repo-manager";
+import type { LoggerWithScope } from "../shared/log";
+import { type BootstrapLocalTasksOptions, bootstrapLocalTasks } from "./local-task-registry";
 import { ResultCode } from "./task.interface";
 import type { TaskRepoContext } from "./task-repo-context";
 
@@ -15,7 +15,7 @@ export type ValidateTaskRepoAndParamsInput = {
     taskTypeKey: string;
     params: unknown;
     /**
-     * When true, run {@link bootstrapLocalTasks} before resolve (CLI / Trigger / postTask).
+     * When true, run {@link bootstrapLocalTasks} before resolve (CLI / Trigger / postTaskWithValidation).
      * Worker paths should omit — {@link TaskManager.registerTasks} already bootstrapped.
      */
     bootstrapLocal?: boolean;
@@ -40,14 +40,12 @@ export type ValidateTaskRepoAndParamsSuccess = {
     repoContext: TaskRepoContext;
 };
 
-export type ValidateTaskRepoAndParamsResult =
-    | ValidateTaskRepoAndParamsFailure
-    | ValidateTaskRepoAndParamsSuccess;
+export type ValidateTaskRepoAndParamsResult = ValidateTaskRepoAndParamsFailure | ValidateTaskRepoAndParamsSuccess;
 
 function validateTaskParams(
     validator: TaskRepoContext["taskParamsValidator"],
     taskParams: unknown,
-    logger: LoggerWithScope
+    logger: LoggerWithScope,
 ): boolean {
     try {
         return validator(taskParams) === true;

package/src/task/task.api.ts

@@ -1,8 +1,18 @@
-import { createTarget, getPossibleTarget, QueryFilter, updateTargetDetails, validateWithSchema, isOptimisticLockError, OPTIMISTIC_LOCK_FAILED_MESSAGE } from "../core.api";
-import { generateResponse, type SupabaseResponse } from "../core.interface";
-import { createApiLogger, logManager, type LoggerWithScope } from "../shared/log";
 import { z } from "zod";
-import { CategoryTask, ResultCode, Task, TaskDetails, TaskStatus, TaskStatusAction } from "./task.interface";
+import {
+    getTargetList,
+    isOptimisticLockError,
+    OPTIMISTIC_LOCK_ERROR_CODE,
+    OPTIMISTIC_LOCK_FAILED_MESSAGE,
+    type QueryFilter,
+    updateTargetDetails,
+    validateWithSchema,
+} from "../core.api";
+import { generateResponse, type SupabaseResponse } from "../core.interface";
+import { createLogger, type LoggerWithScope } from "../shared/log";
+import { getErrorMessage } from "../shared/utils/error.utils";
+import { LOG_TOPIC_TASK } from "./task.constant";
+import { CategoryTask, ResultCode, type Task, type TaskDetails, TaskStatus, TaskStatusAction } from "./task.interface";
 
 const TASK_STATUS_FIELD = "details->>status" as const;
 const TASK_NODE_ID_FIELD = "details->>nodeId" as const;
@@ -46,7 +56,7 @@ const taskIdSchema = z.string().trim().min(1);
 const nodeIdSchema = z.string().trim().min(1);
 /** Optional — orchestrator (e.g. TaskNode loop) passes its trace to correlate logs. */
 const traceIdSchema = z.string().trim().min(1).optional();
-const traceParentIdSchema = z.string().trim().min(1).nullable().optional();
+const _traceParentIdSchema = z.string().trim().min(1).nullable().optional();
 
 const patchChangeTaskStatusBaseSchema = {
     id: taskIdSchema,
@@ -163,10 +173,10 @@ function logTaskTransition(
     logger: LoggerWithScope,
     action: TaskStatusAction | "patchTaskProgress" | "patchClaimTask",
     task: Task,
-    data?: Record<string, unknown>
+    data?: Record<string, unknown>,
 ): void {
-    logger.info("任务状态迁移成功", {
-        topic: "task",
+    logger.debug("任務狀態遷移成功", {
+        topic: LOG_TOPIC_TASK,
         data: {
             action,
             taskId: task.id,
@@ -204,9 +214,9 @@ async function claimTaskById({
 
 export const patchChangeTaskStatus = validateWithSchema(
     patchChangeTaskStatusSchema,
-    "patchChangeTaskStatusSchema"
+    "patchChangeTaskStatusSchema",
 )(async (params) => {
-    const logger = createApiLogger("patchChangeTaskStatus", { traceId: params.traceId });
+    const logger = createLogger({ module: "patchChangeTaskStatus", traceId: params.traceId });
     const { id, action, extra } = params;
     const updateExtraFn = extra == null ? undefined : () => extra;
 
@@ -308,9 +318,9 @@ export const patchChangeTaskStatus = validateWithSchema(
 /** Update progress on a DOING task; only the owning node may write (see `lockOnDoingOwner`). */
 export const patchTaskProgress = validateWithSchema(
     patchTaskProgressSchema,
-    "patchTaskProgressSchema"
+    "patchTaskProgressSchema",
 )(async ({ id, progress, nodeId, traceId }) => {
-    const logger = createApiLogger("patchTaskProgress", { traceId, labels: { nodeId } });
+    const logger = createLogger({ module: "patchTaskProgress", traceId, labels: { nodeId } });
     const data = await transitionTask({
         id,
         optimisticLockFilterList: lockOnDoingOwner(nodeId),
@@ -328,42 +338,68 @@ export const patchTaskProgress = validateWithSchema(
 /**
  * Discover and claim one TODO task for this node.
  *
- * Flow: filter by `availableTaskList` → {@link claimTaskById} (same as `action: CLAIM`).
+ * Flow: oldest TODO in `availableTaskList` (FIFO by `created_at`) → {@link claimTaskById}.
  * Equivalent to `patchChangeTaskStatus({ id, action: CLAIM, nodeId })` when `id` is already known.
  *
  * Returns `data: null` when no TODO task matches.
- * Optimistic lock conflicts return `{ error }` with `code: "OPTIMISTIC_LOCK"` (not thrown).
+ * Optimistic lock conflicts return `{ error, code: OPTIMISTIC_LOCK_ERROR_CODE }` (not thrown).
  */
 export const patchClaimTask = validateWithSchema(
     patchClaimTaskSchema,
-    "patchClaimTaskSchema"
+    "patchClaimTaskSchema",
 )(async ({ nodeId, availableTaskList, traceId }): Promise<SupabaseResponse<Task | null>> => {
-    const logger = createApiLogger("patchClaimTask", { traceId, labels: { nodeId } });
+    const logger = createLogger({ module: "patchClaimTask", traceId, labels: { nodeId } });
 
+    let todoTask: Task;
     try {
-        const { data: possibleTask } = await getPossibleTarget({
+        const { data: taskCandidates } = await getTargetList<Task>({
+            category: CategoryTask.TASK,
             filterList: [
-                { field: "category", operator: "eq", value: CategoryTask.TASK },
                 { field: TASK_STATUS_FIELD, operator: "eq", value: TaskStatus.TODO },
                 { field: "value", operator: "in", value: availableTaskList },
             ],
+            limit: 1,
+            orderBy: { field: "created_at", ascending: true },
         });
-
+        const possibleTask = taskCandidates?.[0] ?? null;
         if (possibleTask == null) {
             return generateResponse.success(null);
         }
+        todoTask = possibleTask;
+    } catch (error) {
+        const message = getErrorMessage(error);
+        logger.error("獲取 TODO 任務失敗", { topic: LOG_TOPIC_TASK, data: { error: message, availableTaskList } });
+        return generateResponse.error(message) as SupabaseResponse<Task | null>;
+    }
 
-        const todoTask = possibleTask as Task;
+    const taskLogger = createLogger({
+        module: "patchClaimTask",
+        traceId,
+        traceParentId: todoTask.details.traceId,
+        labels: { nodeId },
+    });
+
+    try {
         const data = await claimTaskById({ taskId: todoTask.id, nodeId });
-        logTaskTransition(logger, "patchClaimTask", data);
+        logTaskTransition(taskLogger, "patchClaimTask", data);
         return generateResponse.success(data);
     } catch (error) {
         if (isOptimisticLockError(error)) {
-            logger.debug("認領競爭失敗，本輪無可認領任務", { topic: "task" });
-            return generateResponse.error(OPTIMISTIC_LOCK_FAILED_MESSAGE, undefined, "OPTIMISTIC_LOCK") as SupabaseResponse<Task | null>;
+            taskLogger.debug("認領競爭失敗，任務已被其他節點認領", {
+                topic: LOG_TOPIC_TASK,
+                data: { taskId: todoTask.id, taskTypeKey: todoTask.value },
+            });
+            return generateResponse.error(
+                OPTIMISTIC_LOCK_FAILED_MESSAGE,
+                undefined,
+                OPTIMISTIC_LOCK_ERROR_CODE,
+            ) as SupabaseResponse<Task | null>;
         }
-        const message = error instanceof Error ? error.message : String(error);
-        logger.error("認領任務失敗", { topic: "task", data: { error: message } });
+        const message = getErrorMessage(error);
+        taskLogger.error("認領任務失敗", {
+            topic: LOG_TOPIC_TASK,
+            data: { error: message, taskId: todoTask.id, taskTypeKey: todoTask.value },
+        });
         return generateResponse.error(message) as SupabaseResponse<Task | null>;
     }
 });

package/src/task/task.constant.ts

@@ -0,0 +1,4 @@
+/** Log topic for task domain (`topic` field on structured logs). */
+export const LOG_TOPIC_TASK = "task";
+
+export const CRITICAL_UNKNOWN_TASK_TRACE_ID = "CRITICAL_UNKNOWN_TASK_TRACE_ID";

package/src/task/task.interface.ts

@@ -1,4 +1,4 @@
-import { Target } from "../core.interface";
+import type { Target } from "../core.interface";
 
 export enum CategoryTask {
     TASK = "task",
@@ -60,11 +60,8 @@ export interface TaskDetails {
         code: ResultCode;
         errorMessage?: string;
         data?: unknown;
-    }
-};
-
-// TODO loop condition combination
-export interface TaskFlow extends Target {
-
+    };
 }
 
+// TODO loop condition combination
+export interface TaskFlow extends Target {}