Arbel Firebase ORM

https://github.com/yarivluts/firebase-orm
Admin
Arbel Firebase ORM is a versatile Object-Relational Mapping tool for Firebase that supports...
Tokens:158,758
Snippets:575
Trust Score:5.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Setup Firebase

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/examples/README.md

Installs necessary npm packages and initializes a Firebase project. This is the first step to get started with Firebase ORM.

```bash
npm install @arbel/firebase-orm firebase moment

firebase init
```

--------------------------------

### Install Firebase ORM

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Installs the Firebase ORM library and its dependencies using npm. Includes separate commands for client-side and server-side applications.

```bash
npm install @arbel/firebase-orm firebase moment --save
```

```bash
npm install @arbel/firebase-orm firebase-admin moment --save
```

--------------------------------

### Firebase ORM Model Verification

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

A TypeScript example demonstrating the creation of a model, saving an instance, and verifying the Firebase ORM setup.

```typescript
import { BaseModel, Model, Field } from '@arbel/firebase-orm';

@Model({
  reference_path: 'test',
  path_id: 'test_id'
})
export class TestModel extends BaseModel {
  @Field({ is_required: true })
  public name!: string;
}

// Test the connection
async function testConnection() {
  const test = new TestModel();
  test.name = 'Hello Firebase ORM!';
  
  try {
    await test.save();
    console.log('✅ Firebase ORM setup successful!', test.getId());
  } catch (error) {
    console.error('❌ Setup failed:', error);
  }
}

testConnection();
```

--------------------------------

### Environment Variables File Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

An example `.env` file for storing Firebase configuration details, intended for use with environment variable loading libraries.

```env
FIREBASE_API_KEY=your-api-key
FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_STORAGE_BUCKET=your-project.appspot.com
FIREBASE_MESSAGING_SENDER_ID=123456789
FIREBASE_APP_ID=your-app-id
```

--------------------------------

### Complete Firebase ORM Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

A comprehensive example demonstrating the initialization of Firebase, definition of User and Post models with relationships, and performing CRUD operations including saving, loading, and querying data. It showcases the end-to-end usage of the Firebase ORM.

```typescript
import { initializeApp } from 'firebase/app';
import { getFirestore } from 'firebase/firestore';
import { FirestoreOrmRepository, BaseModel, Model, Field, HasMany } from '@arbel/firebase-orm';

// Initialize Firebase
const app = initializeApp({
  // your Firebase config
});
const firestore = getFirestore(app);
FirestoreOrmRepository.initGlobalConnection(firestore);

// Define models
@Model({
  reference_path: 'users',
  path_id: 'user_id'
})
class User extends BaseModel {
  @Field({ is_required: true })
  public name!: string;

  @Field({ is_required: true })
  public email!: string;

  @Field({ field_name: 'created_at' })
  public createdAt?: string;

  @HasMany({ model: Post, foreignKey: 'author_id' })
  public posts?: Post[];
}

@Model({
  reference_path: 'posts',
  path_id: 'post_id'
})
class Post extends BaseModel {
  @Field({ is_required: true })
  public title!: string;

  @Field({ is_required: true })
  public content!: string;

  @Field({ field_name: 'author_id' })
  public authorId!: string;
}

// Main application logic
async function main() {
  try {
    // Create a user
    const user = new User();
    user.name = 'Alice Johnson';
    user.email = 'alice@example.com';
    user.createdAt = new Date().toISOString();
    await user.save();

    console.log('✅ User created:', user.getId());

    // Create a post by this user
    const post = new Post();
    post.title = 'My First Post';
    post.content = 'This is the content of my first post!';
    post.authorId = user.getId();
    await post.save();

    console.log('✅ Post created:', post.getId());

    // Load user with their posts
    const userWithPosts = new User();
    await userWithPosts.load(user.getId());
    const posts = await userWithPosts.loadHasMany('posts');

    console.log(`✅ ${userWithPosts.name} has ${posts.length} post(s)`);

    // Query all users
    const allUsers = await User.getAll();
    console.log(`✅ Total users: ${allUsers.length}`);

  } catch (error) {
    console.error('❌ Error:', error);
  }
}

// Run the example
main();
```

--------------------------------

### Error Handling Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Provides an example of how to handle potential errors during database operations, specifically when loading a non-existent user. It demonstrates using a try-catch block to manage exceptions and log appropriate messages.

```typescript
try {
  const user = new User();
  await user.load('non-existent-id');
} catch (error) {
  if (error.message.includes('not found')) {
    console.log('User not found');
  } else {
    console.error('Database error:', error);
  }
}
```

--------------------------------

### Install Firebase ORM (Client-Side)

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

Installs the Firebase ORM package along with Firebase client SDK and RxFire for client-side applications using npm.

```bash
npm install @arbel/firebase-orm firebase rxfire moment --save
```

