@cravery/core 0.0.3 → 0.0.4

package/src/lib/repository/firestore.repository.ts

@@ -0,0 +1,607 @@
+import {
+  Firestore,
+  CollectionReference,
+  DocumentData,
+  Query,
+  FieldValue,
+  Transaction,
+  WriteBatch,
+  Timestamp,
+  QueryDocumentSnapshot,
+} from "firebase-admin/firestore";
+import type {
+  IRepository,
+  QueryOptions,
+  PaginatedResult,
+  CursorPaginatedResult,
+  WhereClause,
+  TransactionCallback,
+  RepositoryConfig,
+} from "../../types/repository";
+import { RepositoryError, RepositoryErrorCode } from "./errors";
+
+const FIRESTORE_IN_QUERY_LIMIT = 10;
+const FIRESTORE_BATCH_WRITE_LIMIT = 500;
+
+export abstract class FirestoreRepository<T extends { id: string }>
+  implements IRepository<T>
+{
+  protected readonly collection: CollectionReference<DocumentData>;
+  protected readonly config: Required<RepositoryConfig>;
+
+  constructor(
+    protected readonly firestore: Firestore,
+    protected readonly collectionName: string,
+    config?: RepositoryConfig,
+  ) {
+    this.collection = firestore.collection(collectionName);
+    this.config = {
+      enableTimestamps: true,
+      enableSoftDelete: false,
+      validateOnWrite: false,
+      ...config,
+    };
+  }
+
+  protected toDocument(entity: Partial<T>): DocumentData {
+    return { ...entity };
+  }
+
+  protected fromDocument(id: string, data: DocumentData): T {
+    return { id, ...data } as T;
+  }
+
+  protected validate(_data: Partial<T>): void {
+  }
+
+  async findById(id: string): Promise<T | null> {
+    const doc = await this.collection.doc(id).get();
+    if (!doc.exists) return null;
+
+    const data = doc.data()!;
+    if (this.config.enableSoftDelete && data.deletedAt) {
+      return null;
+    }
+
+    return this.fromDocument(doc.id, data);
+  }
+
+  async findByIds(ids: string[]): Promise<T[]> {
+    if (ids.length === 0) return [];
+
+    const results: T[] = [];
+    const chunks = this.chunk(ids, FIRESTORE_IN_QUERY_LIMIT);
+
+    for (const chunk of chunks) {
+      const refs = chunk.map((id) => this.collection.doc(id));
+      const docs = await this.firestore.getAll(...refs);
+
+      for (const doc of docs) {
+        if (doc.exists) {
+          const data = doc.data()!;
+          if (this.config.enableSoftDelete && data.deletedAt) {
+            continue;
+          }
+          results.push(this.fromDocument(doc.id, data));
+        }
+      }
+    }
+
+    return results;
+  }
+
+  async findAll(options?: QueryOptions): Promise<T[]> {
+    let query: Query = this.collection;
+
+    if (this.config.enableSoftDelete) {
+      query = query.where("deletedAt", "==", null);
+    }
+
+    query = this.applyQueryOptions(query, options);
+    const snapshot = await query.get();
+    return snapshot.docs.map((doc: QueryDocumentSnapshot<DocumentData>) =>
+      this.fromDocument(doc.id, doc.data()),
+    );
+  }
+
+  async findWhere(
+    clauses: WhereClause[],
+    options?: QueryOptions,
+  ): Promise<T[]> {
+    let query = this.applyWhereClauses(this.collection, clauses);
+
+    if (this.config.enableSoftDelete) {
+      query = query.where("deletedAt", "==", null);
+    }
+
+    query = this.applyQueryOptions(query, options);
+    const snapshot = await query.get();
+    return snapshot.docs.map((doc: QueryDocumentSnapshot<DocumentData>) =>
+      this.fromDocument(doc.id, doc.data()),
+    );
+  }
+
+  async findPaginated(
+    clauses?: WhereClause[],
+    options?: QueryOptions,
+  ): Promise<PaginatedResult<T>> {
+    let query: Query = clauses
+      ? this.applyWhereClauses(this.collection, clauses)
+      : this.collection;
+
+    if (this.config.enableSoftDelete) {
+      query = query.where("deletedAt", "==", null);
+    }
+
+    const countSnapshot = await query.count().get();
+    const total = countSnapshot.data().count;
+
+    query = this.applyQueryOptions(query, options);
+    const snapshot = await query.get();
+    const data = snapshot.docs.map((doc: QueryDocumentSnapshot<DocumentData>) =>
+      this.fromDocument(doc.id, doc.data()),
+    );
+
+    const offset = options?.offset ?? 0;
+    return {
+      data,
+      total,
+      hasMore: offset + data.length < total,
+    };
+  }
+
+  async findPaginatedCursor(
+    clauses?: WhereClause[],
+    options?: QueryOptions & { cursor?: string },
+  ): Promise<CursorPaginatedResult<T>> {
+    let query: Query = clauses
+      ? this.applyWhereClauses(this.collection, clauses)
+      : this.collection;
+
+    if (this.config.enableSoftDelete) {
+      query = query.where("deletedAt", "==", null);
+    }
+
+    if (options?.orderBy) {
+      query = query.orderBy(options.orderBy.field, options.orderBy.direction);
+    }
+
+    if (options?.cursor) {
+      const cursorDoc = await this.collection.doc(options.cursor).get();
+      if (cursorDoc.exists) {
+        query = query.startAfter(cursorDoc);
+      }
+    }
+
+    const limit = options?.limit ?? 20;
+    query = query.limit(limit + 1);
+
+    const snapshot = await query.get();
+    const docs = snapshot.docs;
+    const hasMore = docs.length > limit;
+
+    if (hasMore) docs.pop();
+
+    const data = docs.map((doc: QueryDocumentSnapshot<DocumentData>) =>
+      this.fromDocument(doc.id, doc.data()),
+    );
+    const nextCursor =
+      hasMore && docs.length > 0 ? docs[docs.length - 1].id : null;
+
+    return { data, nextCursor, hasMore };
+  }
+
+  async exists(id: string): Promise<boolean> {
+    const doc = await this.collection.doc(id).get();
+    if (!doc.exists) return false;
+
+    if (this.config.enableSoftDelete) {
+      const data = doc.data()!;
+      return !data.deletedAt;
+    }
+
+    return true;
+  }
+
+  async count(clauses?: WhereClause[]): Promise<number> {
+    let query: Query = clauses
+      ? this.applyWhereClauses(this.collection, clauses)
+      : this.collection;
+
+    if (this.config.enableSoftDelete) {
+      query = query.where("deletedAt", "==", null);
+    }
+
+    const snapshot = await query.count().get();
+    return snapshot.data().count;
+  }
+
+  async create(data: Omit<T, "id" | "createdAt" | "updatedAt" | "deletedAt">, id?: string): Promise<T> {
+    if (this.config.validateOnWrite) {
+      this.validate(data as Partial<T>);
+    }
+
+    const docRef = id ? this.collection.doc(id) : this.collection.doc();
+    const now = Timestamp.now();
+
+    let docData = this.toDocument({
+      ...data,
+      id: docRef.id,
+    } as Partial<T>);
+
+    if (this.config.enableTimestamps) {
+      docData = {
+        ...docData,
+        createdAt: now,
+        updatedAt: now,
+      };
+    }
+
+    if (this.config.enableSoftDelete) {
+      docData = {
+        ...docData,
+        deletedAt: null,
+      };
+    }
+
+    await docRef.set(docData);
+    return this.fromDocument(docRef.id, docData);
+  }
+
+  async update(id: string, data: Partial<Omit<T, "id" | "createdAt" | "updatedAt" | "deletedAt">>): Promise<T> {
+    if (this.config.validateOnWrite) {
+      this.validate(data as Partial<T>);
+    }
+
+    const docRef = this.collection.doc(id);
+    let updateData = this.toDocument(data as Partial<T>);
+
+    if (this.config.enableTimestamps) {
+      updateData = {
+        ...updateData,
+        updatedAt: Timestamp.now(),
+      };
+    }
+
+    await docRef.update(updateData);
+    const updated = await docRef.get();
+
+    if (!updated.exists) {
+      throw new RepositoryError(
+        RepositoryErrorCode.NOT_FOUND,
+        `Document ${id} not found after update`,
+        { collection: this.collectionName, id },
+      );
+    }
+
+    return this.fromDocument(updated.id, updated.data()!);
+  }
+
+  async delete(id: string): Promise<void> {
+    if (this.config.enableSoftDelete) {
+      await this.collection.doc(id).update({
+        deletedAt: Timestamp.now(),
+        updatedAt: Timestamp.now(),
+      });
+    } else {
+      await this.collection.doc(id).delete();
+    }
+  }
+
+  async createMany(items: Omit<T, "id" | "createdAt" | "updatedAt" | "deletedAt">[]): Promise<T[]> {
+    if (items.length === 0) return [];
+
+    const results: T[] = [];
+    const chunks = this.chunk(items, FIRESTORE_BATCH_WRITE_LIMIT);
+
+    for (const chunk of chunks) {
+      const batch = this.firestore.batch();
+      const now = Timestamp.now();
+      const chunkResults: T[] = [];
+
+      for (const item of chunk) {
+        if (this.config.validateOnWrite) {
+          this.validate(item as Partial<T>);
+        }
+
+        const docRef = this.collection.doc();
+        let docData = this.toDocument({
+          ...item,
+          id: docRef.id,
+        } as Partial<T>);
+
+        if (this.config.enableTimestamps) {
+          docData = { ...docData, createdAt: now, updatedAt: now };
+        }
+
+        if (this.config.enableSoftDelete) {
+          docData = { ...docData, deletedAt: null };
+        }
+
+        batch.set(docRef, docData);
+        chunkResults.push(this.fromDocument(docRef.id, docData));
+      }
+
+      await batch.commit();
+      results.push(...chunkResults);
+    }
+
+    return results;
+  }
+
+  async updateMany(
+    updates: Array<{ id: string; data: Partial<Omit<T, "id" | "createdAt" | "updatedAt" | "deletedAt">> }>,
+  ): Promise<void> {
+    if (updates.length === 0) return;
+
+    const chunks = this.chunk(updates, FIRESTORE_BATCH_WRITE_LIMIT);
+
+    for (const chunk of chunks) {
+      const batch = this.firestore.batch();
+      const now = Timestamp.now();
+
+      for (const { id, data } of chunk) {
+        if (this.config.validateOnWrite) {
+          this.validate(data as Partial<T>);
+        }
+
+        const docRef = this.collection.doc(id);
+        let updateData = this.toDocument(data as Partial<T>);
+
+        if (this.config.enableTimestamps) {
+          updateData = { ...updateData, updatedAt: now };
+        }
+
+        batch.update(docRef, updateData);
+      }
+
+      await batch.commit();
+    }
+  }
+
+  async deleteMany(ids: string[]): Promise<void> {
+    if (ids.length === 0) return;
+
+    const chunks = this.chunk(ids, FIRESTORE_BATCH_WRITE_LIMIT);
+
+    for (const chunk of chunks) {
+      const batch = this.firestore.batch();
+      const now = Timestamp.now();
+
+      for (const id of chunk) {
+        const docRef = this.collection.doc(id);
+
+        if (this.config.enableSoftDelete) {
+          batch.update(docRef, {
+            deletedAt: now,
+            updatedAt: now,
+          });
+        } else {
+          batch.delete(docRef);
+        }
+      }
+
+      await batch.commit();
+    }
+  }
+
+  async increment(
+    id: string,
+    field: keyof T,
+    value: number = 1,
+  ): Promise<void> {
+    const updateData: DocumentData = {
+      [field as string]: FieldValue.increment(value),
+    };
+
+    if (this.config.enableTimestamps) {
+      updateData.updatedAt = Timestamp.now();
+    }
+
+    await this.collection.doc(id).update(updateData);
+  }
+
+  async decrement(
+    id: string,
+    field: keyof T,
+    value: number = 1,
+  ): Promise<void> {
+    await this.increment(id, field, -value);
+  }
+
+  async runTransaction<R>(callback: TransactionCallback<R>): Promise<R> {
+    return this.firestore.runTransaction(callback);
+  }
+
+  getFirestore(): Firestore {
+    return this.firestore;
+  }
+
+  batch(): WriteBatch {
+    return this.firestore.batch();
+  }
+
+  protected applyWhereClauses(query: Query, clauses: WhereClause[]): Query {
+    let q = query;
+
+    for (const clause of clauses) {
+      if (
+        (clause.op === "in" ||
+          clause.op === "not-in" ||
+          clause.op === "array-contains-any") &&
+        Array.isArray(clause.value) &&
+        clause.value.length > FIRESTORE_IN_QUERY_LIMIT
+      ) {
+        throw new RepositoryError(
+          RepositoryErrorCode.QUERY_LIMIT_EXCEEDED,
+          `${clause.op} queries support max ${FIRESTORE_IN_QUERY_LIMIT} values. ` +
+            `Got ${clause.value.length}. Use multiple queries and merge results.`,
+          { field: clause.field, op: clause.op, valueCount: clause.value.length },
+        );
+      }
+
+      q = q.where(clause.field, clause.op, clause.value);
+    }
+
+    return q;
+  }
+
+  protected applyQueryOptions(query: Query, options?: QueryOptions): Query {
+    let q = query;
+
+    if (options?.orderBy) {
+      q = q.orderBy(options.orderBy.field, options.orderBy.direction);
+    }
+    if (options?.offset) {
+      q = q.offset(options.offset);
+    }
+    if (options?.limit) {
+      q = q.limit(options.limit);
+    }
+
+    return q;
+  }
+
+  protected chunk<U>(array: U[], size: number): U[][] {
+    const chunks: U[][] = [];
+    for (let i = 0; i < array.length; i += size) {
+      chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+  }
+
+  protected async getInTransaction(
+    transaction: Transaction,
+    id: string,
+  ): Promise<T | null> {
+    const doc = await transaction.get(this.collection.doc(id));
+    if (!doc.exists) return null;
+
+    const data = doc.data()!;
+    if (this.config.enableSoftDelete && data.deletedAt) {
+      return null;
+    }
+
+    return this.fromDocument(doc.id, data);
+  }
+
+  protected setInTransaction(
+    transaction: Transaction,
+    id: string,
+    data: Partial<T>,
+  ): void {
+    let docData = this.toDocument(data);
+    const now = Timestamp.now();
+
+    if (this.config.enableTimestamps) {
+      docData = { ...docData, createdAt: now, updatedAt: now };
+    }
+
+    if (this.config.enableSoftDelete) {
+      docData = { ...docData, deletedAt: null };
+    }
+
+    transaction.set(this.collection.doc(id), docData);
+  }
+
+  protected updateInTransaction(
+    transaction: Transaction,
+    id: string,
+    data: Partial<T>,
+  ): void {
+    let docData = this.toDocument(data);
+
+    if (this.config.enableTimestamps) {
+      docData = { ...docData, updatedAt: Timestamp.now() };
+    }
+
+    transaction.update(this.collection.doc(id), docData);
+  }
+
+  protected deleteInTransaction(transaction: Transaction, id: string): void {
+    if (this.config.enableSoftDelete) {
+      const now = Timestamp.now();
+      transaction.update(this.collection.doc(id), {
+        deletedAt: now,
+        updatedAt: now,
+      });
+    } else {
+      transaction.delete(this.collection.doc(id));
+    }
+  }
+
+  createInBatch(batch: WriteBatch, data: Omit<T, "id" | "createdAt" | "updatedAt" | "deletedAt">, id?: string): T {
+    if (this.config.validateOnWrite) {
+      this.validate(data as Partial<T>);
+    }
+
+    const docRef = id ? this.collection.doc(id) : this.collection.doc();
+    const now = Timestamp.now();
+
+    let docData = this.toDocument({
+      ...data,
+      id: docRef.id,
+    } as Partial<T>);
+
+    if (this.config.enableTimestamps) {
+      docData = { ...docData, createdAt: now, updatedAt: now };
+    }
+
+    if (this.config.enableSoftDelete) {
+      docData = { ...docData, deletedAt: null };
+    }
+
+    batch.set(docRef, docData);
+    return this.fromDocument(docRef.id, docData);
+  }
+
+  setInBatch(batch: WriteBatch, id: string, data: Partial<Omit<T, "id" | "createdAt" | "updatedAt" | "deletedAt">>): void {
+    if (this.config.validateOnWrite) {
+      this.validate(data as Partial<T>);
+    }
+
+    const docRef = this.collection.doc(id);
+    const now = Timestamp.now();
+
+    let docData = this.toDocument(data as Partial<T>);
+
+    if (this.config.enableTimestamps) {
+      docData = { ...docData, createdAt: now, updatedAt: now };
+    }
+
+    if (this.config.enableSoftDelete) {
+      docData = { ...docData, deletedAt: null };
+    }
+
+    batch.set(docRef, docData);
+  }
+
+  updateInBatch(batch: WriteBatch, id: string, data: Partial<Omit<T, "id" | "createdAt" | "updatedAt" | "deletedAt">>): void {
+    if (this.config.validateOnWrite) {
+      this.validate(data as Partial<T>);
+    }
+
+    const docRef = this.collection.doc(id);
+    let updateData = this.toDocument(data as Partial<T>);
+
+    if (this.config.enableTimestamps) {
+      updateData = { ...updateData, updatedAt: Timestamp.now() };
+    }
+
+    batch.update(docRef, updateData);
+  }
+
+  deleteInBatch(batch: WriteBatch, id: string): void {
+    const docRef = this.collection.doc(id);
+
+    if (this.config.enableSoftDelete) {
+      const now = Timestamp.now();
+      batch.update(docRef, {
+        deletedAt: now,
+        updatedAt: now,
+      });
+    } else {
+      batch.delete(docRef);
+    }
+  }
+}

package/src/lib/repository/index.ts

@@ -0,0 +1,6 @@
+export * from "./errors";
+export * from "./firestore.repository";
+export * from "./rtdb.repository";
+export * from "./user.repository";
+export * from "./profile.repository";
+export * from "./settings.repository";

package/src/lib/repository/profile.repository.ts

@@ -0,0 +1,51 @@
+import { Firestore } from "firebase-admin/firestore";
+import { FirestoreRepository } from "./firestore.repository";
+import type { Profile } from "../../types/profile";
+import { ProfileSchema } from "../../types/profile";
+import { Collections } from "../../config/collections";
+import { RepositoryError, RepositoryErrorCode } from "./errors";
+
+export class ProfileRepository extends FirestoreRepository<Profile> {
+  constructor(firestore: Firestore) {
+    super(firestore, Collections.Profiles, {
+      enableTimestamps: true,
+      enableSoftDelete: true,
+      validateOnWrite: true,
+    });
+  }
+
+  protected validate(data: Partial<Profile>): void {
+    const result = ProfileSchema.partial().safeParse(data);
+    if (!result.success) {
+      throw new RepositoryError(
+        RepositoryErrorCode.VALIDATION_ERROR,
+        "Profile validation failed",
+        { errors: result.error.issues },
+      );
+    }
+  }
+
+  async findByHandle(handle: string): Promise<Profile | null> {
+    const results = await this.findWhere(
+      [{ field: "handle", op: "==", value: handle }],
+      { limit: 1 },
+    );
+    return results[0] ?? null;
+  }
+
+  async findByUserId(userId: string): Promise<Profile | null> {
+    return this.findById(userId);
+  }
+
+  async createWithUserId(
+    userId: string,
+    data: Omit<Profile, "id">,
+  ): Promise<Profile> {
+    return this.create(data, userId);
+  }
+
+  async handleExists(handle: string): Promise<boolean> {
+    const profile = await this.findByHandle(handle);
+    return profile !== null;
+  }
+}