\n\n> LTIJS Firestore plugin.\n\n# Introduction\n\nThis package allows [LTIJS](https://cvmcosta.github.io/ltijs) to work with Firestore instead of MongoDB.\n\n# Installation\n\n```\nnpm install @examind/ltijs-firestore\n```\n\nImport package (TypeScript and ES Modules):\n\n```\nimport { Firestore } from '@examind/ltijs-firestore';\n```\n\nImport package (CommonJS):\n\n```\nconst { Firestore } = require('@examind/ltijs-firestore');\n```\n\nRegister the plugin during [LTIJS](https://cvmcosta.github.io/ltijs) setup:\n\n```\nlti.setup(\n 'LTIKEY',\n { plugin: new Firestore() }\n);\n\n```\n\nThe `Firestore` constructor accepts an options object with the following property:\n\n- `collectionPrefix`: A custom prefix to prepend to all collection paths. Defaults to empty string.\n - Example 1: `ltijs-` will create collections 'ltijs-accsesstoken', 'ltijs-platforms', etc.\n - Example 2: `ltijs/index/` will create subcollections 'ltijs/index/accesstoken', 'ltijs/index/platforms', etc.\n\nExample with options:\n\n```\nlti.setup(\n 'LTIKEY',\n { plugin: new Firestore({collectionPrefix: 'ltijs-'}) }\n);\n\n```\n\n## Firestore Authentication\n\nThe `firebase-admin` library that's used in this package looks for a `LTIJS_APPLICATION_CREDENTIALS` environment variable. That environment variable needs to point to a GCP Service Account key with access to Firestore. For simplicity, you can use the Firebase Admin SDK private key from Firebase Console:\n\n- Select your project from [Firebase Console](https://console.firebase.google.com/)\n- Go to `Project Settings` -> `Service accounts`, then download a new private key:\n\n\n\nSave that file somewhere (e.g. `./service-account.json`), then point `LTIJS_APPLICATION_CREDENTIALS` to that file. If you use [dotenv](https://www.npmjs.com/package/dotenv), then your `.env` file will look like this:\n\n```\nLTIJS_APPLICATION_CREDENTIALS=./service-account.json\n```\n\nIf you prefer to hard code the environment variable inside a Node.js file, you can do this:\n\n```\nprocess.env.LTIJS_APPLICATION_CREDENTIALS = './service-account.json'\n```\n\nNotes:\n\n- Specifying the `LTIJS_APPLICATION_CREDENTIALS` environment variable is recommended, but if not available, `firebase-admin` will also look for a `GOOGLE_APPLICATION_CREDENTIALS` environment variable.\n- When using `LTIJS_APPLICATION_CREDENTIALS`, make sure the environment variable is set before you import `@examind/ltijs-firestore`. Example using dotenv:\n\n```\nimport { config } from 'dotenv';\nif (process.env.NODE_ENV !== 'production') config();\nimport { Firestore } from '@examind/ltijs-firestore';\n```\n\nThe following will also work if you're using dotenv unconditionally:\n\n```\nimport 'dotenv/config';\nimport { Firestore } from '@examind/ltijs-firestore';\n```\n\n- When using `GOOGLE_APPLICATION_CREDENTIALS`, it's not necessary to set the environment variable before you import `@examind/ltijs-firestore`, as `firebase-admin` will lazy load the credentials. For example, this will work:\n\n```\nimport { config } from 'dotenv';\nimport { Firestore } from '@examind/ltijs-firestore';\nif (process.env.NODE_ENV !== 'production') config();\n```\n\n- If running this inside of a GCP server (e.g. GCP Compute Engine, GCP Cloud Function, or GCP Cloud Run), you may omit the `LTIJS_APPLICATION_CREDENTIALS` environment variable, as `GOOGLE_APPLICATION_CREDENTIALS` will be set automatically using the default service account.\n\n## Principle of Least Privilege\n\nAs an alternative to using the Firebase Admin SDK private key, you can choose to only grant the necessary permissions to `@examind/ltijs-firestore`. To do this, [create a custom service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts) with only the `Cloud Datastore User` role and use its key instead.\n\n## Purging Stale Documents\n\nThe default detabase provider of LTIJS uses MongoDB as its storage layer and it's configured to automatically purge stale documents. To set up the same behavior in Firestore, we'll use one of 2 strategies depending on which version of @examind/ltijs-firestore you're using.\n\n### @examind/ltijs-firestore v2+\n\n@examind/litjs-firestore@2+ sets `expiresAt` on the following documents:\n\n- accesstoken\n- contexttoken\n- idtoken\n- nonce\n- state\n\nUse this field set up [Firestore TTL Policies](https://firebase.google.com/docs/firestore/ttl) to auto-purge stale documents. You only need to set this up once.\n\nUsing gcloud, substitute your project ID for {project_id} and execute the following commands. Warning, this will take a while.\n\n```\ngcloud firestore fields ttls update expiresAt --collection-group=accesstoken --enable-ttl --project={project_id}\ngcloud firestore fields ttls update expiresAt --collection-group=contexttoken --enable-ttl --project={project_id}\ngcloud firestore fields ttls update expiresAt --collection-group=idtoken --enable-ttl --project={project_id}\ngcloud firestore fields ttls update expiresAt --collection-group=nonce --enable-ttl --project={project_id}\ngcloud firestore fields ttls update expiresAt --collection-group=state --enable-ttl --project={project_id}\n```\n\nTo ensure that everything worked correctly, you can list all your TTL policies:\n\n```\ngcloud firestore fields ttls list --project={project_id}\n```\n\n#### Upgrade Guide\n\nWhen upgrading from v1.1+, previous TTL policies will need to be deleted as Firestore only allows 1 TTL policy per collection group. You'll also want to amend the existing documents in the database so they include expiresAt fields.\n\nDelete previous TTL policies:\n\n```\ngcloud firestore fields ttls update age1HourAt --collection-group=accesstoken --disable-ttl --project={project_id}\ngcloud firestore fields ttls update age24HoursAt --collection-group=contexttoken --disable-ttl --project={project_id}\ngcloud firestore fields ttls update age24HoursAt --collection-group=idtoken --disable-ttl --project={project_id}\ngcloud firestore fields ttls update age2MinutesAt --collection-group=nonce --disable-ttl --project={project_id}\ngcloud firestore fields ttls update age10MinutesAt --collection-group=state --disable-ttl --project={project_id}\n```\n\nTo add `deletedAt` to existing documents, use firebase-admin to run the following script. \nYou'll need to set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to a gcloud auth key for this to work: `export GOOGLE_APPLICATION_CREDENTIALS='./my-gcloud-auth-key.json'`\n\n```\nconst { initializeApp } = require('firebase-admin/app');\nconst { getFirestore } = require('firebase-admin/firestore');\n\nconst app = initializeApp({ projectId: 'my-project-id' });\nconst db = getFirestore(app);\n\n// Set this if you're using a collection prefix\nconst COLLECTION_PREFIX = '';\n\nconst addMinutes = (date, minutes) =>\n new Date(date.getTime() + minutes * 60000);\n\n(async () => {\n const collectionExpiresInMinutes = {\n accesstoken: 60,\n contexttoken: 24 * 60,\n idtoken: 24 * 60,\n nonce: 2,\n state: 10,\n };\n\n for (const [collection, expiresInMinutes] of Object.entries(\n collectionExpiresInMinutes,\n )) {\n const documents = await db\n .collection(`${COLLECTION_PREFIX}${collection}`)\n .get();\n\n for (const document of documents.docs) {\n if (!document.data().createdAt) continue;\n await document.ref.update({\n expiresAt: addMinutes(\n document.data().createdAt.toDate(),\n expiresInMinutes,\n ),\n });\n }\n }\n\n console.log('Done');\n})();\n```\n\n### @examind/ltijs-firestore v1.1.0 - v1.3.2\n\n@examind/litjs-firestore@1.1.0 - 1.3.2 sets the following fields on all new documents created in Firestore:\n\n- age2MinutesAt\n- age10MinutesAt\n- age1HourAt\n- age24HoursAt\n\nUse these fields to set up [Firestore TTL Policies](https://firebase.google.com/docs/firestore/ttl) to auto-purge stale documents. You only need to set this up once.\n\nUsing gcloud, substitute your project ID for {project_id} and execute the following commands. Warning, this will take a while.\n\n```\ngcloud firestore fields ttls update age1HourAt --collection-group=accesstoken --enable-ttl --project={project_id}\ngcloud firestore fields ttls update age24HoursAt --collection-group=contexttoken --enable-ttl --project={project_id}\ngcloud firestore fields ttls update age24HoursAt --collection-group=idtoken --enable-ttl --project={project_id}\ngcloud firestore fields ttls update age2MinutesAt --collection-group=nonce --enable-ttl --project={project_id}\ngcloud firestore fields ttls update age10MinutesAt --collection-group=state --enable-ttl --project={project_id}\n```\n\nTo ensure that everything worked correctly, you can list all your TTL policies:\n\n```\ngcloud firestore fields ttls list --project={project_id}\n```\n\n### @examind/ltijs-firestore <= v1.0.0\n\nUse [@examind/ltijs-firestore-scheduler](https://www.npmjs.com/package/@examind/ltijs-firestore-scheduler).\n\n# Development\n\nClone this repo, navigate to its location in Terminal and run:\n\n```\n\nnpm ci\nnpm run compile\nnpm link\n\n```\n\nIn another project, link directly to this repo:\n\n```\n\nnpm link @examind/ltijs-firestore\n\n```\n\n## Unit Test\n\nRunning unit tests requires that the Firebase CLI (`firebase-tools`) is installed globally:\n\n```\n\nnpm install -g firebase-tools@12.4.2\nnpm ci\nnpm run compile\nnpm test\n\n```\n\nTo use VS Code's debugger:\n\n- Open VS Code's `JavaScript Debug Terminal`\n- Add breakpoints in `0-provider.js` or `Firestore.ts`\n- Then `npm test` inside `JavaScript Debug Terminal`\n\n# Publish\n\n- Bump version in package.json\n- `npm install`\n- Commit with message: `Release {version, e.g. 0.1.6}`\n","readmeFilename":"README.md"}
![](\"https://raw.githubusercontent.com/Cvmcosta/ltijs/master/docs/logo-300.svg\"){kind=logo}