@dereekb/firebase 12.5.10 → 12.6.1

package/src/lib/model/storagefile/storagefile.d.ts

@@ -1,13 +1,56 @@
-import { type Maybe } from '@dereekb/util';
+import { type NeedsSyncBoolean, type Maybe } from '@dereekb/util';
 import { type GrantedReadRole, type GrantedUpdateRole } from '@dereekb/model';
-import { AbstractFirestoreDocument, type CollectionReference, type FirestoreCollection, type FirestoreContext, type FirebaseAuthUserId, type FirebaseAuthOwnershipKey, type StoragePath, type StorageSignedDownloadUrl, type StorageDownloadUrl } from '../../common';
-import { type StorageFileId, type StorageFileMetadata, type StorageFilePurpose } from './storagefile.id';
+import { AbstractFirestoreDocument, type CollectionReference, type FirestoreCollection, type FirestoreContext, type FirebaseAuthUserId, type FirebaseAuthOwnershipKey, type StoragePath, type StorageSignedDownloadUrl, type StorageDownloadUrl, type SavedToFirestoreIfTrue, type OneWayFlatFirestoreModelKey, type FirestoreCollectionModelKey } from '../../common';
+import { type StorageFileGroupId, type StorageFileGroupRelatedStorageFilePurpose, type StorageFileId, type StorageFileMetadata, type StorageFilePurpose } from './storagefile.id';
 import { type NotificationKey } from '../notification';
 export declare abstract class StorageFileFirestoreCollections {
     abstract readonly storageFileCollection: StorageFileFirestoreCollection;
+    abstract readonly storageFileGroupCollection: StorageFileGroupFirestoreCollection;
+}
+export type StorageFileTypes = typeof storageFileIdentity | typeof storageFileGroupIdentity;
+/**
+ * StorageFile-related model that is initialized asynchronously at a later time.
+ *
+ * Examples: StorageFileGroup
+ */
+export interface InitializedStorageFileModel {
+    /**
+     * True if this model needs to be sync'd/initialized with the original model.
+     *
+     * Is set false if/when "fi" is set true.
+     */
+    s?: Maybe<NeedsSyncBoolean>;
+    /**
+     * True if this model has been flagged invalid.
+     *
+     * This is for cases where the model cannot be properly initiialized.
+     *
+     * Typically this results in this model and related data being deleted.
+     */
+    fi?: Maybe<SavedToFirestoreIfTrue>;
 }
-export type StorageFileTypes = typeof storageFileIdentity;
 export declare const storageFileIdentity: import("../../common").RootFirestoreModelIdentity<"storageFile", "sf">;
+/**
+ * The key for a StorageFile that is generated/related to a StorageFileGroup.
+ *
+ * For example, a StorageFile id for the Zip file generated by a StorageFileGroup with id "123" and the zip purpose "sfg_zip" would be "sfg_zip_sf123".
+ */
+export type StorageFileGroupCreatedStorageFileKey<P extends StorageFileGroupRelatedStorageFilePurpose> = FirestoreCollectionModelKey<typeof storageFileIdentity, `${P}_${OneWayFlatFirestoreModelKey}`>;
+/**
+ * Creates a StorageFileGroupCreatedStorageFileKey from the input StorageFileGroupId and purpose.
+ */
+export declare function storageFileGroupCreatedStorageFileKey<P extends StorageFileGroupRelatedStorageFilePurpose>(purpose: P, storageFileGroupId: StorageFileGroupId): StorageFileGroupCreatedStorageFileKey<P>;
+/**
+ * Creates a StorageFileGroupCreatedStorageFileKey from the input StorageFileGroupId and pre-configured purpose.
+ */
+export type StorageFileGroupCreateStorageFileKeyFactory<P extends StorageFileGroupRelatedStorageFilePurpose> = (storageFileGroupId: StorageFileGroupId) => StorageFileGroupCreatedStorageFileKey<P>;
+/**
+ * Creates a factory function for generating StorageFileGroupCreatedStorageFileKey values using the input purpose.
+ *
+ * @param purpose The purpose of the StorageFileGroupCreatedStorageFileKey.
+ * @returns A factory function that takes a StorageFileGroupId and returns a StorageFileGroupCreatedStorageFileKey.
+ */
+export declare function storageFileGroupCreateStorageFileKeyFactory<P extends StorageFileGroupRelatedStorageFilePurpose>(purpose: P): StorageFileGroupCreateStorageFileKeyFactory<P>;
 /**
  * This key is used in the CustomStorageMetadata of a Firebase Storage file that is associated with a StorageFile to link the file to the StorageFile.
  */
