Registry / database / firestore-storage-core

firestore-storage-core

library7.0.5jsnpmunverified

Core classes, types and utilities for firestore-storage, a TypeScript-first library that provides typesafe repositories around Firestore. Version 7.0.5 is current and stable, with regular releases. Key differentiators: compile-time safety for document paths and queries via generics, automatic base model fields (id, _rawPath), and nested collection support with type-safe parent ID maps. Unlike raw Firestore SDK, it enforces collection and document structures through repository patterns.

database

npm install firestore-storage-core

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FIRESTORE-STORAGE-

firestore-storage-core

databasejavascriptv7.0.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BaseModel

✓ import { BaseModel } from 'firestore-storage-core'

✗ import BaseModel from 'firestore-storage-core'

BaseModel is a named export, not default. The library is ESM-only since v7.

CollectionPath

✓ import { CollectionPath } from 'firestore-storage-core'

✗ const { CollectionPath } = require('firestore-storage-core')

This package is ESM-only; CommonJS require() will not work correctly.

DocumentIds

✓ import type { DocumentIds } from 'firestore-storage-core'

✗ import { DocumentIds } from 'firestore-storage-core'

DocumentIds is a type-only export; using it as a value will cause runtime errors.

Shows how to define a CollectionPath for a top-level collection, generate doc/collection paths, and parse paths back to IDs.

import { BaseModel, CollectionPath, DocumentIds } from 'firestore-storage-core'; // Define a collection path for restaurants const Restaurants = new CollectionPath< 'restaurantId', string >( 'restaurants', 'restaurantId' ); // Generate a document path const docPath = Restaurants.doc({ restaurantId: 'abc123' }); console.log(docPath); // 'restaurants/abc123' // Generate a collection path const colPath = Restaurants.collection(); console.log(colPath); // 'restaurants' // Parse a document path type ParsedIds = DocumentIds<typeof Restaurants>; const parsed = Restaurants.parse('restaurants/xyz456'); console.log(parsed); // { restaurantId: 'xyz456' }

Debug

Known issues

breakingESM-only since v7; CommonJS imports will throw error: ERR_REQUIRE_ESM

fix

Use import syntax instead of require(). Ensure package.json has "type": "module" or use .mjs extension.

affects: >=7.0.0

breakingBaseModel properties (id, _rawPath) are added dynamically during reads and removed before writes. Attempting to use them in query conditions may cause unexpected results.

fix

Do not rely on id or _rawPath in custom logic; treat them as transient read-only metadata.

affects: >=1.0.0

gotchaWhen saving, do not include id or _rawPath in the data object; they are automatically stripped but may cause TypeScript type errors if provided

fix

Use separate interfaces (e.g., CreateReview vs Review) to exclude id from input types.

affects: >=1.0.0

deprecatedThe @Repository decorator is deprecated in favor of explicit repository instantiation; may be removed in future major version

fix

Create repository instances directly without decorator: class MyRepo extends BaseRepository<...>

affects: >=5.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Using require() to import an ESM-only module.

fix

Use import syntax. If you must use require, ensure your project has type: module or use dynamic import: const m = await import('pkg')

Cannot find module 'firestore-storage-core'

Package not installed or incorrect import path.

fix

Install both core and main packages: npm install firestore-storage-core firestore-storage

'DocumentIds' cannot be used as a value because it is a type

Importing a type-only export as a value in .ts file without 'type' modifier.

fix

Use import type { DocumentIds } from 'firestore-storage-core' or 'isolatedModules' enabled

Upgrade

Version history

7.0.5latest on npm

Audit

Dependencies

firestore-storageoptionalThe companion package providing BaseRepository and decorators; firestore-storage-core is the low-level types and utilities

firebase-adminrequiredRequired to initialize Firestore instance via getFirestore()

Agent activity

4 hits · last 30 days

node

Resources

githubssh://git@github.com/freshfox/firestore-storage ↗

packagefirestore-storage-core ↗

homepagehttps://github.com/freshfox/firestore-storage ↗