@degenerate/generic 0.7.1 → 0.9.1

package/dist/models/application/database/firestore-models.js

@@ -1,43 +1,48 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IDatabaseDeleteItemSchema = exports.IDatabaseGetInformationSchema = exports.IDatabaseQueryFieldsSchema = exports.IDatabaseOrderBySchema = exports.IDatabaseGetItemSchema = exports.WhereFilterOpSchema = exports.OrderByDirectionSchema = exports.IDatabaseUpdatesSchema = exports.IDatabaseRecordAndRefSchema = exports.IDatabasePropertyChangeInformationSchema = exports.IDatabaseChangeInformationSchema = exports.IDatabaseAuditLogUpdatesSchema = void 0;
-const admin = __importStar(require("firebase-admin"));
+exports.IDatabaseDeleteItemSchema = exports.IDatabaseGetInformationSchema = exports.IDatabasePageCursorSchema = exports.IDatabaseQueryFieldsSchema = exports.IDatabaseOrderBySchema = exports.IDatabaseGetItemSchema = exports.WhereFilterOpSchema = exports.OrderByDirectionSchema = exports.IDatabaseUpdatesSchema = exports.IDatabaseRecordAndRefSchema = exports.IDatabasePropertyChangeInformationSchema = exports.IDatabaseChangeInformationSchema = exports.IDatabaseAuditLogUpdatesSchema = void 0;
 const zod_1 = require("zod");
-const firestore_1 = require("firebase-admin/firestore");
+const application_settings_1 = require("../../../_settings/application-settings");
 const application_audit_log_models_1 = require("../audit-log/application-audit-log-models");
+// The lazily loaded module: undefined until a check first tries to load it, then the module, or
+// null when firebase-admin isn't installed (remembered for the life of the process).
+let firestoreModule;
+// Whether a failed load means firebase-admin itself isn't installed, as opposed to a broken install
+// (a dependency missing inside an installed copy), which should surface. Node names the module it
+// couldn't find on the message's first line; Yarn PnP names it in `data.dependencyName`.
+const NODE_NOT_FOUND = /^Cannot find module 'firebase-admin(\/[^']*)?'/;
+const isFirebaseAdminMissing = (error) => {
+    if (!(error instanceof Error) || !('code' in error) || error.code !== 'MODULE_NOT_FOUND') {
+        return false;
+    }
+    if ('data' in error && typeof error.data === 'object' && error.data !== null && 'dependencyName' in error.data) {
+        return error.data.dependencyName === 'firebase-admin';
+    }
+    return NODE_NOT_FOUND.test(error.message);
+};
+const tryLoadFirestore = () => {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- loaded on first use, see above
+        return require('firebase-admin/firestore');
+    }
+    catch (error) {
+        if (!isFirebaseAdminMissing(error)) {
+            throw error;
+        }
+        return null;
+    }
+};
+const loadFirestore = () => {
+    if (firestoreModule === undefined) {
+        firestoreModule = tryLoadFirestore();
+    }
+    return firestoreModule;
+};
+const isFirestoreInstance = (className) => (arg) => {
+    const firestore = loadFirestore();
+    return firestore !== null && arg instanceof firestore[className];
+};
+//#endregion Firestore classes
 //#region Backend Data Models
 //#region Audit Log Information
 /**
@@ -56,7 +61,7 @@ exports.IDatabaseChangeInformationSchema = zod_1.z.object({
     alai: zod_1.z.array(application_audit_log_models_1.AdditionalApplicationAuditLogIdsSchema), // the additional application audit log ids
     auditLogSubType: application_audit_log_models_1.ApplicationAuditLogSubTypeSchema, // the audit log sub type
     item: zod_1.z.unknown(), // the item to add to the database
-    itemDocRef: zod_1.z.custom(arg => arg instanceof firestore_1.DocumentReference), // the item document reference (where to add the item to the database)
+    itemDocRef: zod_1.z.custom(isFirestoreInstance('DocumentReference')), // the item document reference (where to add the item to the database)
 });
 /**
  * This contains the information that is needed to pass a change to the generic database functions.
@@ -67,14 +72,14 @@ exports.IDatabasePropertyChangeInformationSchema = zod_1.z.object({
     alai: zod_1.z.array(application_audit_log_models_1.AdditionalApplicationAuditLogIdsSchema), // the additional application audit log ids
     auditLogSubType: application_audit_log_models_1.ApplicationAuditLogSubTypeSchema, // the audit log sub type
     partialObjectUpdate: zod_1.z.any(), // the partial object to update
-    itemDocRef: zod_1.z.custom(arg => arg instanceof firestore_1.DocumentReference), // the item document reference (where to add the item to the database)
+    itemDocRef: zod_1.z.custom(isFirestoreInstance('DocumentReference')), // the item document reference (where to add the item to the database)
 });
 /**
  * This contains the information for a record and its reference
  */
 exports.IDatabaseRecordAndRefSchema = zod_1.z.object({
     record: zod_1.z.unknown(), // the record to update
-    recordDocRef: zod_1.z.custom(arg => arg instanceof firestore_1.DocumentReference), // the record document reference
+    recordDocRef: zod_1.z.custom(isFirestoreInstance('DocumentReference')), // the record document reference
 });
 /**
  * This contains the information records and audit logs for database changes
@@ -93,40 +98,53 @@ exports.WhereFilterOpSchema = zod_1.z.enum(['<', '<=', '==', '!=', '>=', '>', 'a
  * This contains the information to get a single item from the database.
  */
 exports.IDatabaseGetItemSchema = exports.IDatabaseAuditLogUpdatesSchema.extend({
-    itemDocRef: zod_1.z.custom(arg => arg instanceof firestore_1.DocumentReference), // the document reference to get the item from
+    itemDocRef: zod_1.z.custom(isFirestoreInstance('DocumentReference')), // the document reference to get the item from
     throwErrorOnNotFound: zod_1.z.boolean(), // if true, then throw an error if the item is not found.
 });
 /**
  * This contains the information that is needed to get information from the database.
  */
 exports.IDatabaseOrderBySchema = zod_1.z.object({
-    fieldPath: zod_1.z.union([zod_1.z.string(), zod_1.z.instanceof(admin.firestore.FieldPath)]), // the field to order by
+    fieldPath: zod_1.z.union([zod_1.z.string(), zod_1.z.custom(isFirestoreInstance('FieldPath'))]), // the field to order by
     direction: exports.OrderByDirectionSchema, // the direction to order by
 });
 /**
  * This contains the query information for the database if it is required
  */
 exports.IDatabaseQueryFieldsSchema = zod_1.z.object({
-    fieldPath: zod_1.z.union([zod_1.z.string(), zod_1.z.instanceof(admin.firestore.FieldPath)]),
+    fieldPath: zod_1.z.union([zod_1.z.string(), zod_1.z.custom(isFirestoreInstance('FieldPath'))]),
     opStr: exports.WhereFilterOpSchema,
     value: zod_1.z.any(),
 });
