{"id":16032,"library":"firebase-rules-parser","title":"Firebase Rules Parser","description":"The `firebase-rules-parser` library provides a parser and emulator for Firebase security rules, allowing developers to programmatically load and test Firebase rule files. Its primary use case is facilitating unit testing for Firebase projects, particularly as a companion to `ts-mock-firebase`. The current stable version is 2.0.1, released in May 2019. While it aims to support nearly all Firebase rules language functionality, it explicitly notes limitations with duration, latlong, and timestamp functions. The project's release cadence appears to be slow or inactive since 2019, and it differentiates itself by offering an off-platform rule emulation capability without requiring a live Firebase instance, making it suitable for local development and CI/CD pipelines. It ships with TypeScript types, enhancing developer experience for TypeScript users.","status":"maintenance","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/mindhivefi/firebase-rules-parser","tags":["javascript","firebase","rules","security","parser","typescript"],"install":[{"cmd":"npm install firebase-rules-parser","lang":"bash","label":"npm"},{"cmd":"yarn add firebase-rules-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add firebase-rules-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core parsing engine, moved to peer dependency in v1.0.2 to allow consumers to manage its version.","package":"antlr4","optional":false}],"imports":[{"note":"This is the default export for the interpreter factory. The CommonJS `require` pattern for default exports is often incorrect and might return `undefined` or the whole module object.","wrong":"const createFirebaseRulesIntepreter = require('firebase-rules-parser').createFirebaseRulesIntepreter;","symbol":"createFirebaseRulesIntepreter","correct":"import createFirebaseRulesIntepreter from 'firebase-rules-parser';"},{"note":"This is a named export. Incorrectly importing it as a default export or from a deep path is a common mistake.","wrong":"import createFirebaseRulesContext from 'firebase-rules-parser/createFirebaseRulesContext';","symbol":"createFirebaseRulesContext","correct":"import { createFirebaseRulesContext } from 'firebase-rules-parser';"},{"note":"This is the type for the interpreter instance, not a runtime value. Use `import type` to avoid bundling issues and clearly indicate its type-only nature. Before v2.0.0, it was named `FirebaseRulesIntepreterFacade`.","wrong":"import { FirebaseRulesIntepreter } from 'firebase-rules-parser';","symbol":"FirebaseRulesIntepreter","correct":"import type { FirebaseRulesIntepreter } from 'firebase-rules-parser';"}],"quickstart":{"code":"import createFirebaseRulesIntepreter, { createFirebaseRulesContext } from 'firebase-rules-parser';\n\nconst rulesSource = `\nservice cloud.firestore {\n  match /databases/{database}/documents {\n    match /users/{userId} {\n      allow read: if request.auth.uid == userId;\n      allow write: if request.auth.uid == userId && resource.data.name is string;\n    }\n    match /public/{documentId} {\n      allow read: if true;\n    }\n  }\n}\n`;\n\n// Create an instance of the interpreter\nconst rules = createFirebaseRulesIntepreter();\n// Load your rules source string\nrules.init(rulesSource);\n\n// Create a context object for the access check\nconst context = createFirebaseRulesContext({\n  auth: {\n    uid: 'testUserId123',\n    email: 'test@example.com'\n  },\n  resource: {\n    id: 'testUserId123',\n    data: {\n      name: 'John Doe',\n      value: 123\n    }\n  },\n  // Define triggers for `exists()` and `get()` calls within rules\n  onExistsCall: (path) => {\n    return path === '/databases/DEFAULT/documents/users/testUserId123'; \n  },\n  onGetCall: (path) => {\n    if (path === '/databases/DEFAULT/documents/users/testUserId123') {\n      return {\n        uid: 'testUserId123',\n        name: 'Test User'\n      };\n    }\n    return null;\n  }\n});\n\n// Check access for a specific path and operation\nconst hasReadAccess = rules.hasAccess('/databases/DEFAULT/documents/users/testUserId123', context);\nconsole.log('Read access:', hasReadAccess.read); // Should be true\n\nconst hasWriteAccess = rules.hasAccess('/databases/DEFAULT/documents/users/testUserId123', context);\nconsole.log('Write access:', hasWriteAccess.write); // Should be true\n\nconst noAccessContext = createFirebaseRulesContext({\n  auth: { uid: 'anotherUser' },\n  resource: { id: 'testUserId123', data: { name: 'Another Name' } }\n});\nconst noReadAccess = rules.hasAccess('/databases/DEFAULT/documents/users/testUserId123', noAccessContext);\nconsole.log('No read access:', noReadAccess.read); // Should be false or undefined\n\nconst publicReadAccess = rules.hasAccess('/databases/DEFAULT/documents/public/someDoc', noAccessContext);\nconsole.log('Public read access:', publicReadAccess.read); // Should be true","lang":"typescript","description":"Demonstrates initializing the Firebase rules parser with a rules string and then using it to check read and write access for different paths and authentication contexts."},"warnings":[{"fix":"Update all references from `FirebaseRulesIntepreterFacade` to `FirebaseRulesIntepreter`.","message":"The `FirebaseRulesIntepreterFacade` class was renamed to `FirebaseRulesIntepreter`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `antlr4` is installed in your project: `npm install antlr4` or `yarn add antlr4`.","message":"The `antlr4` dependency was moved from a direct dependency to a peer dependency. Consumers of the library are now responsible for installing `antlr4` themselves.","severity":"gotcha","affected_versions":">=1.0.2"},{"fix":"Always cross-reference critical rule logic with actual Firebase behavior or official documentation. Report discrepancies to the library maintainers if significant.","message":"This library is based on reverse-engineering Firebase rules behavior. There might be subtle differences between its emulation and the actual Firebase rules engine, especially with less common functions (e.g., duration, latlong, timestamp) or newer Firebase features.","severity":"gotcha","affected_versions":"*"},{"fix":"Evaluate against current Firebase security rules documentation. Consider contributing to the project or forking it if specific new features are required.","message":"The project appears to be minimally maintained since its last release in 2019. It may not support newer Firebase rules features or address recent security updates to the Firebase platform itself.","severity":"gotcha","affected_versions":">=2.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use `const createFirebaseRulesIntepreter = require('firebase-rules-parser').default;` for CommonJS, or preferably use ES module imports `import createFirebaseRulesIntepreter from 'firebase-rules-parser';`.","cause":"Attempting to call `init` on an undefined interpreter instance, likely due to incorrect default import syntax for `createFirebaseRulesIntepreter` with CommonJS.","error":"TypeError: Cannot read properties of undefined (reading 'init')"},{"fix":"Install `antlr4` as a direct dependency: `npm install antlr4` or `yarn add antlr4`.","cause":"The `antlr4` library, a peer dependency, is not installed in the project.","error":"Error: Cannot find module 'antlr4'"},{"fix":"Rename `FirebaseRulesIntepreterFacade` to `FirebaseRulesIntepreter` in your code.","cause":"Attempting to reference the old class name `FirebaseRulesIntepreterFacade` after upgrading to v2.0.0 or later.","error":"Property 'FirebaseRulesIntepreterFacade' does not exist on type 'typeof import(\"firebase-rules-parser\")'."}],"ecosystem":"npm"}