{"id":16624,"library":"firebase-database-modeler","title":"Firebase Realtime Database Modeler","description":"Firebase Database Modeler is a TypeScript-first library designed to enhance development with the Firebase Realtime Database by providing a structured, strongly-typed modeling layer. Currently at version 2.8.0, it aims to abstract the complexities of database path management and data serialization through a declarative model definition. It offers robust IntelliSense support, automatically converting between the defined model schema and the actual database structure. The library supports integration with `firebase`, `firebase-admin`, and `react-native-firebase`, making it versatile for various JavaScript environments. While a strict release cadence isn't published, the developer indicates active use in a real project, implying ongoing maintenance and feature evolution. Its key differentiation lies in bringing advanced type safety and a clear object-oriented approach to Firebase Realtime Database interactions, simplifying complex data structures and reducing common runtime errors associated with schema mismatches.","status":"active","version":"2.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/SrBrahma/Firebase-Database-Modeler","tags":["javascript","firebase","google","realtime","database","model"],"install":[{"cmd":"npm install firebase-database-modeler","lang":"bash","label":"npm"},{"cmd":"yarn add firebase-database-modeler","lang":"bash","label":"yarn"},{"cmd":"pnpm add firebase-database-modeler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for client-side web applications using the Firebase Realtime Database SDK.","package":"firebase","optional":true},{"reason":"Required for server-side Node.js applications or Firebase Admin SDK usage.","package":"firebase-admin","optional":true},{"reason":"Required for React Native applications using the Firebase Realtime Database SDK.","package":"react-native-firebase","optional":true}],"imports":[{"note":"This library primarily uses ES Modules. `require()` syntax will not work. This function sets the global Firebase Realtime Database instance.","wrong":"const { modelerSetDefaultDatabase } = require('firebase-database-modeler');","symbol":"modelerSetDefaultDatabase","correct":"import { modelerSetDefaultDatabase } from 'firebase-database-modeler';"},{"note":"These are named exports for defining regular and variable database nodes. There is no default export for these utilities.","wrong":"import ModelNodes from 'firebase-database-modeler';","symbol":"_, _$","correct":"import { _, _$ } from 'firebase-database-modeler';"},{"note":"The root model definition function is specifically named `_root`.","wrong":"import { root } from 'firebase-database-modeler';","symbol":"_root","correct":"import { _root } from 'firebase-database-modeler';"}],"quickstart":{"code":"import { _, _$, _root, modelerSetDefaultDatabase } from 'firebase-database-modeler';\nimport firebase from 'firebase/compat/app';\nimport 'firebase/compat/database';\n\n// Initialize Firebase (replace with your actual config)\nconst firebaseConfig = {\n  apiKey: process.env.FIREBASE_API_KEY ?? 'YOUR_API_KEY',\n  authDomain: process.env.FIREBASE_AUTH_DOMAIN ?? 'YOUR_AUTH_DOMAIN',\n  projectId: process.env.FIREBASE_PROJECT_ID ?? 'YOUR_PROJECT_ID',\n  storageBucket: process.env.FIREBASE_STORAGE_BUCKET ?? 'YOUR_STORAGE_BUCKET',\n  messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID ?? 'YOUR_MESSAGING_SENDER_ID',\n  appId: process.env.FIREBASE_APP_ID ?? 'YOUR_APP_ID',\n  databaseURL: process.env.FIREBASE_DATABASE_URL ?? 'YOUR_DATABASE_URL'\n};\n\nif (!firebase.apps.length) {\n  firebase.initializeApp(firebaseConfig);\n}\n\nconst database = firebase.database();\nmodelerSetDefaultDatabase(database);\n\nconst stores = _('stores', {\n  $storeId: _$1({\n    name: _<string>('n'), // DB key 'n' for model property 'name'\n    rating: _<number>('rating'),\n    open: _<boolean>('open'),\n    optionalProp: _<number | null>('oP'), // Optional property\n    users: _('users', {\n      $userId: _$1({\n        name: _<string>('name')\n      })\n    })\n  })\n});\n\nconst root = _root({\n  stores\n});\n\nasync function createStore(storeId: string, userId: string, userName: string) {\n  // All non-null model properties for the current path must be provided.\n  await stores.$storeId._set({\n    name: 'Cool Store', \n    rating: 4.2,\n    open: true,\n    users: {\n      [userId]: {\n        name: userName\n      }\n    }\n  }, storeId);\n  console.log(`Store ${storeId} created.`);\n}\n\nasync function setStoreName(storeId: string, newName: string) {\n  // To update a single field, target its specific path.\n  await stores.$storeId.name._set(newName, storeId);\n  console.log(`Store ${storeId} name updated to ${newName}.`);\n}\n\nasync function getStore(storeId: string) {\n  const store = await stores.$storeId._onceVal('value', storeId);\n  console.log(`Fetched store ${storeId}:`, store);\n  return store;\n}\n\n// Example usage\n(async () => {\n  const myStoreId = 'store_abc';\n  const myUserId = 'user_123';\n  await createStore(myStoreId, myUserId, 'Alice');\n  await setStoreName(myStoreId, 'Super Cool Store');\n  await getStore(myStoreId);\n})();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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)`.","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.","error":"TS2339: Property 'database' does not exist on type 'typeof firebase'."},{"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.","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.","error":"TS2345: Argument of type '{ name: string; rating: number; open: boolean; users: { [x: string]: { name: string; }; }; }' is not assignable to parameter of type 'StoreModel'."},{"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.","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()`.","error":"TypeError: Cannot read properties of undefined (reading '_set')"}],"ecosystem":"npm"}