🔧 API Reference

Firetype generates fully typed APIs that mirror your Firestore database structure. Here’s a comprehensive reference of the generated functions and types.

Generated Functions

`createFireTypeAdmin(firestoreInstance)`

Creates a type-safe Firestore API for server-side operations using the Firebase Admin SDK. Parameters:

firestoreInstance: Firebase Admin Firestore instance

Returns: Type-safe API object matching your schema structure

`createFireTypeClient(firestoreInstance)`

Creates a type-safe Firestore API for client-side operations using the Firebase Web SDK. Parameters:

firestoreInstance: Firebase Client Firestore instance

Returns: Type-safe API object matching your schema structure

API Structure

The generated API mirrors your directory structure. For this schema structure:

schemas/database/
├── users/
│   ├── schema.ts
│   └── posts/
│       └── schema.ts
└── posts/
    └── schema.ts

You get this typed API:

const firetype = createFireTypeAdmin(db);

firetype.users; // /users collection API
firetype.users.posts; // /users/{userId}/posts subcollection API
firetype.posts; // /posts collection API

Collection API Methods

`getCollectionRef(validate?: boolean)`

Returns a typed Firestore collection reference. Parameters:

validate (boolean, optional): Enable runtime validation (default: false)

Returns:

Admin: AdminCollectionReference<T>
Client: ClientCollectionReference<T>

Example:

const usersRef = firetype.users.getCollectionRef(true); // With validation
const usersRef = firetype.users.getCollectionRef(); // Without validation

`getDocumentRef(documentId, validate?: boolean)`

Returns a typed Firestore document reference. Parameters:

documentId (string): The document ID
validate (boolean, optional): Enable runtime validation (default: false)

Returns:

Admin: AdminDocumentReference<T>
Client: ClientDocumentReference<T>

Example:

const userDoc = firetype.users.getDocumentRef('user123', true);

`getCollectionGroupRef(validate?: boolean)`

Returns a typed collection group reference for querying across all subcollections. Parameters:

validate (boolean, optional): Enable runtime validation (default: false)

Returns:

Admin: AdminCollectionGroup<T>
Client: ClientQuery<T>

Example:

// Query all posts across all users
const allPosts = firetype.users.posts.getCollectionGroupRef();
const recentPosts = await allPosts
  .where('published', '==', true)
  .orderBy('createdAt', 'desc')
  .limit(10)
  .get();

Subcollection API Methods

For subcollections, the API methods require parent document IDs:

`getCollectionRef(args, validate?: boolean)`

Parameters:

args: Object containing parent document IDs (e.g., { usersId: "user123" })
validate (boolean, optional): Enable runtime validation (default: false)

Example:

// Get posts for a specific user
const userPostsRef = firetype.users.posts.getCollectionRef({
  usersId: 'user123',
});

`getDocumentRef(args, documentId, validate?: boolean)`

Parameters:

args: Object containing parent document IDs
documentId (string): The document ID
validate (boolean, optional): Enable runtime validation (default: false)

Example:

// Get a specific post from a user
const userPostDoc = firetype.users.posts.getDocumentRef({ usersId: 'user123' }, 'post456');

Validation

Firetype supports optional runtime validation using your Zod schemas:

// Enable validation for all operations
const firetype = createFireTypeAdmin(db);

// Collection operations with validation
const usersRef = firetype.users.getCollectionRef(true);

// Document operations with validation
const userDoc = firetype.users.getDocumentRef('user123', true);

// Invalid data will throw Zod validation errors
await usersRef.add({
  name: '', // ❌ Fails validation (empty string)
  email: 'invalid', // ❌ Fails validation (not email)
  createdAt: new Date(),
});

Type Safety

All generated APIs are fully type-safe:

// TypeScript knows the exact shape of your data
const user = await userDoc.get();
const userData = user.data();
// userData is typed as your User schema type

// Autocomplete and type checking for all fields
userData.name; // string
userData.email; // string
userData.age; // number | undefined
userData.metadata; // { lastLogin?: Date; isVerified: boolean; ... }

Error Handling

Firetype throws descriptive errors for common issues:

Validation errors: Zod validation errors when validation is enabled
Schema errors: Issues with your schema definitions
Firestore errors: Standard Firestore SDK errors are passed through

try {
  await usersRef.add(invalidUserData);
} catch (error) {
  if (error instanceof z.ZodError) {
    console.log('Validation failed:', error.errors);
  } else {
    console.log('Firestore error:', error);
  }
}

Generated Types

Schema Types

For each schema file, Firetype generates:

Document type: The TypeScript type for your document data
Create type: Type for creating new documents (with optional fields)
Update type: Type for updating existing documents

Reference Types