--------------------------------

### Client-Side Firebase Initialization

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

Initializes the Firebase app and Firestore instance for web applications and sets up the global connection for Firebase ORM.

```typescript
import { initializeApp } from 'firebase/app';
import { getFirestore } from 'firebase/firestore';
import { FirestoreOrmRepository } from '@arbel/firebase-orm';

const firebaseConfig = {
  apiKey: "your-api-key",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "123456789",
  appId: "your-app-id"
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);
const firestore = getFirestore(app);

// Initialize Firebase ORM
FirestoreOrmRepository.initGlobalConnection(firestore);
```

--------------------------------

### Create a New Record

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Demonstrates creating a new 'User' instance, setting its properties, and saving it to Firestore.

```typescript
// Create a new user
const user = new User();
user.name = 'John Doe';
user.email = 'john@example.com';
user.bio = 'Software developer';
user.createdAt = new Date().toISOString();

// Save to Firestore
await user.save();

console.log('User created with ID:', user.getId());
```

--------------------------------

### Install Firebase ORM (Server-Side)

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

Installs the Firebase ORM package along with Firebase Admin SDK and Moment for server-side Node.js applications using npm.

```bash
npm install @arbel/firebase-orm firebase-admin moment --save
```

--------------------------------

### Initialize Firebase and Firestore ORM

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Configures and initializes Firebase with provided credentials and sets up the global connection for the Firestore ORM repository.

```typescript
// config/firebase.ts
import { initializeApp } from 'firebase/app';
import { getFirestore } from 'firebase/firestore';
import { FirestoreOrmRepository } from '@arbel/firebase-orm';

const firebaseConfig = {
  apiKey: "your-api-key",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "123456789",
  appId: "your-app-id"
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);
const firestore = getFirestore(app);

// Initialize Firebase ORM
FirestoreOrmRepository.initGlobalConnection(firestore);
```

--------------------------------

### Advanced Querying with Firebase ORM

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Provides examples of complex queries, including filtering, ordering, limiting results, and implementing pagination using cursor-based approaches.

```typescript
// Complex queries
const activeUsers = await User.query()
  .where('isActive', '==', true)
  .where('createdAt', '>', '2024-01-01')
  .orderBy('createdAt', 'desc')
  .limit(10)
  .get();

// Pagination
const firstPage = await User.query()
  .orderBy('name')
  .limit(5)
  .get();

// Get next page using the last document
const lastDoc = firstPage[firstPage.length - 1];
const nextPage = await User.query()
  .orderBy('name')
  .startAfter(lastDoc.name)
  .limit(5)
  .get();
```

--------------------------------

### Firebase Configuration with Environment Variables

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

Demonstrates how to configure Firebase using environment variables for dynamic settings in production applications.

```typescript
const firebaseConfig = {
  apiKey: process.env.FIREBASE_API_KEY,
  authDomain: process.env.FIREBASE_AUTH_DOMAIN,
  projectId: process.env.FIREBASE_PROJECT_ID,
  storageBucket: process.env.FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.FIREBASE_APP_ID
};
```

--------------------------------

### Server-Side Firebase Initialization (Default Credentials)

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

Initializes the Firebase Admin SDK using default Google Cloud credentials for server-side applications and sets up Firebase ORM.

```typescript
import admin from 'firebase-admin';
import { FirestoreOrmRepository } from '@arbel/firebase-orm';

// Initialize with default credentials
admin.initializeApp();

const firestore = admin.firestore();
FirestoreOrmRepository.initGlobalConnection(firestore);
```

--------------------------------

### Server-Side Firebase Initialization (Service Account)

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

Initializes the Firebase Admin SDK using a service account key for server-side applications and configures Firebase ORM.

```typescript
import admin from 'firebase-admin';
import { FirestoreOrmRepository } from '@arbel/firebase-orm';

// Initialize Firebase Admin
const serviceAccount = require('./path/to/serviceAccountKey.json');

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount),
  databaseURL: "https://your-project-id.firebaseio.com"
});

const firestore = admin.firestore();
FirestoreOrmRepository.initGlobalConnection(firestore);
```

--------------------------------

### Production Deployment Configuration Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/examples/README.md

Provides an example of a configuration file for production deployment, likely related to environment setup, CI/CD pipelines, performance monitoring, and error tracking for Firebase ORM applications.

```yaml
# deployment/production-config.ts
# This is a placeholder for actual YAML content related to deployment configuration.
```

--------------------------------

### Using Relationships (Loading Data)

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Illustrates how to load related data for a user and a post. It shows fetching a user and then their associated posts, and fetching a post and then its author, demonstrating the ORM's relationship traversal capabilities.