@@ -36,7 +79,14 @@ export declare enum StorageFileCreationType {
     /**
      * The StorageFile was initialized from an uploaded file.
      */
-    INIT_FROM_UPLOAD = 2
+    INIT_FROM_UPLOAD = 2,
+    /**
+     * This StorageFile was created by/for a StorageFileGroup.
+     *
+     * When creating a StorageFile via createStorageFileDocumentPairFactory(), this flag changes the behavior to use a parent
+     * StorageFileGroup to derive the created StorageFile's identifier.
+     */
+    FOR_STORAGE_FILE_GROUP = 3
 }
 /**
  * The current file state.
@@ -135,13 +185,19 @@ export type StorageFilePublicDownloadUrl = StorageDownloadUrl;
  */
 export type StorageFileSignedDownloadUrl = StorageSignedDownloadUrl;
 /**
- * A global storage file in the system.
+ * A download URL for a StorageFile.
+ *
+ * This can be a public download URL or a signed download URL.
+ */
+export type StorageFileDownloadUrl = StorageFilePublicDownloadUrl | StorageFileSignedDownloadUrl;
+/**
+ * A StorageFile in the system, which references a file in Google Cloud Storage.
  *
  * Contains file metadata and ownership information, along with other arbitrary metadata.
  */
 export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata> extends StoragePath {
     /**
-     * Created at date
+     * Created at date.
      */
     cat: Date;
     /**
@@ -206,6 +262,23 @@ export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata
      * Is the main trigger for determining a StorageFile should be deleted.
      */
     sdat?: Maybe<Date>;
+    /**
+     * StorageFileGroup id(s) that this StorageFile should be associated with.
+     *
+     * These StorageFileGroup do not need to exist, and will be created when synchronization occurs.
+     *
+     * These groups by design should typically be pre-determined at the time the StorageFile is created and remain unchanged; timely removal of data from groups is not part of the design spec.
+     *
+     * When a StorageFile is updated to remove groups, the removal is eventually propogated to the StorageFileGroup(s) that it was associated with,
+     * but there is no gurantee about timeliness when this will happen. StorageFiles, when deleted, are removed from StorageFileGroups immediately, which are flagged for another regeneration automatically.
+     *
+     * In cases where you need to have the StorageFileGroup be updated promptly, you should manually handle those cases.
+     */
+    g: StorageFileGroupId[];
+    /**
+     * If true, this file should be re-synced with each StorageFileGroup that it references.
+     */
+    gs?: Maybe<NeedsSyncBoolean>;
 }
 /**
  * Granted roles for creating a download link to the StorageFile's file.
@@ -213,7 +286,7 @@ export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata
  * The admin_download role allows specifying additional parameters and longer expiration times.
  */
 export type StorageFileDownloadRole = 'download' | 'admin_download';
-export type StorageFileRoles = StorageFileDownloadRole | 'process' | GrantedUpdateRole | GrantedReadRole;
+export type StorageFileRoles = StorageFileDownloadRole | 'forceSyncWithGroups' | 'syncWithGroups' | 'process' | GrantedUpdateRole | GrantedReadRole;
 export declare class StorageFileDocument extends AbstractFirestoreDocument<StorageFile, StorageFileDocument, typeof storageFileIdentity> {
     get modelIdentity(): import("../../common").RootFirestoreModelIdentity<"storageFile", "sf">;
 }
@@ -221,3 +294,75 @@ export declare const storageFileConverter: import("../../common").SnapshotConver
 export declare function storageFileCollectionReference(context: FirestoreContext): CollectionReference<StorageFile>;
 export type StorageFileFirestoreCollection = FirestoreCollection<StorageFile, StorageFileDocument>;
 export declare function storageFileFirestoreCollection(firestoreContext: FirestoreContext): StorageFileFirestoreCollection;
