@dereekb/firebase 13.42.0 → 13.43.0

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

@@ -0,0 +1,348 @@
+import { type ContentTypeMimeType, type Maybe } from '@dereekb/util';
+import { type FirebaseAuthOwnershipKey, type FirebaseAuthUserId } from '../../common/auth/auth';
+import { type FirestoreModelKey } from '../../common/firestore/collection/collection';
+import { type StorageFileGroupId } from '../storagefile/storagefile.id';
+import { type FormSpace, type FormSpaceData, type FormSpaceFile } from './formspace';
+import { type FormSpaceFileSlot, type FormSpaceKey, type FormSpaceType } from './formspace.id';
+import { type FormSpaceFileSlotConfig, type FormSpaceTypeConfig } from './formspace.type';
+/**
+ * @module formspace.util
+ *
+ * Pure helpers shared by the client and the server: the write templates for each lifecycle transition, and
+ * the upload predicate.
+ *
+ * {@link assertFormSpaceUploadAllowed} in particular is deliberately PURE and lives here rather than in
+ * `firebase-server`: the client pre-checks a file with it before asking for a signed URL, and the server's
+ * upload initializer enforces the very same function afterwards. One rule, two callers — a client-side copy
+ * that drifted would show the user an accept for a file the server then silently discards.
+ *
+ * A file's NAME is not one of the rules. It used to be: two files of one name in a slot resolved to the
+ * same destination object, so the second silently overwrote the first. The destination is now keyed by the
+ * space's `fi` index instead, so two files of one name are two objects, and the name is free to be
+ * whatever the user uploaded.
+ */
+/**
+ * Returns the {@link StorageFileGroupId} that owns every file uploaded into a FormSpace.
+ *
+ * The group is keyed by the FormSpace's own model key, so the existing sync machinery creates it on the
+ * first upload and the existing zip / cleanup machinery applies with no FormSpace-specific code.
+ *
+ * @param formSpaceKey - The FormSpace's model key.
+ * @returns The group id.
+ *
+ * @example
+ * ```ts
+ * const groupId = formSpaceStorageFileGroupId('fsp/abc123'); // 'fsp_abc123'
+ * ```
+ */
+export declare function formSpaceStorageFileGroupId(formSpaceKey: FormSpaceKey): StorageFileGroupId;
+/**
+ * Input for {@link resolveFormSpaceExpiresAt}.
+ */
+export interface ResolveFormSpaceExpiresAtInput {
+    readonly config: FormSpaceTypeConfig;
+    /**
+     * The instant the space is being created at. Defaults to now.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Returns the instant a newly created FormSpace of the given type expires at, or null when its type never
+ * expires.
+ *
+ * Null is meaningful rather than merely absent: it is what leaves `eat` unwritten, and an unwritten `eat`
+ * is what excludes the space from the sweep's inequality query.
+ *
+ * @param input - The type config and creation instant.
+ * @returns The expiration instant, or null when the type does not expire.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function resolveFormSpaceExpiresAt(input: ResolveFormSpaceExpiresAtInput): Maybe<Date>;
+/**
+ * Input for {@link formSpaceTemplate}.
+ */
+export interface FormSpaceTemplateInput<T extends FormSpaceData = FormSpaceData> {
+    readonly formSpaceType: FormSpaceType;
+    readonly uid: FirebaseAuthUserId;
+    readonly ownerKey?: Maybe<FirebaseAuthOwnershipKey>;
+    readonly targetModelKey?: Maybe<FirestoreModelKey>;
+    readonly displayName?: Maybe<string>;
+    readonly data?: Maybe<T>;
+    readonly expiresAt?: Maybe<Date>;
+    /**
+     * The creation instant. Defaults to now.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Builds the complete document template for a newly created FormSpace.
+ *
+ * @param input - The type, owner, and initial content of the space.
+ * @returns The FormSpace template.
+ *
+ * @example
+ * ```ts
+ * const template = formSpaceTemplate({ formSpaceType: 'demo_example', uid: 'user123' });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceTemplate<T extends FormSpaceData = FormSpaceData>(input: FormSpaceTemplateInput<T>): FormSpace<T>;
+/**
+ * Builds the update template that submits a FormSpace.
+ *
+ * Clearing `eat` is not tidiness: a submitted space that kept its expiration instant would still match the
+ * expiration sweep and be retired out from under the processing task.
+ *
+ * @param now - The submission instant. Defaults to now.
+ * @returns The update template.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function submitFormSpaceTemplate(now?: Maybe<Date>): Partial<FormSpace>;
+/**
+ * Builds the update template that expires a FormSpace.
+ *
+ * @param now - The expiration instant. Defaults to now.
+ * @returns The update template.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function expireFormSpaceTemplate(now?: Maybe<Date>): Partial<FormSpace>;
+/**
+ * Input for {@link isFormSpaceEditable}.
+ */
+export interface IsFormSpaceEditableInput {
+    readonly formSpace: Pick<FormSpace, 's' | 'sat' | 'eat'>;
+    /**
+     * The instant to judge against. Defaults to now.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Returns true when a FormSpace may still be edited or uploaded into.
+ *
+ * Checks the expiration instant as well as the state, so a space whose sweep has not run yet is already
+ * closed. The sweep is what RETIRES the document; it is not what makes it un-editable.
+ *
+ * @param input - The space and the instant to judge against.
+ * @returns True when the space is editable.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isFormSpaceEditable(input: IsFormSpaceEditableInput): boolean;
+/**
+ * Returns the slot config a type declares for the given slot, or null when it declares none.
+ *
+ * @param config - The type config.
+ * @param slot - The slot to look up.
+ * @returns The slot config, or null.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceFileSlotConfig(config: FormSpaceTypeConfig, slot: FormSpaceFileSlot): Maybe<FormSpaceFileSlotConfig>;
+/**
+ * Returns the human-readable name of a slot, falling back to the slot key itself.
+ *
+ * The key is a reasonable fallback rather than a placeholder: a slot is named `resume` or `cover` precisely
+ * because that is what it holds, so a type that declared no `name` still reads as something.
+ *
+ * @param config - The type config.
+ * @param slot - The slot to name.
+ * @returns The slot's name.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceFileSlotName(config: FormSpaceTypeConfig, slot: FormSpaceFileSlot): string;
+/**
+ * Returns how many files a slot may hold at once.
+ *
+ * @param slotConfig - The slot config, or null for an undeclared slot.
+ * @returns The slot's file capacity.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceSlotMaxFiles(slotConfig: Maybe<FormSpaceFileSlotConfig>): number;
+/**
+ * Returns how many files a slot must hold before the space may be submitted.
+ *
+ * `required` is the older, coarser spelling of the same idea, so it resolves to 1 when `minFiles` is absent.
+ *
+ * @param slotConfig - The slot config, or null for an undeclared slot.
+ * @returns The slot's minimum file count.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceSlotMinFiles(slotConfig: Maybe<FormSpaceFileSlotConfig>): number;
+/**
+ * Returns the files a FormSpace currently holds in one slot.
+ *
+ * @param formSpace - The space to read.
+ * @param slot - The slot to filter by.
+ * @returns The slot's files, in the order the space stores them.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceFilesInSlot(formSpace: Pick<FormSpace, 'f'>, slot: FormSpaceFileSlot): FormSpaceFile[];
+/**
+ * Every slot a type requires be filled before its spaces may be submitted.
+ *
+ * A CLIENT-side convenience for labelling a form's required slots. The submit gate itself uses
+ * {@link formSpaceSubmitBlockers}, which also understands `minFiles` and validation state.
+ *
+ * @param config - The type config.
+ * @returns The required slots.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function requiredFormSpaceFileSlots(config: FormSpaceTypeConfig): FormSpaceFileSlot[];
+/**
+ * Why {@link assertFormSpaceUploadAllowed} rejected an upload.
+ *
+ * A discriminated reason rather than a bare false: the caller turns it into an error code, and a client
+ * pre-check turns it into a message the user can act on.
+ */
+export type FormSpaceUploadRejectionReason = 'not_editable' | 'unknown_slot' | 'max_uploads_reached' | 'slot_full' | 'invalid_mime_type' | 'file_too_large';
+/**
+ * Result of {@link assertFormSpaceUploadAllowed}.
+ */
+export interface FormSpaceUploadAllowedResult {
+    readonly allowed: boolean;
+    readonly reason?: Maybe<FormSpaceUploadRejectionReason>;
+}
+/**
+ * Input for {@link assertFormSpaceUploadAllowed}.
+ */
+export interface AssertFormSpaceUploadAllowedInput {
+    readonly formSpace: Pick<FormSpace, 's' | 'sat' | 'eat' | 'uc' | 'f'>;
+    readonly config: FormSpaceTypeConfig;
+    readonly slot: FormSpaceFileSlot;
+    readonly mimeType: ContentTypeMimeType;
+    readonly sizeBytes: number;
+    /**
+     * The instant to judge editability against. Defaults to now.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Decides whether one file may be uploaded into one slot of one FormSpace.
+ *
+ * THE single upload rule. The client calls it to pre-check before requesting a signed URL, and the server's
+ * upload initializer calls it again — authoritatively, after loading the space — before creating any
+ * StorageFile. The client call is a courtesy; only the server call is a control.
+ *
+ * @param input - The space, its type config, and the candidate file.
+ * @returns Whether the upload is allowed, and why not when it is not.
+ *
+ * @example
+ * ```ts
+ * const result = assertFormSpaceUploadAllowed({ formSpace, config, slot: 'resume', mimeType: 'application/pdf', sizeBytes: 4096 });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function assertFormSpaceUploadAllowed(input: AssertFormSpaceUploadAllowedInput): FormSpaceUploadAllowedResult;
+/**
+ * Why a FormSpace cannot be submitted yet.
+ *
+ * Per-slot rather than a bare list of slot names, because "you have not uploaded a second document" and "the
+ * document you uploaded was rejected" want different words in front of the user.
+ */
+export interface FormSpaceSubmitBlocker {
+    readonly slot: FormSpaceFileSlot;
+    /**
+     * `missing_files` — the slot holds fewer than its `minFiles`.
+     * `invalid_file` — the slot holds a file validation judged INVALID.
+     * `pending_validation` — the slot holds a file whose validation has not concluded.
+     */
+    readonly reason: 'missing_files' | 'invalid_file' | 'pending_validation';
+    /**
+     * The offending files, for `invalid_file` and `pending_validation`.
+     */
+    readonly files?: Maybe<FormSpaceFile[]>;
+}
+/**
+ * Returns every reason a FormSpace may not be submitted yet, or an empty array when it may.
+ *
+ * Reads the space's own `f` array rather than querying its StorageFiles. That array is written in the
+ * accept transaction, so unlike a query it is correct immediately after an upload — and unlike a query it
+ * can be read inside the transaction that takes the submit lock.
+ *
+ * @param formSpace - The space to check.
+ * @param config - Its type config.
+ * @returns The blockers, empty when the space may be submitted.
+ *
+ * @example
+ * ```ts
+ * const blockers = formSpaceSubmitBlockers(formSpace, config);
+ *
+ * if (blockers.length > 0) {
+ *   throw formSpaceRequiredSlotMissingError(blockers.map((x) => x.slot));
+ * }
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceSubmitBlockers(formSpace: Pick<FormSpace, 'f'>, config: FormSpaceTypeConfig): FormSpaceSubmitBlocker[];
+/**
+ * What one slot of a FormSpace currently holds, and whether that satisfies the slot's own requirement.
+ *
+ * The per-slot view of {@link formSpaceSubmitBlockers}, for a UI that labels each slot individually rather
+ * than reporting one verdict for the whole space.
+ */
+export interface FormSpaceSlotStatus {
+    readonly slot: FormSpaceFileSlot;
+    /**
+     * The files the slot currently holds.
+     */
+    readonly files: FormSpaceFile[];
+    readonly minFiles: number;
+    readonly maxFiles: number;
+    /**
+     * Whether the space cannot be submitted while this slot is empty, i.e. {@link minFiles} is above zero.
+     */
+    readonly required: boolean;
+    /**
+     * Every reason this slot blocks submission. Empty when it does not.
+     */
+    readonly blockers: FormSpaceSubmitBlocker[];
+    /**
+     * Whether this slot blocks submission. An OPTIONAL EMPTY slot is satisfied — it is holding up nothing.
+     */
+    readonly satisfied: boolean;
+    /**
+     * Whether the slot is satisfied AND holds something.
+     *
+     * The distinction from {@link satisfied} is what an optional slot needs: an empty one blocks nothing, but
+     * marking it DONE claims the user dealt with it when they have not touched it. So this is the narrower
+     * predicate — "there is something here and it is fine" — and it is what a checkmark belongs next to.
+     */
+    readonly complete: boolean;
+}
+/**
+ * Input for {@link formSpaceSlotStatus}.
+ */
+export interface FormSpaceSlotStatusInput {
+    readonly formSpace: Pick<FormSpace, 'f'>;
+    readonly config: FormSpaceTypeConfig;
+    readonly slot: FormSpaceFileSlot;
+}
+/**
+ * Returns what one slot holds and whether that satisfies the slot's requirement.
+ *
+ * Derived from {@link formSpaceSubmitBlockers} rather than re-deriving the rule, so a slot a UI marks done is
+ * exactly a slot the server's submit gate would not object to.
+ *
+ * @param input - The space, its type config, and the slot to report on.
+ * @returns The slot's status.
+ *
+ * @example
+ * ```ts
+ * const status = formSpaceSlotStatus({ formSpace, config, slot: 'resume' });
+ * const showCheck = status.complete;
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceSlotStatus(input: FormSpaceSlotStatusInput): FormSpaceSlotStatus;

package/src/lib/model/formspace/index.d.ts

@@ -0,0 +1,13 @@
+export * from './formspace.access';
+export * from './formspace.action';
+export * from './formspace.api.error';
+export * from './formspace.api';
+export * from './formspace.id';
+export * from './formspace.permission';
+export * from './formspace.processing';
+export * from './formspace.query';
+export * from './formspace.task';
+export * from './formspace.type';
+export * from './formspace.upload';
+export * from './formspace.util';
+export * from './formspace';

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

@@ -1,5 +1,6 @@
 export * from './external';
 export * from './calendar';
+export * from './formspace';
 export * from './user';
 export * from './notification';
 export * from './oidcmodel';

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

@@ -2,6 +2,7 @@ import { type Type } from 'arktype';
 import { type TargetModelParams, type OnCallCreateModelResult, type FirestoreModelKey } from '../../common';
 import { type ModelFirebaseCrudFunction, type FirebaseFunctionTypeConfigMap, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap, type ModelFirebaseCreateFunction } from '../../client';
 import { type StorageFileSignedDownloadUrl, type StorageFileTypes } from './storagefile';
+import { type StorageFileUploadScope } from './storagefile.upload';
 import { type StorageFileKey, type StorageFileId, type StorageFilePurpose } from './storagefile.id';
 import { type StorageBucketId, type StorageMetadata, type StoragePath, type StorageSlashPath } from '../../common/storage';
 import { type ContentDispositionString, type ContentTypeMimeType, type Maybe, type Milliseconds, type SlashPath, type SlashPathFile, type UnixDateTimeMillisecondsNumber, type UnixDateTimeSecondsNumber } from '@dereekb/util';
@@ -26,6 +27,14 @@ export interface InitializeAllStorageFilesFromUploadsParams {
     readonly maxFilesToInitialize?: Maybe<number>;
     readonly folderPath?: Maybe<StorageSlashPath>;
     readonly overrideUploadsFolderPath?: Maybe<StorageSlashPath>;
+    /**
+     * Whether to expedite processing of each initialized file that ends up queued for it.
+     *
+     * The same option {@link InitializeStorageFileFromUploadParams} already offers for a single file. Without
+     * it a file initialized by this sweep waits for the next `processAllQueuedStorageFiles` pass, which is a
+     * whole scheduling tick of latency for a purpose whose processing the uploader is waiting on.
+     */
+    readonly expediteProcessing?: Maybe<boolean>;
 }
 export declare const initializeAllStorageFilesFromUploadsParamsType: Type<InitializeAllStorageFilesFromUploadsParams>;
 /**
@@ -343,7 +352,17 @@ export interface CreateStorageFileSignedUploadUrlParams {
      * when omitted.
      */
     readonly expiresInMs?: Maybe<Milliseconds>;
+    /**
+     * The model, and optionally the slot within it, this upload belongs to. Required when the resolved
+     * policy sets `requiresScopeInput: true` (e.g. a FormSpace upload, which is keyed by space and slot
+     * rather than by the uid alone).
+     */
+    readonly scope?: Maybe<StorageFileUploadScope>;
 }
+/**
+ * Arktype for a {@link StorageFileUploadScope}.
+ */
+export declare const storageFileUploadScopeType: Type<StorageFileUploadScope>;
 export declare const createStorageFileSignedUploadUrlParamsType: Type<CreateStorageFileSignedUploadUrlParams>;
 /**
  * Result of creating a signed upload URL.

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

@@ -1,11 +1,51 @@
-import { type Factory, type FactoryWithRequiredInput, type Maybe, type SlashPathDetails } from '@dereekb/util';
-import { type StoragePath } from '../../common/storage/storage';
+import { type ContentTypeMimeType, type Factory, type FactoryWithRequiredInput, type Maybe, type SlashPathDetails, type SlashPathFile } from '@dereekb/util';
+import { type StoragePath, type StorageSlashPath } from '../../common/storage/storage';
+import { type StorageFileDisplayName } from './storagefile.id';
 import { type StorageCustomMetadata } from '../../common/storage/types';
 import { type FirebaseStorageAccessorFile } from '../../common/storage/driver/accessor';
 /**
  * Input for a {@link StoredFileReader}, carrying the storage bucket and path of the file.
  */
 export type StoredFileReaderInput = StoragePath;
+/**
+ * Input for {@link storageFileDisplayFileName}.
+ */
+export interface StorageFileDisplayFileNameInput {
+    /**
+     * The StorageFile's own `n`, which is UNTYPED by contract (see {@link StorageFileDisplayName}).
+     */
+    readonly displayName?: Maybe<StorageFileDisplayName>;
+    /**
+     * The object's path — a StorageFile's `pathString`, or the `name` off its storage metadata.
+     */
+    readonly pathString?: Maybe<StorageSlashPath>;
+    /**
+     * The object's content type, used when the path names no extension.
+     */
+    readonly contentType?: Maybe<ContentTypeMimeType>;
+}
+/**
+ * Composes the name a stored file should be presented to a user under.
+ *
+ * THE one place that answers "what is this file called". A StorageFile's `n` is untyped by contract, so
+ * the extension always comes from the object's own path — which is why a purpose whose destination is not
+ * name-keyed (a FormSpace file lives at `.../{index}.{ext}`) still downloads and zips under the name its
+ * uploader gave it.
+ *
+ * Falls back to the path's own leaf when there is no display name, so a StorageFile that never had one
+ * behaves exactly as it did before.
+ *
+ * @param input - The display name, the object path, and the content type.
+ * @returns The composed file name, or null when the input names neither.
+ *
+ * @example
+ * ```ts
+ * storageFileDisplayFileName({ displayName: 'resume', pathString: '/fsp/f1/resume/0.pdf' }); // 'resume.pdf'
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function storageFileDisplayFileName(input: StorageFileDisplayFileNameInput): Maybe<SlashPathFile>;
 /**
  * Factory that creates a {@link StoredFileReader} from a {@link FirebaseStorageAccessorFile}.
  *

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

@@ -105,6 +105,28 @@ export type StorageFileInitializeFromUploadResultType = 'success' | 'no_determin
 export interface StorageFilePurposeUploadPolicyBuildPathInput {
     readonly uid: FirebaseAuthUserId;
     readonly filename?: Maybe<SlashPathFile>;
+    /**
+     * The model the upload is scoped to, for a purpose whose destination is not derivable from the uid alone.
+     *
+     * Required when the policy sets {@link StorageFilePurposeUploadPolicy.requiresScopeInput}.
+     */
+    readonly scope?: Maybe<StorageFileUploadScope>;
+}
+/**
+ * Names the specific model, and optionally the slot within it, that an upload belongs to.
+ *
+ * This is what lets ONE purpose serve many destinations: a FormSpace upload is `{ id: formSpaceId,
+ * subgroup: slot }` under a single `form_space` purpose, rather than a purpose per form type.
+ */
+export interface StorageFileUploadScope {
+    /**
+     * Id of the model the upload is scoped to.
+     */
+    readonly id: string;
+    /**
+     * Slot/subgroup within the scoped model, when the model has more than one.
+     */
+    readonly subgroup?: Maybe<string>;
 }
 /**
  * Per-purpose constraints for generating short-lived signed upload URLs.
@@ -128,4 +150,12 @@ export interface StorageFilePurposeUploadPolicy {
      * When false (e.g. avatar), the path is derived solely from the uid.
      */
     readonly requiresFilenameInput: boolean;
+    /**
+     * When true, the caller MUST provide a {@link StorageFileUploadScope} for `buildUploadPath`.
+     *
+     * Set by a purpose whose destination folder is keyed by a model rather than by the uid alone. The scope
+     * is only a PATH input — it is not itself authorization; the purpose's initializer is what loads the
+     * scoped model and decides whether this uploader may write into it.
+     */
+    readonly requiresScopeInput?: boolean;
 }

package/test/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.42.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.42.0",
-    "@dereekb/firebase": "13.42.0",
-    "@dereekb/model": "13.42.0",
-    "@dereekb/rxjs": "13.42.0",
-    "@dereekb/util": "13.42.0",
+    "@dereekb/date": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/util": "13.43.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",