```typescript
// Load a user with their posts
const user = new User();
await user.load('user-id-here');

// Load related posts
const posts = await user.loadHasMany('posts');
console.log(`${user.name} has ${posts.length} posts`);

// Load a post with its author
const post = new Post();
await post.load('post-id-here');

const author = await post.loadBelongsTo('author');
console.log(`Post "${post.title}" by ${author.name}`);
```

--------------------------------

### Read Records from Firestore

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Shows how to retrieve all records, load a specific record by ID, and query records based on conditions.

```typescript
// Get all users
const allUsers = await User.getAll();
console.log('All users:', allUsers);

// Get a specific user by ID
const specificUser = new User();
await specificUser.load('user-id-here');
console.log('User:', specificUser.name);

// Find users with conditions
const johnUsers = await User.query()
  .where('name', '==', 'John Doe')
  .get();

console.log('Users named John:', johnUsers);
```

--------------------------------

### Performance Monitoring Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/examples/README.md

Illustrates performance monitoring using a `PerformanceMonitor` utility. It shows how to start monitoring, track specific operations like fetching all users, and measure their execution time.

```typescript
import { PerformanceMonitor } from '../utils/PerformanceMonitor';

// Monitor query performance
const monitor = new PerformanceMonitor();
monitor.startMonitoring();

// Track specific operations
const users = await monitor.trackOperation(
  'User.getAll',
  () => User.getAll()
);
```

--------------------------------

### TypeScript Configuration for Firebase ORM

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

Essential TypeScript compiler options for using Firebase ORM, including decorator support and target ES2017.

```json
{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "strictPropertyInitialization": false,
    "target": "ES2017",
    "lib": ["ES2017", "DOM"]
  }
}
```

--------------------------------

### Real-time Data Updates

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Shows how to subscribe to real-time changes for lists of documents or specific documents using listener functions.

```typescript
// Listen to all user changes
const unsubscribe = User.onList((user) => {
  console.log('User updated:', user.name);
});

// Listen to a specific user
const user = new User();
await user.load('user-id-here');

const unsubscribeUser = user.on(() => {
  console.log('User data changed:', user.name);
});

// Don't forget to unsubscribe when done
// unsubscribe();
// unsubscribeUser();
```

--------------------------------

### Data Validation Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Demonstrates how to add custom data validation to a Firebase ORM model by overriding the save method. It includes an example of validating an email format before saving the user data.

```typescript
@Model({
  reference_path: 'users',
  path_id: 'user_id'
})
export class User extends BaseModel {
  @Field({ is_required: true })
  public email!: string;

  // Override save to add validation
  async save() {
    // Validate email format
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!emailRegex.test(this.email)) {
      throw new Error('Invalid email format');
    }

    // Call parent save method
    return super.save();
  }
}
```

--------------------------------

### Run Example Application

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/examples/README.md

Imports and executes a specific example application, such as the blog example. This demonstrates how to integrate and run a full application using Firebase ORM.

```typescript
// Import and run your chosen example
import { BlogExample } from './examples/blog-example';

const example = new BlogExample();
await example.run();
```

--------------------------------

### Example Project Structure

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/examples/README.md

Outlines a standard directory structure for contributing a new example to the Firebase ORM project. It includes common directories like `models`, `services`, `tests`, and `src`, along with a `README.md` for example-specific documentation.

```plaintext
examples/
├── your-example/
│   ├── README.md           # Example-specific documentation
│   ├── models/             # Model definitions
│   ├── services/           # Business logic
│   ├── tests/              # Test files
│   ├── package.json        # Dependencies
│   └── src/
│       ├── index.ts        # Main application file
│       └── config/         # Configuration files
```

--------------------------------

### Update a Record

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Illustrates loading an existing user record from Firestore, modifying its properties, and saving the changes.

```typescript
// Load an existing user
const user = new User();
await user.load('user-id-here');

// Update properties
user.name = 'John Smith';
user.bio = 'Senior Software Developer';

// Save changes
await user.save();

console.log('User updated!');
```

--------------------------------

### TypeScript Configuration for Decorators

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Specifies TypeScript compiler options required for using decorators, including experimental decorators and emit decorator metadata.

```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strictPropertyInitialization": false
  }
}
```

--------------------------------

### Complete Firebase ORM Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/global-configuration.md

A comprehensive example showcasing the setup of Firebase ORM with global configuration for auto-generated path IDs and auto-converted field names. It includes the definition of User and ShoppingCart models and a usage example.

