Firebase Realtime Database Modeler

Common errors

• TS2339: Property 'database' does not exist on type 'typeof firebase'.

  cause Incorrect or incomplete Firebase SDK import for Realtime Database, often happening when using modular Firebase v9+ without the compat layer or specific database service imports.
  fix Ensure you have correctly imported the Realtime Database service. For Firebase v8 or compat mode: `import firebase from 'firebase/compat/app'; import 'firebase/compat/database';`. For modular v9+: `import { getDatabase } from 'firebase/database';` and initialize the database instance from `getDatabase(app)`.

• TS2345: Argument of type '{ name: string; rating: number; open: boolean; users: { [x: string]: { name: string; }; }; }' is not assignable to parameter of type 'StoreModel'.

  cause Attempting to call `_set()` with an object that omits properties defined as non-nullable in the model for that path. `_set()` expects a complete object matching the model's required properties.
  fix Either provide all required properties for the `_set()` call or, if you intend to perform a partial update, target a more specific child node in your model (e.g., `stores.$storeId.name._set(newName, storeId)`). Alternatively, adjust your model definition to mark properties as optional (`_<Type | null>('dbKey')`) if they are not always present.

• TypeError: Cannot read properties of undefined (reading '_set')

  cause This typically means the underlying Firebase Realtime Database reference is `undefined`, often because `modelerSetDefaultDatabase` was not called or an invalid database instance was passed to `_root` or `._ref()`.
  fix Verify that `modelerSetDefaultDatabase(firebase.database());` has been executed before any model operations, or that the `database` argument was correctly passed to your `_root()` model definition.

Warnings

• gotcha Operations on a model node will fail if a default Firebase Realtime Database instance has not been set or explicitly passed to the root node or `_ref()` function.
  Fix: Ensure `modelerSetDefaultDatabase(firebase.database());` is called once during application initialization, or pass the database instance directly to `_root({...}, database)` or `node._ref(database)` calls.
• gotcha When using `_set()` on a model node, all properties defined in the model for that specific path segment are considered required, unless explicitly marked with `| null` in the model definition. Attempting a partial update with `_set()` will result in a TypeScript error or data loss for omitted fields.
  Fix: To perform a partial update, target the specific child node you wish to modify (e.g., `stores.$storeId.name._set(newName, storeId)` instead of `stores.$storeId._set(...)`). If a property can be optional, define it with `_<Type | null>('dbKey')` in your model.
• gotcha The library allows property key aliasing where the model property name differs from the actual database key (e.g., `name: _<string>('n')`). This is powerful but can be a source of confusion if not carefully managed, as direct database path manipulation will use the database key, not the model property name.
  Fix: Be explicit in your model definitions and ensure consistency. Remember that the model property name (`name`) is for TypeScript and IntelliSense, while the string in `_('n')` is the actual key used in Firebase Realtime Database paths.
• gotcha Variable path segments, defined with `_$()`, require the actual value for that segment to be passed as the last argument to operations like `_set()`, `_onceVal()`, `_ref()`, etc. (e.g., `stores.$storeId._set(data, storeId)`). Forgetting to pass the variable value will lead to incorrect paths.
  Fix: Always provide the concrete value for dynamic path segments as the final argument to any database operation method on a variable node. The type system will typically guide you, but be mindful during refactoring.

Install

• npm install firebase-database-modeler npm
• yarn add firebase-database-modeler yarn
• pnpm add firebase-database-modeler pnpm

Imports

• modelerSetDefaultDatabase
  wrong:

  const { modelerSetDefaultDatabase } = require('firebase-database-modeler');

  correct:

  import { modelerSetDefaultDatabase } from 'firebase-database-modeler';

  This library primarily uses ES Modules. `require()` syntax will not work. This function sets the global Firebase Realtime Database instance.
• _, _$
  wrong:

  import ModelNodes from 'firebase-database-modeler';

  correct:

  import { _, _$ } from 'firebase-database-modeler';

  These are named exports for defining regular and variable database nodes. There is no default export for these utilities.
• _root
  wrong:

  import { root } from 'firebase-database-modeler';

  correct:

  import { _root } from 'firebase-database-modeler';

  The root model definition function is specifically named `_root`.

Quickstart

This quickstart demonstrates defining a typed model for a Firebase Realtime Database 'stores' collection, initializing Firebase, setting the default database for the modeler, and performing type-safe create, update, and fetch operations using the defined model with dynamic path segments.

import { _, _$, _root, modelerSetDefaultDatabase } from 'firebase-database-modeler';
import firebase from 'firebase/compat/app';
import 'firebase/compat/database';

// Initialize Firebase (replace with your actual config)
const firebaseConfig = {
  apiKey: process.env.FIREBASE_API_KEY ?? 'YOUR_API_KEY',
  authDomain: process.env.FIREBASE_AUTH_DOMAIN ?? 'YOUR_AUTH_DOMAIN',
  projectId: process.env.FIREBASE_PROJECT_ID ?? 'YOUR_PROJECT_ID',
  storageBucket: process.env.FIREBASE_STORAGE_BUCKET ?? 'YOUR_STORAGE_BUCKET',
  messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID ?? 'YOUR_MESSAGING_SENDER_ID',
  appId: process.env.FIREBASE_APP_ID ?? 'YOUR_APP_ID',
  databaseURL: process.env.FIREBASE_DATABASE_URL ?? 'YOUR_DATABASE_URL'
};

if (!firebase.apps.length) {
  firebase.initializeApp(firebaseConfig);
}

const database = firebase.database();
modelerSetDefaultDatabase(database);

const stores = _('stores', {
  $storeId: _$1({
    name: _<string>('n'), // DB key 'n' for model property 'name'
    rating: _<number>('rating'),
    open: _<boolean>('open'),
    optionalProp: _<number | null>('oP'), // Optional property
    users: _('users', {
      $userId: _$1({
        name: _<string>('name')
      })
    })
  })
});

const root = _root({
  stores
});

async function createStore(storeId: string, userId: string, userName: string) {
  // All non-null model properties for the current path must be provided.
  await stores.$storeId._set({
    name: 'Cool Store', 
    rating: 4.2,
    open: true,
    users: {
      [userId]: {
        name: userName
      }
    }
  }, storeId);
  console.log(`Store ${storeId} created.`);
}

async function setStoreName(storeId: string, newName: string) {
  // To update a single field, target its specific path.
  await stores.$storeId.name._set(newName, storeId);
  console.log(`Store ${storeId} name updated to ${newName}.`);
}

async function getStore(storeId: string) {
  const store = await stores.$storeId._onceVal('value', storeId);
  console.log(`Fetched store ${storeId}:`, store);
  return store;
}

// Example usage
(async () => {
  const myStoreId = 'store_abc';
  const myUserId = 'user_123';
  await createStore(myStoreId, myUserId, 'Alice');
  await setStoreName(myStoreId, 'Super Cool Store');
  await getStore(myStoreId);
})();