+export declare const storageFileGroupIdentity: import("../../common").RootFirestoreModelIdentity<"storageFileGroup", "sfg">;
+/**
+ * Current embedded state
+ */
+export interface StorageFileGroupEmbeddedFile {
+    /**
+     * StorageFile id
+     */
+    s: StorageFileId;
+    /**
+     * The time number it was added to the group.
+     */
+    sat: Date;
+    /**
+     * The first time the StorageFile's file was added to the zip, if applicable.
+     */
+    zat?: Maybe<Date>;
+}
+export declare const storageFileGroupEmbeddedFile: import("../../common").FirestoreSubObjectFieldMapFunctionsConfig<StorageFileGroupEmbeddedFile, Partial<import("@dereekb/util").ReplaceType<StorageFileGroupEmbeddedFile, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * A group of StorageFiles.
+ *
+ * Contains file metadata and ownership information, along with other arbitrary metadata.
+ */
+export interface StorageFileGroup extends InitializedStorageFileModel {
+    /**
+     * List of embedded files in this group currently.
+     */
+    f: StorageFileGroupEmbeddedFile[];
+    /**
+     * Created at date.
+     */
+    cat: Date;
+    /**
+     * Ownership key, if applicable.
+     */
+    o?: Maybe<FirebaseAuthOwnershipKey>;
+    /**
+     * True if a zip file should be generated for this group.
+     *
+     * This should remain true while a zip file
+     */
+    z?: Maybe<SavedToFirestoreIfTrue>;
+    /**
+     * StorageFile that contains the zip file for this group.
+     */
+    zsf?: Maybe<StorageFileId>;
+    /**
+     * The last date the zip file was regenerated for this group.
+     */
+    zat?: Maybe<Date>;
+    /**
+     * True if this StorageFileGroup should flag regeneration of output StorageFiles/content.
+     */
+    re?: Maybe<SavedToFirestoreIfTrue>;
+    /**
+     * True if this StorageFileGroup should clean up file references.
+     *
+     * This cleanup process will occur during the next regeneration.
+     */
+    c?: Maybe<SavedToFirestoreIfTrue>;
+}
+export type StorageFileGroupContentFlagsData = Pick<StorageFileGroup, 'z'>;
+export type StorageFileGroupRoles = 'regenerate' | GrantedReadRole;
+export declare class StorageFileGroupDocument extends AbstractFirestoreDocument<StorageFileGroup, StorageFileGroupDocument, typeof storageFileGroupIdentity> {
+    get modelIdentity(): import("../../common").RootFirestoreModelIdentity<"storageFileGroup", "sfg">;
+    get storageFileGroupRelatedModelKey(): string;
+}
+export declare const storageFileGroupConverter: import("../../common").SnapshotConverterFunctions<StorageFileGroup, Partial<import("@dereekb/util").ReplaceType<StorageFileGroup, import("@dereekb/util").MaybeMap<object>, any>>>;
+export declare function storageFileGroupCollectionReference(context: FirestoreContext): CollectionReference<StorageFileGroup>;
+export type StorageFileGroupFirestoreCollection = FirestoreCollection<StorageFileGroup, StorageFileGroupDocument>;
+export declare function storageFileGroupFirestoreCollection(firestoreContext: FirestoreContext): StorageFileGroupFirestoreCollection;

package/src/lib/model/storagefile/storagefile.group.d.ts

@@ -0,0 +1,9 @@
+import { type SlashPathFile, type SlashPathFolder, type SlashPath, type Maybe } from '@dereekb/util';
+import { type StorageFileGroupId } from './storagefile.id';
+/**
+ * All StorageFileGroup generated files are stored under this root folder.
+ */
+export declare const STORAGE_FILE_GROUP_ROOT_FOLDER_PATH: SlashPathFolder;
+export declare function storageFileGroupFolderPath(storageFileGroupId: StorageFileGroupId, ...subPath: Maybe<SlashPath>[]): SlashPathFolder;
+export declare const STORAGE_FILE_GROUP_ZIP_FILE_PATH: SlashPathFile;
+export declare function storageFileGroupZipFileStoragePath(storageFileGroupId: StorageFileGroupId): SlashPath;

package/src/lib/model/storagefile/storagefile.group.processing.d.ts