```typescript
import { FirestoreOrmRepository, Model, Field, BaseModel } from '@arbel/firebase-orm';

// Configure global settings
FirestoreOrmRepository.setGlobalConfig({
  auto_lower_case_field_name: true,
  auto_path_id: true
});

// User model with auto-generated path_id and auto-converted field names
@Model({
  reference_path: 'users'
  // path_id auto-generated as "user_id"
})
export class User extends BaseModel {
  @Field({ is_required: true })
  public firstName!: string;  // Stored as "first_name"

  @Field({ is_required: true })
  public lastName!: string;   // Stored as "last_name"

  @Field({ is_required: true })
  public emailAddress!: string; // Stored as "email_address"

  @Field({
    is_required: false,
    field_name: 'avatar_url'  // Custom field name
  })
  public profileImage?: string; // Stored as "avatar_url"
}

// Shopping cart with complex class name
@Model({
  reference_path: 'shopping_carts'
  // path_id auto-generated as "shopping_cart_id"
})
export class ShoppingCart extends BaseModel {
  @Field({ is_required: true })
  public cartItems!: string[];  // Stored as "cart_items"

  @Field({ is_required: true })
  public totalPrice!: number;   // Stored as "total_price"

  @Field({ is_required: true })
  public createdAt!: string;    // Stored as "created_at"
}

// Usage
async function example() {
  const user = new User();
  user.firstName = 'John';
  user.lastName = 'Doe';
  user.emailAddress = 'john@example.com';
  
  await user.save();
  
  console.log('User saved with auto-generated path_id:', user.pathId); // "user_id"
  console.log('Database data:', user.getData()); 
  // { first_name: 'John', last_name: 'Doe', email_address: 'john@example.com' }
}

```

--------------------------------

### Delete a Record

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Demonstrates loading a user record and then deleting it from Firestore.

```typescript
// Load and delete a user
const user = new User();
await user.load('user-id-here');
await user.destroy();

console.log('User deleted!');
```

--------------------------------

### Import Firebase ORM (ESM)

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

Imports core Firebase ORM classes using the ECMAScript Modules (ESM) system, suitable for modern JavaScript and TypeScript projects.

```javascript
import { FirestoreOrmRepository, BaseModel, Field, Model } from "@arbel/firebase-orm";
```

--------------------------------

### Define a User Model

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Defines a 'User' model extending BaseModel with fields like name, email, createdAt, and bio, using decorators for ORM configuration.

```typescript
// models/User.ts
import { BaseModel, Model, Field } from '@arbel/firebase-orm';

@Model({
  reference_path: 'users',
  path_id: 'user_id'
})
export class User extends BaseModel {
  @Field({ is_required: true })
  public name!: string;

  @Field({ is_required: true })
  public email!: string;

  @Field({ field_name: 'created_at' })
  public createdAt?: string;

  @Field({ is_required: false })
  public bio?: string;

  // Helper method
  getDisplayName(): string {
    return this.name || this.email;
  }
}
```

--------------------------------

### Define Relationships (Post and User Models)

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Demonstrates how to define one-to-many and belongs-to relationships between Post and User models using decorators. It specifies reference paths, primary keys, and foreign keys for establishing these connections.

```typescript
import { HasMany, BelongsTo } from '@arbel/firebase-orm';

@Model({
  reference_path: 'posts',
  path_id: 'post_id'
})
export class Post extends BaseModel {
  @Field({ is_required: true })
  public title!: string;

  @Field({ is_required: true })
  public content!: string;

  @Field({ field_name: 'author_id' })
  public authorId!: string;

  @BelongsTo({ model: User, localKey: 'authorId' })
  public author?: User;
}

@Model({
  reference_path: 'users',
  path_id: 'user_id'
})
export class User extends BaseModel {
  // ... existing fields ...

  @HasMany({ model: Post, foreignKey: 'author_id' })
  public posts?: Post[];
}
```

--------------------------------

### Timestamp Management

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Shows how to automatically manage `createdAt` and `updatedAt` timestamps for Firebase ORM models. The `save` method is overridden to set these fields appropriately for both new and existing records.

```typescript
@Model({
  reference_path: 'posts',
  path_id: 'post_id'
})
export class Post extends BaseModel {
  @Field({ field_name: 'created_at' })
  public createdAt?: string;

  @Field({ field_name: 'updated_at' })
  public updatedAt?: string;

  // Override save to add timestamps
  async save() {
    const now = new Date().toISOString();
    
    if (!this.getId()) {
      // New record
      this.createdAt = now;
    }
    
    this.updatedAt = now;
    
    return super.save();
  }
}
```

--------------------------------

### Install Firebase ORM

Source: https://github.com/yarivluts/firebase-orm/blob/master/README.md

Command to install the Firebase ORM package along with its dependencies, moment, using npm.

```bash
npm install @arbel/firebase-orm firebase moment --save
```

--------------------------------

### Install Firebase ORM and Dependencies

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/frameworks/react.md

Installs the necessary packages for Firebase ORM, Firebase, moment, and development type definitions using npm.

```bash
npm install @arbel/firebase-orm firebase moment --save
npm install --save-dev @types/node
```

--------------------------------

### Install Firebase ORM and Dependencies

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/frameworks/nodejs.md

Installs the necessary packages for Firebase ORM integration and development tools using npm.

