npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@schorts/firestore-admin-dao

v7.0.0

Published

This module provides a type-safe, domain-driven abstraction over Firestore persistence. It integrates tightly with the `Model`, `Entity`, `Criteria` and `UnitOfWork` constructs from the Shared Kernel, enabling expressive, consistent, and testable data acc

Readme

@schorts/firestore-admin-dao

npm version

This module provides a type-safe, domain-driven abstraction over Firestore persistence. It integrates tightly with the Model, Entity, Criteria and UnitOfWork constructs from @schorts/shared-kernel, enabling expressive, consistent, and testable data access.

🤖 Using it with AI coding agents

The package ships agent docs in node_modules/@schorts/firestore-admin-dao/ai/: an AGENTS.md overview, rules (entity mapping, querying, transactions, soft delete, testing), and step-by-step skills (create a DAO, geo search, transactions and batches, soft delete, testing, upgrading to 6.x) with type-checked examples. They build on the shared kernel's docs. Point your agent at both, for example in CLAUDE.md:

Before writing code that uses @schorts/firestore-admin-dao, read
node_modules/@schorts/shared-kernel/ai/AGENTS.md, then
node_modules/@schorts/firestore-admin-dao/ai/AGENTS.md, and follow their rules and skills.

ai/README.md has setup for Claude Code (including linking the skills), Cursor, Copilot, and other tools.

Installation

This package has a peer dependency on @schorts/shared-kernel 11.x and requires Node.js 22 or later (a requirement of firebase-admin 14).

npm install @schorts/firestore-admin-dao @schorts/shared-kernel

It works from both ES modules and CommonJS.

Usage

Here's a complete example of how to use the FirestoreDAO to interact with a collection.

1. Initialize Firebase Admin

With no arguments, initializeApp() uses Application Default Credentials, or the Firestore emulator when FIRESTORE_EMULATOR_HOST is set. Pass credential: cert(serviceAccount) to use a service account key instead.

// file: firebase.ts
import { getApps, getFirestore, initializeApp } from "@schorts/firestore-admin-dao";

const app = getApps()[0] ?? initializeApp();

export const firestore = getFirestore(app);

2. Define your entity

An entity extends the kernel's Entity and implements toPrimitives(). createId and restoreFromPrimitives let the kernel rebuild it from a stored document.

  • The document is toPrimitives() without id; the document ID is the entity ID.
  • Date and DateValue properties are stored as Firestore Timestamps, under the property name in snake_case (createdAt → created_at). Name the model field the same way. They come back as ISO strings.
// file: task.ts
import { Entity } from "@schorts/shared-kernel/entities";
import { DateValue, UUIDValue } from "@schorts/shared-kernel/value-objects";

export class TaskId extends UUIDValue {
  readonly attributeName = "taskId";
}

export class CreatedAt extends DateValue {
  readonly attributeName = "createdAt";
}

export type TaskModel = {
  id: string;
  title: string;
  priority: number;
  done: boolean;
  created_at: string;
};

export class Task extends Entity<TaskId, TaskModel> {
  constructor(
    id: TaskId,
    public title = "",
    public priority = 0,
    public done = false,
    public createdAt = new CreatedAt(new Date()),
  ) {
    super(id);
  }

  toPrimitives(): TaskModel {
    return {
      id: this.id.value,
      title: this.title,
      priority: this.priority,
      done: this.done,
      created_at: this.createdAt.value.toISOString(),
    };
  }

  protected override createId(rawId: unknown): TaskId {
    return new TaskId(String(rawId));
  }

  protected override restoreFromPrimitives(data: TaskModel): void {
    this.title = data.title;
    this.priority = data.priority;
    this.done = data.done;
    this.createdAt = new CreatedAt(new Date(data.created_at));
  }
}

3. Create a concrete DAO class

FirestoreDAO is abstract. Extend it with your collection and register the entity under the collection's path, so the DAO can rebuild entities when it reads.

// file: task-dao.ts
import { EntityRegistry, FirestoreDAO, type CollectionReference } from "@schorts/firestore-admin-dao";
import { Criteria } from "@schorts/shared-kernel/criteria";
import { Task, type TaskModel } from "./task.js";

export const TASKS = "tasks";

EntityRegistry.register(TASKS, Task);

export class TaskDAO extends FirestoreDAO<TaskModel, Task> {
  constructor(collection: CollectionReference) {
    // "HARD" removes deleted documents; "SOFT" flags them so they can be restored.
    super(collection, "HARD");
  }

  findOpenByPriority(limit = 20): Promise<Task[]> {
    return this.search(
      Criteria.none()
        .where("done", "EQUAL", false)
        .orderBy("priority", "DESC")
        .limitResults(limit),
    );
  }
}

4. Use the DAO

// file: main.ts
import { randomUUID } from "node:crypto";
import { Criteria } from "@schorts/shared-kernel/criteria";
import { firestore } from "./firebase.js";
import { Task, TaskId } from "./task.js";
import { TASKS, TaskDAO } from "./task-dao.js";

const tasks = new TaskDAO(firestore.collection(TASKS));

// Create
const task = new Task(new TaskId(randomUUID()), "Write the release notes", 2);
await tasks.create(task);

// Read
const found = await tasks.findByID(task.id.value);
const urgent = await tasks.search(
  Criteria.none().where("priority", "GREATER_THAN_OR_EQUAL", 2).orderBy("priority", "DESC"),
);
const pageCriteria = Criteria.none().orderBy("priority", "DESC").limitResults(20);
const firstPage = await tasks.search(pageCriteria);
const nextPage = firstPage.length
  ? await tasks.search(pageCriteria.cursorResults(String(firstPage[firstPage.length - 1]!.id.value)))
  : [];
const open = await tasks.findOpenByPriority();
const total = await tasks.count();

// Update
if (found) {
  found.done = true;
  await tasks.update(found);
}

// Delete
await tasks.delete(task);

console.log({ urgent: urgent.length, open: open.length, total });

Every method also takes an optional unit of work to group writes. Use FirestoreUnitOfWorkRunner for transactions and FirestoreBatchUnitOfWork for batched writes.

Supported Criteria operators are EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN, ARRAY_CONTAINS, ARRAY_CONTAINS_ANY, and GEO_RADIUS. LIKE and BETWEEN throw OperatorNotValid.

For cursor pagination, use the last returned entity's document ID as shown above, and keep filters and ordering unchanged between pages. Firestore reads the cursor document to construct the next query; it must still exist and contain the ordered fields. If its ordered fields change between requests, results can be skipped or repeated. The cursor is applied before any offset and limit. Geo queries apply the cursor after merging and filtering their results and require the cursor document to still match.

The ai/ docs cover entity mapping, querying and indexes, geo search, transactions and batches, soft delete, and testing in detail.

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

License

This project is licensed under the LGPL-3.0-or-later License.