firestoreRef(path?): Creates document reference schemas. When a path is provided, it will be replaced during generation with a strongly-typed reference schema. When omitted, it behaves as a permissive Zod schema at authoring time and supports composition like z.array(firestoreRef()).
collectionPath(path): Generic helper that preserves literal types and brands collection paths.

SDK-Specific Types

Admin SDK:

AdminCollectionReference<T>
AdminDocumentReference<T>
AdminCollectionGroup<T>

Client SDK:

ClientCollectionReference<T>
ClientDocumentReference<T>
ClientQuery<T>

Helper Functions

`firestoreRef(collectionPath?)`

Creates a strongly-typed Firestore document reference field.

import { firestoreRef } from '@anonymous-dev/firetype';

const schema = z.object({
  userRef: firestoreRef('users'),
  postRef: firestoreRef('users/posts'),
  anyRef: firestoreRef(),
  anyRefs: z.array(firestoreRef()),
});

`collectionPath(path)`

Creates a branded collection path for better type safety.

import { collectionPath, type CollectionPath } from '@anonymous-dev/firetype';

// Generic preserves the literal type and narrows to the generated union alias
const userPath: CollectionPath = collectionPath('users');

Best Practices

Validation Strategy

// Development: Enable validation everywhere
const firetype = createFireTypeAdmin(db);
const usersRef = firetype.users.getCollectionRef(true);

// Production: Disable validation for performance
const usersRef = firetype.users.getCollectionRef(false);

Error Handling Patterns

// Centralized error handling
async function createUser(userData: UserCreate) {
  try {
    const docRef = await firetype.users.getCollectionRef(true).add(userData);
    return { success: true, id: docRef.id };
  } catch (error) {
    if (error instanceof z.ZodError) {
      return {
        success: false,
        errors: error.errors.map((e) => ({
          field: e.path.join('.'),
          message: e.message,
        })),
      };
    }
    throw error; // Re-throw Firestore errors
  }
}

Type-Safe Queries

// Collection group queries
const allPosts = firetype.users.posts.getCollectionGroupRef();

// Type-safe where clauses
const publishedPosts = await allPosts
  .where('published', '==', true)
  .where('createdAt', '>', new Date(Date.now() - 86400000)) // Last 24h
  .orderBy('createdAt', 'desc')
  .limit(10)
  .get();

// Fully typed results
publishedPosts.docs.forEach((doc) => {
  const post = doc.data();
  // post is fully typed with your Post schema
});

Getting Started

Guides

API Reference

Help

API Reference

🔧 API Reference

Generated Functions

`createFireTypeAdmin(firestoreInstance)`

`createFireTypeClient(firestoreInstance)`

API Structure

Collection API Methods

`getCollectionRef(validate?: boolean)`

`getDocumentRef(documentId, validate?: boolean)`

`getCollectionGroupRef(validate?: boolean)`

Subcollection API Methods

`getCollectionRef(args, validate?: boolean)`

`getDocumentRef(args, documentId, validate?: boolean)`

Validation

Type Safety

Error Handling

Generated Types

Schema Types

Reference Types

SDK-Specific Types

Helper Functions

`firestoreRef(collectionPath?)`

`collectionPath(path)`

Best Practices

Validation Strategy

Error Handling Patterns

Type-Safe Queries

​🔧 API Reference

​Generated Functions

​createFireTypeAdmin(firestoreInstance)

​createFireTypeClient(firestoreInstance)

​API Structure

​Collection API Methods

​getCollectionRef(validate?: boolean)

​getDocumentRef(documentId, validate?: boolean)

​getCollectionGroupRef(validate?: boolean)

​Subcollection API Methods

​getCollectionRef(args, validate?: boolean)

​getDocumentRef(args, documentId, validate?: boolean)

​Validation

​Type Safety

​Error Handling

​Generated Types

​Schema Types

​Reference Types

​SDK-Specific Types

​Helper Functions

​firestoreRef(collectionPath?)

​collectionPath(path)

​Best Practices

​Validation Strategy

​Error Handling Patterns

​Type-Safe Queries

🔧 API Reference

Generated Functions

`createFireTypeAdmin(firestoreInstance)`

`createFireTypeClient(firestoreInstance)`

API Structure

Collection API Methods

`getCollectionRef(validate?: boolean)`

`getDocumentRef(documentId, validate?: boolean)`

`getCollectionGroupRef(validate?: boolean)`

Subcollection API Methods

`getCollectionRef(args, validate?: boolean)`

`getDocumentRef(args, documentId, validate?: boolean)`

Validation

Type Safety

Error Handling

Generated Types

Schema Types

Reference Types

SDK-Specific Types

Helper Functions

`firestoreRef(collectionPath?)`

`collectionPath(path)`

Best Practices

Validation Strategy

Error Handling Patterns

Type-Safe Queries