```bash
npm install @arbel/firebase-orm firebase-admin moment --save
npm install --save-dev @types/node nodemon ts-node typescript
```

--------------------------------

### Import Firebase ORM (CommonJS)

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/installation.md

Imports core Firebase ORM classes using the CommonJS module system, typically used in Node.js environments.

```javascript
const { FirestoreOrmRepository, BaseModel, Field, Model } = require("@arbel/firebase-orm");
```

--------------------------------

### Initialize Firebase ORM

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/examples/README.md

Initializes the Firebase app and Firestore instance, then sets up the global connection for Firebase ORM. This step is crucial for using the ORM's functionalities.

```typescript
// app.ts
import { initializeApp } from 'firebase/app';
import { getFirestore } from 'firebase/firestore';
import { FirestoreOrmRepository } from '@arbel/firebase-orm';
import { firebaseConfig } from './firebase-config';

const app = initializeApp(firebaseConfig);
const firestore = getFirestore(app);
FirestoreOrmRepository.initGlobalConnection(firestore);
```

--------------------------------

### Initialize Firebase and Configure Global Settings

Source: https://github.com/yarivluts/firebase-orm/blob/master/README.md

TypeScript code snippet demonstrating the initialization of Firebase and the Firestore ORM repository with global connection and configuration settings.

```typescript
import { initializeApp } from 'firebase/app';
import { getFirestore } from 'firebase/firestore';
import { FirestoreOrmRepository } from '@arbel/firebase-orm';

const app = initializeApp(firebaseConfig);
const firestore = getFirestore(app);
FirestoreOrmRepository.initGlobalConnection(firestore);

// Configure global settings for automatic field naming and path_id generation
FirestoreOrmRepository.setGlobalConfig({
  auto_lower_case_field_name: true, // cartItem → cart_item
  auto_path_id: true                // User class → user_id
});
```

--------------------------------

### TypeScript SensitiveData Model Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/advanced/security.md

An example of a TypeScript class `SensitiveData` that extends `BaseModel` and utilizes the `@EncryptedField` decorator for sensitive properties like 'ssn' and 'creditCard'. It includes a method `getEncryptionKey` for retrieving the encryption key, with a fallback to a default key.

```typescript
// Usage
@Model({
  reference_path: "sensitive_data",
  path_id: "data_id"
})
export class SensitiveData extends BaseModel {
  @Field({ is_required: true })
  public name!: string;

  @EncryptedField({ field_name: "encrypted_ssn" })
  public ssn!: string;

  @EncryptedField({ field_name: "encrypted_credit_card" })
  public creditCard!: string;

  private getEncryptionKey(): string {
    // In production, use proper key management
    return process.env.ENCRYPTION_KEY || 'default-key';
  }
}
```

--------------------------------

### Initialize Firebase ORM with Admin SDK

Source: https://github.com/yarivluts/firebase-orm/blob/master/README.md

Demonstrates how to initialize the Firebase ORM repository using the Firebase Admin SDK. This includes setting up the Admin app with credentials and optionally initializing the global storage.

```typescript
import * as admin from "firebase-admin";
import { FirestoreOrmRepository } from "@arbel/firebase-orm";

// Initialize Firebase Admin with your credentials
const adminApp = admin.initializeApp({
  credential: admin.credential.cert(serviceAccount),
  databaseURL: "https://your-project-id.firebaseio.com",
  storageBucket: "your-project-id.appspot.com"
});

// Initialize Firebase ORM with the Admin app
FirestoreOrmRepository.initializeAdminApp(adminApp);

// Initialize storage (optional)
const adminStorage = admin.storage();
FirestoreOrmRepository.initGlobalStorage(adminStorage);
```

--------------------------------

### HasMany Relationship Setup

Source: https://github.com/yarivluts/firebase-orm/blob/master/README.md

Sets up a HasMany relationship, typically for parent-child scenarios, where one model can have multiple related records. For example, a User having many Posts.

```typescript
// Define the "many" side (Post belongs to User)
@Model({
  reference_path: 'posts',
  path_id: 'post_id'
})
class Post extends BaseModel {
  @Field({ is_required: true })
  public title!: string;

  @Field({ is_required: true, field_name: 'author_id' })
  public authorId!: string;  // Foreign key to User

  // Each post belongs to one user
  @BelongsTo({
    model: User,
    localKey: 'authorId'
  })
  public author?: User;
}

// Define the "one" side (User has many Posts)
@Model({
  reference_path: 'users',
  path_id: 'user_id'
})
class User extends BaseModel {
  @Field({ is_required: true })
  public name!: string;

  // User has many posts
  @HasMany({
    model: Post,              // The model that contains the foreign key
    foreignKey: 'author_id'   // The field in Post that references this User
  })
  public posts?: Post[];
}
```

--------------------------------

### Integration Testing with Blog Service

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/examples/README.md