@@ -0,0 +1,26 @@
+import { type SlashPathTypedFile } from '@dereekb/util';
+import { type StorageFileGroupId, type StorageFilePurpose } from './storagefile.id';
+import { type StorageFileProcessingSubtask, type StorageFileProcessingSubtaskMetadata } from './storagefile.task';
+import { type StorageFileGroupCreatedStorageFileKey } from './storagefile';
+/**
+ * StorageFilePurpose for a StorageFileGroup's generated zip file.
+ */
+export declare const STORAGE_FILE_GROUP_ZIP_STORAGE_FILE_PURPOSE: StorageFilePurpose;
+/**
+ * The predictable StorageFileKey for the StorageFileGroup's generated zip file StorageFile.
+ */
+export type StorageFileGroupZipStorageFileKey = StorageFileGroupCreatedStorageFileKey<typeof STORAGE_FILE_GROUP_ZIP_STORAGE_FILE_PURPOSE>;
+/**
+ * Creates a StorageFileGroupZipStorageFileKey from the input StorageFileGroupId.
+ */
+export declare const storageFileGroupZipStorageFileKey: import("./storagefile").StorageFileGroupCreateStorageFileKeyFactory<string>;
+/**
+ * Metadata for the StorageFileGroupZipStorageFile.
+ */
+export interface StorageFileGroupZipStorageFileMetadata {
+    readonly sfg: StorageFileGroupId;
+}
+export declare const STORAGE_FILE_GROUP_ZIP_STORAGE_FILE_PURPOSE_CREATE_ZIP_SUBTASK: StorageFileProcessingSubtask;
+export type StorageFileGroupZipStorageFileProcessingSubtask = typeof STORAGE_FILE_GROUP_ZIP_STORAGE_FILE_PURPOSE_CREATE_ZIP_SUBTASK;
+export type StorageFileGroupZipStorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata;
+export declare const STORAGE_FILE_GROUP_ZIP_INFO_JSON_FILE_NAME: SlashPathTypedFile;

package/src/lib/model/storagefile/storagefile.id.d.ts

@@ -1,4 +1,4 @@
-import { type FirestoreModelId, type FirestoreModelKey } from '../../common';
+import { type FlatFirestoreModelKey, inferKeyFromTwoWayFlatFirestoreModelKey, twoWayFlatFirestoreModelKey, type FirestoreModelId, type FirestoreModelKey } from '../../common';
 export type StorageFileId = FirestoreModelId;
 export type StorageFileKey = FirestoreModelKey;
 /**
@@ -12,9 +12,30 @@ export type StorageFileKey = FirestoreModelKey;
  * Can be used for querying.
  */
 export type StorageFilePurpose = string;
+/**
+ * A StorageFilePurpose that is related to a StorageFileGroup.
+ *
+ * Should only have the characters characters "a-z", "0-9", and/or "_", as it is used as part of a FirestoreModelId for StorageFileGroupCreatedStorageFileKey.
+ */
+export type StorageFileGroupRelatedStorageFilePurpose = StorageFilePurpose;
 /**
  * Arbitrary metadata to attach to the storage file.
  *
  * Is serialized directly to/from Firestore, so be mindful of what is stored.
  */
 export type StorageFileMetadata = Readonly<Record<string, any>>;
+/**
+ * The StorgaeFileGroupId is a two way flat firestore model key of the object that it represents.
+ *
+ * This identifier is used by StorageFile's to group files together based around some other model or common identifier.
+ */
+export type StorageFileGroupId = FlatFirestoreModelKey;
+export type StorageFileGroupKey = FirestoreModelKey;
+/**
+ * Creates a StorgaeFileGroupId from the input FirestoreModelKey.
+ *
+ * @param modelKey
+ * @returns
+ */
+export declare const storageFileGroupIdForModel: typeof twoWayFlatFirestoreModelKey;
+export declare const inferStorageFileGroupRelatedModelKey: typeof inferKeyFromTwoWayFlatFirestoreModelKey;

package/src/lib/model/storagefile/storagefile.query.d.ts

@@ -15,3 +15,25 @@ export interface StorageFilePurposeAndUserQueryInput {
     readonly user: FirebaseAuthUserId;
 }
 export declare function storageFilePurposeAndUserQuery(input: StorageFilePurposeAndUserQueryInput): FirestoreQueryConstraint[];
