Skip to main content

​
🔧 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
});