Demonstrates integration testing for the BlogService, including setting up and cleaning the test environment, creating a blog post, and verifying its retrieval. This example utilizes `beforeEach` and `afterEach` hooks for environment management.

```typescript
import { BlogService } from '../services/BlogService';
import { setupTestEnvironment, cleanupTestEnvironment } from '../utils/test-setup';

describe('Blog Service Integration', () => {
  beforeEach(async () => {
    await setupTestEnvironment();
  });

  afterEach(async () => {
    await cleanupTestEnvironment();
  });

  test('should create and retrieve blog post', async () => {
    const blogService = new BlogService();
    const post = await blogService.createPost({
      title: 'Test Post',
      content: 'Test content'
    });

    const retrievedPost = await blogService.getPost(post.getId());
    expect(retrievedPost.title).toBe('Test Post');
  });
});
```

--------------------------------

### Firebase ORM Dependency Update

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/guides/migration.md

Provides the npm commands to uninstall the older version of 'firebase-orm' and install the new version '@arbel/firebase-orm' along with 'firebase' and 'moment'.

```bash
# Uninstall old version
npm uninstall firebase-orm

# Install new version
npm install @arbel/firebase-orm firebase moment
```

--------------------------------

### Example Usage: Creating and Saving Models

Source: https://github.com/yarivluts/firebase-orm/blob/master/examples/global-configuration-example.md

Demonstrates the creation and saving of User, ShoppingCart, and Product instances using the defined models. It logs the generated IDs and the data stored in the database, highlighting the effect of global configurations on field names.

```typescript
async function example() {
  // Create a user
  const user = new User();
  user.firstName = 'John';
  user.lastName = 'Doe';
  user.emailAddress = 'john.doe@example.com';
  user.phoneNumber = '+1-555-0123';
  
  await user.save();
  console.log('User ID:', user.getId());
  console.log('Path ID:', user.pathId);  // 'user_id'
  
  // Create a shopping cart
  const cart = new ShoppingCart();
  cart.userId = user.getId();
  cart.cartItems = ['item1', 'item2', 'item3'];
  cart.totalPrice = 99.99;
  cart.discountCode = 'SAVE10';
  cart.createdAt = new Date().toISOString();
  
  await cart.save();
  console.log('Cart ID:', cart.getId());
  console.log('Path ID:', cart.pathId);  // 'shopping_cart_id'
  
  // Create a product
  const product = new Product();
  product.productName = 'Awesome Widget';
  product.categoryId = 'widgets';
  product.imageURL = 'https://example.com/widget.jpg';
  product.priceInCents = 2999;  // $29.99
  
  await product.save();
  console.log('Product ID:', product.getId());
  console.log('Path ID:', product.pathId);  // 'custom_product_id'
  
  // Examine stored data
  console.log('User data:', user.getData());
  // {
  //   first_name: 'John',
  //   last_name: 'Doe', 
  //   email_address: 'john.doe@example.com',
  //   phone_number: '+1-555-0123'
  // }
  
  console.log('Cart data:', cart.getData());
  // {
  //   user_id: 'user123',
  //   cart_items: ['item1', 'item2', 'item3'],
  //   total_price: 99.99,
  //   discount_code: 'SAVE10',
  //   created_timestamp: '2023-12-01T10:00:00.000Z'
  // }
  
  console.log('Product data:', product.getData());
  // {
  //   product_name: 'Awesome Widget',
  //   category_id: 'widgets',
  //   image_u_r_l: 'https://example.com/widget.jpg',
  //   price_cents: 2999
  // }
}
```

--------------------------------

### Firebase ORM Create Blog Post Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/README.md

Demonstrates how to create a new blog post with associated user and tags using Firebase ORM. It shows the process of instantiating models, setting properties, establishing relationships, and saving them to the database.

```typescript
// Usage Examples:

// Create a new blog post with relationships
async function createBlogPost() {
  // 1. Create or load the author
  const author = new User();
  author.name = "John Doe";
  author.email = "john@example.com";
  author.createdAt = new Date().toISOString();
  await author.save();

  // 2. Create the post
  const post = new Post();
  post.title = "Getting Started with Firebase ORM";
  post.content = "This is a comprehensive guide...";
  post.authorId = author.getId();
  post.status = 'published';
  post.publishedAt = new Date().toISOString();
  await post.save();

  // 3. Create some tags
  const jsTag = new Tag();
  jsTag.name = "JavaScript";
  jsTag.description = "JavaScript programming language";
  await jsTag.save();

  const ormTag = new Tag();
  ormTag.name = "ORM";
  ormTag.description = "Object-Relational Mapping";
  await ormTag.save();

  // 4. Associate tags with the post using the junction table
  const postTag1 = new PostTag();
  postTag1.postId = post.getId();
  postTag1.tagId = jsTag.getId();
  await postTag1.save();

  const postTag2 = new PostTag();
  postTag2.postId = post.getId();
  postTag2.tagId = ormTag.getId();
  await postTag2.save();

  console.log('Blog post created successfully!');
}

// Example of calling the function:
// createBlogPost().catch(console.error);
```