+/**
+ * A page cursor: an opaque token that getItemsFromDatabase returns as a page's nextCursor. Pass it
+ * back unchanged, with the same filters and orderBy, for the next page. It is a plain string of
+ * URL-safe characters, about 4/3 the size of the last item's ordered values as tagged JSON plus the
+ * list's field paths, and inside it those values keep their Firestore types. A small cursor fits
+ * a URL or JSON body; a large one may not (a default express.json() body takes about 100 KB, a URL
+ * or header about 16 KiB), so size the transport for the ordered fields in use.
+ *
+ * Opaque is not secret: the token is encoded, not encrypted. It holds the last item's value for
+ * every field the list is ordered by (its orderBy and every inequality filter's field), and those
+ * fields' names. Only hand a cursor to someone who may see those values for that item.
+ */
+exports.IDatabasePageCursorSchema = zod_1.z.string().min(1).max(application_settings_1.ApplicationSettings.SystemValues.MaxPageCursorLength);
 /**
  * This contains the information that is needed to get multiple items from the database.
  */
 exports.IDatabaseGetInformationSchema = exports.IDatabaseAuditLogUpdatesSchema.extend({
-    itemColRef: zod_1.z.custom(arg => arg instanceof firestore_1.CollectionReference), // the collection reference to get the items from
-    lastId: zod_1.z.string(), // the last id to get the next set of items.
+    itemColRef: zod_1.z.custom(isFirestoreInstance('CollectionReference')), // the collection reference to get the items from
+    cursor: exports.IDatabasePageCursorSchema.optional(), // where the page starts: the previous page's nextCursor; omitted for the first page
     orderBy: exports.IDatabaseOrderBySchema.optional(), // how to order the items
     queryFields: zod_1.z.array(exports.IDatabaseQueryFieldsSchema), // the fields to query
     isMaxSizeDocumentSet: zod_1.z.boolean().optional(), // if true, then the max size document the max number of docs to return
-});
+}).strict(); // strict, so input still carrying the old lastId fails rather than having it dropped
 //#endregion Database Get Information
 //#region Database Delete Information
 /**
  * This contains the information to delete a single item from the database.
  */
 exports.IDatabaseDeleteItemSchema = exports.IDatabaseAuditLogUpdatesSchema.extend({
-    itemDocRef: zod_1.z.custom(arg => arg instanceof firestore_1.DocumentReference), // the document reference to get the item to delete
+    itemDocRef: zod_1.z.custom(isFirestoreInstance('DocumentReference')), // the document reference to get the item to delete
     throwErrorOnNotFound: zod_1.z.boolean(), // if true, then throw an error if the item is not found.
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@degenerate/generic",
-  "version": "0.7.1",
+  "version": "0.9.1",
   "description": "This contains the generic information needed for the ShareData Adaptive Framework Ecosystem (SAFE) network",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,6 +16,7 @@
   "scripts": {
     "build": "rm -rf dist/* && tsc -p tsconfig.pkg.json",
     "compile": "rm -rf dist/* && tsc -p tsconfig.pkg.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "test": "jest --forceExit --detectOpenHandles --verbose --silent=false --env node",
     "test:coverage": "jest --forceExit --coverage --detectOpenHandles --verbose --silent=false --env node ",
     "test:clearCache": "jest --clearCache"
@@ -40,11 +41,10 @@
   "dependencies": {
     "@noble/ed25519": "3.1.0",
     "bip39": "^3.1.0",
-    "firebase-admin": "^13.9.0",
     "jsonwebtoken": "^9.0.3",
-    "zod": "^4.4.3"
+    "zod": "^4.6.6"
   },
-  "gitHead": "5e9a8b3f1d17f6913ccac216ca1a64ad30c30ee5",
+  "gitHead": "ebb2ab0634ac9c4da50e584d11153625e2cc3999",
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/eslint__js": "^8.42.3",
@@ -55,6 +55,7 @@
     "eslint": "^10.3.0",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
+    "firebase-admin": "^14.5.0",
     "jest": "^30.4.2",
     "jest-environment-jsdom": "^30.4.1",
     "ts-jest": "^29.4.9",
@@ -62,6 +63,14 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.3"
   },
+  "peerDependencies": {
+    "firebase-admin": "^13.9.0 || ^14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "firebase-admin": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22"
   }