+export declare function storageFileFlaggedForSyncWithGroupsQuery(): FirestoreQueryConstraint[];
+/**
+ * Query for storageFileGroups that are flagged for initialization.
+ *
+ * @param now
+ * @returns
+ */
+export declare function storageFileGroupsFlaggedForNeedsInitializationQuery(): FirestoreQueryConstraint[];
+/**
+ * Query for storageFileGroups that are flagged for content regeneration.
+ *
+ * @param now
+ * @returns
+ */
+export declare function storageFileGroupsFlaggedForContentRegenerationQuery(): FirestoreQueryConstraint[];
+/**
+ * Query for storageFileGroups that are flagged as invalid.
+ *
+ * @param now
+ * @returns
+ */
+export declare function storageFileGroupsFlaggedInvalidQuery(): FirestoreQueryConstraint[];

package/src/lib/model/storagefile/storagefile.util.d.ts

@@ -0,0 +1,55 @@
+import { type Maybe } from '@dereekb/util';
+import { type FirestoreModelKey, type FirestoreDocumentAccessor } from '../../common';
+import { type StorageFileGroupDocument, type StorageFileGroup, type StorageFileGroupEmbeddedFile } from './storagefile';
+import { type StorageFileId } from './storagefile.id';
+export interface StorageFileGroupDocumentReferencePair {
+    /**
+     * StorageFileGroupDocument to update.
+     *
+     * If not provided, please provide the storageFileGroupRelatedModelKey. If neither value is provided, an error will be thrown.
+     */
+    readonly storageFileGroupDocument?: Maybe<StorageFileGroupDocument>;
+    /**
+     * Key of the model the storage file group is expected to be associated with. Used if StorageFileGroupDocument is not provided already.
+     */
+    readonly storageFileGroupRelatedModelKey?: Maybe<FirestoreModelKey>;
+}
+export declare function loadStorageFileGroupDocumentForReferencePair(input: StorageFileGroupDocumentReferencePair, accessor: FirestoreDocumentAccessor<StorageFileGroup, StorageFileGroupDocument>): StorageFileGroupDocument;
+export interface CalculateStorageFileGroupEmbeddedFileUpdateInput {
+    readonly storageFileGroup: Pick<StorageFileGroup, 'f' | 're' | 'z' | 'zat'>;
+    readonly insert?: Maybe<(Pick<StorageFileGroupEmbeddedFile, 's'> & Partial<Omit<StorageFileGroupEmbeddedFile, 's'>>)[]>;
+    readonly remove?: Maybe<StorageFileId[]>;
+    /**
+     * Whether or not to allow recalculating the regenerate flag even if the current "re" value is true.
+     *
+     * Regenerate will always be true if any files are removed.
+     *
+     * Defaults to false.
+     */
+    readonly allowRecalculateRegenerateFlag?: Maybe<boolean>;
+}
+export declare function calculateStorageFileGroupEmbeddedFileUpdate(input: CalculateStorageFileGroupEmbeddedFileUpdateInput): Pick<StorageFileGroup, 'f' | 're'>;
+export interface CalculateStorageFileGroupRegenerationInput {
+    readonly storageFileGroup: Pick<StorageFileGroup, 'f' | 'z' | 'zat'>;
+    /**
+     * If true, will force regenerating applicable derived files, even if all content is up to date.
+     */
+    readonly force?: Maybe<boolean>;
+}
+export interface CalculateStorageFileGroupRegenerationResult {
+    /**
+     * Whether or not the zip file needs to be regenerated.
+     */
+    readonly regenerateZip?: Maybe<boolean>;
+    /**
+     * Whether or not any derived StorageFile needs to be regenerated.
+     */
+    readonly flagRegenerate: boolean;
+}
+/**
+ * Calculates the regeneration flags for a StorageFileGroup.
+ *
+ * @param input CalculateStorageFileGroupRegenerationInput
+ * @returns CalculateStorageFileGroupRegenerationResult
+ */
+export declare function calculateStorageFileGroupRegeneration(input: CalculateStorageFileGroupRegenerationInput): CalculateStorageFileGroupRegenerationResult;

package/test/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [12.6.1](https://github.com/dereekb/dbx-components/compare/v12.6.0-dev...v12.6.1) (2025-12-07)
+
+
+
+# [12.6.0](https://github.com/dereekb/dbx-components/compare/v12.5.10-dev...v12.6.0) (2025-12-02)
+
+
+
 ## [12.5.10](https://github.com/dereekb/dbx-components/compare/v12.5.9-dev...v12.5.10) (2025-11-21)
 
 

package/test/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "12.5.10",
+  "version": "12.6.1",
   "type": "commonjs",
   "peerDependencies": {
     "@dereekb/util": "*",