--------------------------------

### HasOne Relationship Setup

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/relationships.md

Defines a HasOne relationship where another model holds the foreign key referencing the current model. Includes database structure and usage examples for loading the related model.

```typescript
@Model({
  reference_path: 'users',
  path_id: 'user_id'
})
class User extends BaseModel {
  @Field({ is_required: true })
  public name!: string;

  // Define the relationship
  @HasOne({
    model: UserProfile,     // The model that has the foreign key
    foreignKey: 'user_id'   // The field in UserProfile that references this User
  })
  public profile?: UserProfile;
}

// Usage:
// Load a user and their profile
// const user = new User();
// await user.load('user-1');

// Load the related profile
// const profile = await user.loadHasOne('profile');
// console.log(profile.bio); // "Software developer"
```

--------------------------------

### BelongsTo Relationship Setup

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/relationships.md

Defines a BelongsTo relationship where the current model holds the foreign key referencing another model. Includes database structure and usage examples for loading the related model.

```typescript
import { Field, BaseModel, Model, BelongsTo } from "@arbel/firebase-orm";

// First, define the target model (User)
@Model({
  reference_path: 'users',
  path_id: 'user_id'
})
class User extends BaseModel {
  @Field({ is_required: true })
  public name!: string;
}

// Then, define the model with the foreign key (UserProfile)
@Model({
  reference_path: 'user_profiles',
  path_id: 'profile_id'
})
class UserProfile extends BaseModel {
  @Field({ is_required: true, field_name: 'user_id' })
  public userId!: string;  // This is the foreign key

  @Field({ is_required: false })
  public bio?: string;

  // Define the relationship
  @BelongsTo({
    model: User,           // The target model class
    localKey: 'userId'     // The local field containing the foreign key
  })
  public user?: User;      // Optional property to hold the loaded relationship
}

// Usage:
// Load a profile and its related user
// const profile = new UserProfile();
// await profile.load('profile-1');

// Method 1: Load the relationship explicitly
// const user = await profile.loadBelongsTo('user');
// console.log(user.name); // "John Doe"

// Method 2: Access the loaded relationship (after loading)
// await profile.loadWithRelationships(['user']);
// console.log(profile.user?.name); // "John Doe"
```

--------------------------------

### Domain Logic Examples

Source: https://github.com/yarivluts/firebase-orm/blob/master/README.md

Illustrates common operations using Arbel Firebase ORM, including creating records, working with hierarchical data, querying, real-time updates, managing relationships, and performing text searches.

```javascript
// Create a new user
const user = new User();
user.name = "John Doe";
user.email = "john@example.com";
user.createdAt = new Date().toISOString();
await user.save();

// Work with hierarchical data
const website = await Website.findOne('domain', '==', 'www.google.com');
const members = await website.getModel(Member).getAll();
console.log(`${website.domain} has ${members.length} members`);

// Query users
const activeUsers = await User.query()
  .where('isActive', '==', true)
  .orderBy('createdAt', 'desc')
  .limit(10)
  .get();

// Real-time updates
const unsubscribe = User.onList((user) => {
  console.log('User updated:', user.name);
});

// Relationships
const posts = await user.loadHasMany('posts');
console.log(`${user.name} has ${posts.length} posts`);

// Text search
const searchResults = await User.query()
  .like('name', '%john%')
  .get();
```

--------------------------------

### GitHub Actions CI/CD Example

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/frameworks/nodejs.md

A GitHub Actions workflow for deploying the application to production, including testing and deployment steps.

```yaml
# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to server
        run: |
          # Add your deployment commands here
          echo "Deploying to production..."
```

--------------------------------

### Firebase Authentication Service

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/advanced/security.md

Handles user authentication operations like sign-up, sign-in, getting the current user, and sign-out using Firebase Authentication. It integrates with a User model for data persistence.

