feat(Node): add Effect.ts 2nd Gen Cloud Functions sample

[jhuleatt]

Description

This pull request adds a new code sample under Node/effect-functions demonstrating idiomatic integration of Effect 4.0 (effect@^4.0.0) with Firebase 2nd Generation Cloud Functions.

The sample deliberately leans on what the Firebase and Firestore SDKs already provide (auto-IDs, WriteBatch atomicity and create() preconditions, FieldValue.increment, Eventarc event.time, built-in gRPC retries) and uses Effect only where it adds something the SDKs don't: Schema validation at the boundaries, typed domain errors, dependency injection, and structured logging. Seven source files, readable top to bottom.

Key Architecture & Effect 4.0 Features Demonstrated

• 2nd Gen Callable Function (createTask):
  • Parameterized configuration via firebase-functions/params (defineInt("MAX_ACTIVE_TASKS_PER_USER", { default: 100 })).
  • Request decoding and validation via Schema.decodeUnknownEffect, Schema.Trim.check(Schema.isNonEmpty()), and Schema.withDecodingDefault; schema issues surface as a typed ValidationError carrying SchemaError.message.
  • Authentication and business-rule checks yielding Schema.TaggedError domain errors directly (yield* new UnauthorizedError(...)).
  • Native Firestore auto-IDs (collection.doc()) for new tasks.
  • Zero-cast Exit & Cause inspection via Cause.findErrorOption mapping DomainError to standard HttpsError status codes.
• 2nd Gen Firestore Trigger (onTaskWritten):
  • before/after snapshot decoding at the trigger boundary using Schema.decodeUnknownEffect(Task).
  • Allowed status transition validation wrapped in Effect.fn("validateStatusTransition"); invalid transitions are caught with Effect.catchTag, logged as warnings, and the function succeeds so Eventarc never retries a condition that cannot succeed.
  • Atomic, idempotent event processing with a single WriteBatch visible in the trigger itself: batch.create(audit_logs/{event.id}) rejects redeliveries with GrpcStatus.ALREADY_EXISTS (caught with Effect.catchIf), so the FieldValue.increment user-stats writes in the same batch apply at most once per Eventarc event ID. No reads, no transactions, no application-level retry loops.
  • Counter deltas are derived from the before/after status, so a task written directly as completed is counted correctly.
  • Audit timestamps come from the authoritative Eventarc CloudEvent event.time.
• Serverless Production Patterns:
  • Context.Service repositories (TaskRepository, UserStatsRepository) with a single static layer each (Layer.sync), composed with Layer.mergeAll into a module-scoped ManagedRuntime (appRuntime) for warm-instance reuse.
  • Effect.fn traced repository methods and Effect.annotateLogs / Effect.withLogSpan request context.
  • Custom Logger layer built on Logger.formatStructured + Logger.map + Logger.layer, routing Effect logs into firebase-functions/logger (logger.write) with structured jsonPayload attributes and no synthetic stack traces.
• Testing:
  • 14 integration tests using vitest and firebase-functions-test, always run against the real Firestore emulator (npm test = firebase emulators:exec --only firestore "vitest run"), covering concurrent and sequential Eventarc duplicate delivery idempotency, event.time propagation, counter deltas across every status transition, invalid-transition handling, and typed FirestoreError on corrupted documents.
  • .github/workflows/test_node.yml now installs Java 21 and firebase-tools and caches the emulator jar so test-2nd-gen exercises real Firestore in CI.

Note

The Node Unit Tests job currently fails before reaching this sample because Node/delete-unused-accounts-cron no longer compiles on main (es6-promise-pool TS2351); that is unrelated to this PR.

[gemini-code-assist]

Code Review

This pull request introduces a new sample project demonstrating Firebase 2nd Gen Cloud Functions integrated with Effect.ts, including a callable function, a Firestore trigger, dependency injection, and Vitest tests. The review feedback highlights a critical TypeScript compilation error in the Schema.Record definition. Additionally, it identifies state-tracking bugs in UserStatsRepository during task transitions (especially with archived states) and recommends refactoring to a single, robust updateStats method with numeric deltas. Finally, it suggests using Schedule.intersect instead of Schedule.compose for a more idiomatic retry policy.

[gemini-code-assist]

In Effect Schema, Schema.Record expects two schema arguments: Schema.Record(key, value). Passing an object with key and value properties will cause a TypeScript compilation error. Update this to use the correct positional arguments.

Suggested change

	details: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
	details: Schema.Record(Schema.String, Schema.Unknown),

[gemini-code-assist]

The current implementation of UserStatsRepository has several correctness bugs when handling task status transitions (e.g., transitioning to/from archived or deleting archived tasks), which leads to incorrect counts for activeTasks and completedTasks.

Instead of having multiple specific methods that are prone to state-tracking bugs, we can simplify the repository to a single generic updateStats method that accepts numeric deltas. This makes the repository extremely robust and reusable.