```typescript
import { getAuth, signInWithEmailAndPassword, createUserWithEmailAndPassword } from 'firebase/auth';
import { FirestoreOrmRepository } from '@arbel/firebase-orm';

export class AuthService {
  private auth = getAuth();

  async signUp(email: string, password: string, userData: any): Promise<User> {
    try {
      // Create Firebase Auth user
      const userCredential = await createUserWithEmailAndPassword(this.auth, email, password);
      
      // Create user model
      const user = new User();
      user.setId(userCredential.user.uid);
      user.email = email;
      user.name = userData.name;
      user.createdAt = new Date().toISOString();
      
      await user.save();
      return user;
    } catch (error) {
      console.error('Sign up failed:', error);
      throw error;
    }
  }

  async signIn(email: string, password: string): Promise<User> {
    try {
      const userCredential = await signInWithEmailAndPassword(this.auth, email, password);
      
      // Load user model
      const user = new User();
      await user.load(userCredential.user.uid);
      
      // Update last login
      await user.updateLastLogin();
      
      return user;
    } catch (error) {
      console.error('Sign in failed:', error);
      throw error;
    }
  }

  async getCurrentUser(): Promise<User | null> {
    const firebaseUser = this.auth.currentUser;
    if (!firebaseUser) return null;

    try {
      const user = new User();
      await user.load(firebaseUser.uid);
      return user;
    } catch (error) {
      console.error('Failed to load current user:', error);
      return null;
    }
  }

  async signOut(): Promise<void> {
    await this.auth.signOut();
  }
}
```

--------------------------------

### Conditional Real-time Subscriptions

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/realtime.md

This example demonstrates how to conditionally set up real-time listeners based on specific criteria. The `ConditionalRealtimeService` class manages subscriptions, starting or stopping them based on a provided condition, ensuring listeners are active only when necessary.

```typescript
class ConditionalRealtimeService {
  private activeSubscriptions = new Map<string, () => void>();

  startListening(key: string, condition: boolean) {
    if (condition && !this.activeSubscriptions.has(key)) {
      const unsubscribe = this.setupSubscription(key);
      this.activeSubscriptions.set(key, unsubscribe);
    } else if (!condition && this.activeSubscriptions.has(key)) {
      this.stopListening(key);
    }
  }

  stopListening(key: string) {
    const unsubscribe = this.activeSubscriptions.get(key);
    if (unsubscribe) {
      unsubscribe();
      this.activeSubscriptions.delete(key);
    }
  }

  private setupSubscription(key: string): () => void {
    switch (key) {
      case 'users':
        return User.onList(user => this.handleUserUpdate(user));
      case 'posts':
        return Post.onList(post => this.handlePostUpdate(post));
      default:
        return () => {};
    }
  }
}

// Usage based on user interaction
const service = new ConditionalRealtimeService();

// Start listening when user opens users page
service.startListening('users', userIsOnUsersPage);

// Stop listening when user navigates away
service.startListening('users', false);
```

--------------------------------

### Vanilla Firestore vs. Firebase ORM for Real-time Subscriptions

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/basic-concepts.md

Compares the setup complexity of vanilla Firestore for real-time data updates with the elegant and type-safe approach provided by Firebase ORM.

```javascript
const unsubscribe = onSnapshot(
  collection(firestore, 'users'),
  (snapshot) => {
    snapshot.docChanges().forEach((change) => {
      if (change.type === 'added') {
        const userData = change.doc.data();
        // Manual object creation and type casting
      }
    });
  }
);

// Firebase ORM - elegant and type-safe
const unsubscribe = User.onList((user) => {
  // 'user' is automatically a typed User instance
  console.log(`New user: ${user.name}`);
});
```

--------------------------------

### Firebase Configuration

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/examples/README.md

Defines the Firebase project configuration settings, including API key, auth domain, and project ID. This configuration is essential for connecting to your Firebase project.

```typescript
// firebase-config.ts
export const firebaseConfig = {
  apiKey: "your-api-key",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "your-sender-id",
  appId: "your-app-id"
};
```

--------------------------------

### Soft Deletes Implementation

Source: https://github.com/yarivluts/firebase-orm/blob/master/docs/quick-start.md

Illustrates how to implement soft deletes in Firebase ORM models. This involves adding fields like `isActive` and `deletedAt` and overriding methods like `softDelete` and `getAll` to manage deleted records.

```typescript
@Model({
  reference_path: 'users',
  path_id: 'user_id'
})
export class User extends BaseModel {
  @Field({ is_required: false, default_value: true })
  public isActive?: boolean;

  @Field({ field_name: 'deleted_at' })
  public deletedAt?: string;

  // Soft delete method
  async softDelete() {
    this.isActive = false;
    this.deletedAt = new Date().toISOString();
    await this.save();
  }

  // Override getAll to exclude soft deleted records
  static async getAll() {
    return await User.query()
      .where('isActive', '==', true)
      .get();
  }
}
```

--------------------------------

### Handle Firebase Initialization Errors Gracefully

Source: https://github.com/yarivluts/firebase-orm/blob/master/COLLECTION_FUNCTION_FIX.md

Shows how to wrap Firebase operations in a try-catch block to handle potential initialization errors. If the setup is not complete, a specific error message is logged, guiding the user to await initialization.

```javascript
try {
    const post = new Post();
    await post.save(); // This will work if setup is complete
} catch (error) {
    // Now you get: "Firebase functions not initialized. Repository setup is not complete. 
    // Use async methods or ensure initGlobalConnection is awaited."
    console.log(error.message);
}
```
Tokens:
Raw