export interface UserStatsRepositoryShape {
  readonly updateStats: (
    userId: string,
    deltas: { readonly activeDelta: number; readonly completedDelta: number }
  ) => Effect.Effect<void, FirestoreError>;
}

export class UserStatsRepository extends Context.Tag("UserStatsRepository")<
  UserStatsRepository,
  UserStatsRepositoryShape
>() {}

export const UserStatsRepositoryLive = Layer.effect(
  UserStatsRepository,
  Effect.gen(function* () {
    const db = yield* FirestoreService;
    const statsCol = db.collection("user_stats");

    return {
      updateStats: (userId, { activeDelta, completedDelta }) =>
        Effect.tryPromise({ 
          try: async () => {
            await statsCol.doc(userId).set(
              {
                userId,
                activeTasks: FieldValue.increment(activeDelta),
                completedTasks: FieldValue.increment(completedDelta),
                lastUpdated: new Date().toISOString(),
              },
              { merge: true }
            );
          },
          catch: (cause) =>
            new FirestoreError({
              cause,
              message: `Failed to update user stats for user ${userId}`,
            }),
        }),
    };
  })
);

[gemini-code-assist]

Update the task creation stats logic to use the new generic updateStats method.

Suggested change

	yield* Effect.all(
	[
	auditRepo.record({
	id: randomUUID(),
	taskId,
	userId: task.userId,
	action: "created",
	details: { title: task.title, priority: task.priority },
	timestamp: new Date().toISOString(),
	}).pipe(Effect.retry(retryPolicy)),
	statsRepo.onTaskCreated(task.userId).pipe(Effect.retry(retryPolicy)),
	],
	{ concurrency: "unbounded" }
	);
	yield* Effect.all(
	[
	auditRepo.record({
	id: randomUUID(),
	taskId,
	userId: task.userId,
	action: "created",
	details: { title: task.title, priority: task.priority },
	timestamp: new Date().toISOString(),
	}).pipe(Effect.retry(retryPolicy)),
	statsRepo.updateStats(task.userId, { activeDelta: 1, completedDelta: 0 }).pipe(Effect.retry(retryPolicy)),
	],
	{ concurrency: "unbounded" }
	);

[gemini-code-assist]

Compute the precise deltas for activeTasks and completedTasks based on the status transition. This correctly handles transitions to and from the archived state, which were previously causing incorrect statistics.

        const isActive = (status: TaskStatus) => status === "todo" || status === "in_progress";
        const isCompleted = (status: TaskStatus) => status === "completed";

        const activeDelta = (isActive(afterTask.status) ? 1 : 0) - (isActive(beforeTask.status) ? 1 : 0);
        const completedDelta = (isCompleted(afterTask.status) ? 1 : 0) - (isCompleted(beforeTask.status) ? 1 : 0);

        const statsEffect = activeDelta === 0 && completedDelta === 0
          ? Effect.void
          : statsRepo.updateStats(afterTask.userId, { activeDelta, completedDelta });

        // Run audit logging and user statistics update concurrently with retries
        yield* Effect.all(
          [
            auditRepo.record({
              id: randomUUID(),
              taskId,
              userId: afterTask.userId,
              action: "status_changed",
              details: { from: beforeTask.status, to: afterTask.status },
              timestamp: new Date().toISOString(),
            }).pipe(Effect.retry(retryPolicy)),

            statsEffect.pipe(Effect.retry(retryPolicy)),
          ],
          { concurrency: "unbounded" }
        );

[gemini-code-assist]

Update the task deletion stats logic to use the new generic updateStats method. This ensures that deleting an archived task does not incorrectly decrement activeTasks again.

      const isActive = beforeTask.status === "todo" || beforeTask.status === "in_progress";
      const isCompleted = beforeTask.status === "completed";

      yield* Effect.all(
        [
          auditRepo.record({
            id: randomUUID(),
            taskId,
            userId: beforeTask.userId,
            action: "deleted",
            details: { title: beforeTask.title },
            timestamp: new Date().toISOString(),
          }).pipe(Effect.retry(retryPolicy)),

          statsRepo
            .updateStats(beforeTask.userId, { 
              activeDelta: isActive ? -1 : 0,
              completedDelta: isCompleted ? -1 : 0,
            })
            .pipe(Effect.retry(retryPolicy)),
        ],
        { concurrency: "unbounded" }
      );

[gemini-code-assist]

In Effect, Schedule.compose is used to feed the output of one schedule as the input of another. To combine a delay schedule with a recursion limit, Schedule.intersect is the idiomatic and clearer approach.

Suggested change

	const retryPolicy = Schedule.exponential(Duration.millis(100)).pipe(
	Schedule.jittered,
	Schedule.compose(Schedule.recurs(3))
	);
	const retryPolicy = Schedule.exponential(Duration.millis(100)).pipe(
	Schedule.jittered,
	Schedule.intersect(Schedule.recurs(3))
	);