@dereekb/firebase 13.41.0 → 13.43.0

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>;
 /**
@@ -51,13 +60,34 @@ export declare const initializeStorageFileFromUploadParamsType: Type<InitializeS
 /**
  * Parameters for triggering processing of a specific StorageFile.
  *
- * Supports various modes: immediate processing, retry checking, force restart,
- * and reprocessing already-successful files. Validated with {@link processStorageFileParamsType}.
+ * Which flag is required depends on the file's current processing state. A `FAILED` file
+ * restarts with no flag, while a `SUCCESS` file needs `processAgainIfSuccessful` (or
+ * `forceRestartProcessing`) — note that a file whose processor ran to completion is `SUCCESS`
+ * even when the outcome was a rejection, so re-validating a rejected file normally needs one of
+ * those flags. `ARCHIVED` and `DO_NOT_PROCESS` files cannot be processed at all.
+ *
+ * Validated with {@link processStorageFileParamsType}.
  */
 export interface ProcessStorageFileParams extends TargetModelParams {
+    /**
+     * Runs the first step of the processing task inline instead of waiting for the scheduled task runner.
+     */
     readonly runImmediately?: Maybe<boolean>;
+    /**
+     * Checks an in-flight `PROCESSING` task immediately, instead of waiting for it to age past the
+     * stuck-check throttle.
+     */
     readonly checkRetryProcessing?: Maybe<boolean>;
+    /**
+     * Abandons the file's existing processing task and begins a new one, clearing the completed
+     * checkpoints so the flow runs again from the start. For a `PROCESSING` file this is only applied
+     * once the retry check runs, so pair it with `checkRetryProcessing` to force a restart while the
+     * existing task is still within the stuck-check throttle.
+     */
     readonly forceRestartProcessing?: Maybe<boolean>;
+    /**
+     * Allows processing a file that has already finished processing and is in the `SUCCESS` state.
+     */
     readonly processAgainIfSuccessful?: Maybe<boolean>;
 }
 export declare const processStorageFileParamsType: Type<ProcessStorageFileParams>;
@@ -322,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.create.d.ts

@@ -5,7 +5,7 @@ import { type FirestoreDocumentAccessor } from '../../common/firestore/accessor/
 import { type FirebaseStorageAccessorFile } from '../../common/storage/driver/accessor';
 import { type StoragePathRef, type StoragePath } from '../../common/storage/storage';
 import { type FirebaseAuthOwnershipKey, type FirebaseAuthUserId } from '../../common/auth/auth';
-import { type StorageFilePurposeSubgroup, type StorageFileGroupId, type StorageFileGroupRelatedStorageFilePurpose, type StorageFileMetadata, type StorageFilePurpose } from './storagefile.id';
+import { type StorageFilePurposeSubgroup, type StorageFileGroupId, type StorageFileGroupRelatedStorageFilePurpose, type StorageFileId, type StorageFileMetadata, type StorageFilePurpose } from './storagefile.id';
 import { type ReadFirestoreModelKeyInput } from '../../common';
 /**
  * Input for creating a StorageFile document paired with its storage path.
@@ -13,8 +13,8 @@ import { type ReadFirestoreModelKeyInput } from '../../common';
  * Provides all the fields needed to create a fully-configured {@link StorageFile} Firestore document,
  * including ownership, purpose, group membership, and processing state.
  *
- * Either a `file`, `storagePathRef`, or `storagePath` must be provided to identify the storage location.
- * Either an `accessor` or `context` must be provided for Firestore document creation.
+ * Either a `file`, `storagePathRef`, `storagePath`, or `storagePathFactory` must be provided to identify the
+ * storage location. Either an `accessor` or `context` must be provided for Firestore document creation.
  *
  * @template M - type of arbitrary metadata stored in the `d` field
  */
@@ -43,6 +43,17 @@ export interface CreateStorageFileDocumentPairInput<M extends StorageFileMetadat
      * File to use when creating the StorageFile.
      */
     readonly file?: FirebaseStorageAccessorFile;
+    /**
+     * Builds the storage path from the id of the StorageFile document being created.
+     *
+     * Use this when the path should be keyed by the StorageFile itself rather than by the model it belongs
+     * to. Two StorageFiles then can never resolve to the same path, so replacing one cannot delete the
+     * other's content, and the path is not guessable from the owning model's id.
+     *
+     * Only consulted when no `file`, `storagePathRef`, or `storagePath` is provided, and only for a
+     * DIRECTLY_CREATED StorageFile — a FOR_STORAGE_FILE_GROUP file has a deterministic id by design.
+     */
+    readonly storagePathFactory?: Maybe<(storageFileId: StorageFileId) => StoragePath>;
     /**
      * The display name of the StorageFile.
      *

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.query.d.ts

@@ -9,6 +9,11 @@ import { type FirebaseAuthUserId } from '../../common/auth/auth';
  *
  * @returns Firestore query constraints for StorageFiles queued for processing.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFile
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory sweep
+ *
  * @example
  * ```ts
  * const constraints = storageFilesQueuedForProcessingQuery();
@@ -24,6 +29,11 @@ export declare function storageFilesQueuedForProcessingQuery(): FirestoreQueryCo
  * @param now - Reference time for comparison; defaults to current time.
  * @returns Firestore query constraints for StorageFiles whose scheduled delete date has passed.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFile
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory cleanup
+ *
  * @example
  * ```ts
  * const constraints = storageFilesQueuedForDeleteQuery();
@@ -48,6 +58,12 @@ export interface StorageFilePurposeAndUserQueryInput {
  * @param input - The user, purpose, and optional subgroup to filter by.
  * @returns Firestore query constraints for the given purpose and user.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFile
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
+ * @dbxModelFirebaseIndexSkip true
+ *
  * @example
  * @example
  * ```ts
@@ -65,6 +81,11 @@ export declare function storageFilePurposeAndUserQuery(input: StorageFilePurpose
  *
  * @returns Firestore query constraints for StorageFiles flagged for group synchronization.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFile
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory sweep
+ *
  * @example
  * @example
  * ```ts
@@ -79,6 +100,11 @@ export declare function storageFileFlaggedForSyncWithGroupsQuery(): FirestoreQue
  *
  * @returns Firestore query constraints for StorageFileGroups needing initialization.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFileGroup
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory init
+ *
  * @example
  * @example
  * ```ts
@@ -91,6 +117,11 @@ export declare function storageFileGroupsFlaggedForNeedsInitializationQuery(): F
  *
  * @returns Firestore query constraints for StorageFileGroups flagged for content regeneration.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFileGroup
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory sweep
+ *
  * @example
  * @example
  * ```ts
@@ -105,6 +136,11 @@ export declare function storageFileGroupsFlaggedForContentRegenerationQuery(): F
  *
  * @returns Firestore query constraints for StorageFileGroups flagged as invalid.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFileGroup
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory cleanup
+ *
  * @example
  * @example
  * ```ts

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/src/lib/model/system/index.d.ts

@@ -1,2 +1,3 @@
 export * from './system';
 export * from './system.action';
+export * from './system.scheduler';

package/src/lib/model/system/system.scheduler.d.ts

@@ -0,0 +1,235 @@
+/**
+ * @module system.scheduler
+ *
+ * Declares the framework-owned `scheduler` {@link SystemState} type, plus the pure predicates and
+ * the moment-bound read object that make up the "has this schedule already run in this hour?" gate.
+ *
+ * The gate exists so a cron that fires every hour can run a body that should only run every Nth
+ * hour, without each individual task having to carry a throttle of its own. Evaluate it ONCE at the
+ * top of a schedule function: pass, run the work; fail, return.
+ *
+ * The stateful half — read, evaluate, and claim the hour against Firestore — lives in
+ * `@dereekb/firebase-server/model` as `schedulerSystemStateAccessorFactory()`. Only the shape, the
+ * predicates, and {@link schedulerSystemStateRead} live here, so the evaluation can be exercised
+ * without an emulator and the converter can be registered from an app's client-shared converter
+ * map.
+ */
+import { type HourOfDay, type Hours, type Maybe } from '@dereekb/util';
+import { type FirestoreDocument, type FirestoreDocumentAccessor } from '../../common';
+import { type SystemState, type SystemStateDocument, type SystemStateStoredData, type SystemStateStoredDataFieldConverterConfig } from './system';
+/**
+ * {@link SystemState} type identifier for the scheduler's run-gate state.
+ *
+ * Also the document id, per the SystemState singleton convention — so this state lives at
+ * `sys/scheduler`.
+ */
+export declare const SCHEDULER_SYSTEM_STATE_TYPE = "scheduler";
+/**
+ * Scheduler state for gating scheduled work to at most one run per hour window.
+ *
+ * ONE gate, ONE `lat`. This is deliberately not per-task and not per-table state: it answers
+ * "has the scheduler already run its Nth-hour body during this hour?" for the app as a whole. Two
+ * callers sharing the document with different `everyNHours` values will have whichever one passes
+ * first claim the hour for both.
+ *
+ * @dbxModelSubObject
+ */
+export interface SchedulerSystemData extends SystemStateStoredData {
+    /**
+     * Last run at. The single gate anchor — the moment the most recent passing check claimed its hour.
+     *
+     * @dbxModelVariable lastRunAt
+     */
+    lat?: Maybe<Date>;
+}
+/**
+ * Firestore field converter for {@link SchedulerSystemData}.
+ *
+ * Register it in the app's `SystemStateStoredDataConverterMap` under
+ * {@link SCHEDULER_SYSTEM_STATE_TYPE}. This is NOT optional: without it the collection falls back to
+ * the pass-through converter, `lat` reads back as a raw Firestore `Timestamp` instead of a `Date`,
+ * and {@link hasRunInCurrentHour} can never match — so the gate would open on every single call.
+ */
+export declare const schedulerSystemDataConverter: SystemStateStoredDataFieldConverterConfig<SchedulerSystemData>;
+/**
+ * Loads the {@link SystemStateDocument} that stores {@link SchedulerSystemData}, using
+ * {@link SCHEDULER_SYSTEM_STATE_TYPE} as the document id.
+ *
+ * @param accessor - The document accessor for the SystemState collection.
+ * @returns The SystemState document for the scheduler state.
+ *
+ * @example
+ * ```ts
+ * const doc = loadSchedulerSystemState(systemStateCollection.documentAccessor());
+ * const data = await doc.snapshotData();
+ * ```
+ */
+export declare function loadSchedulerSystemState<D extends FirestoreDocument<SystemState<SystemStateStoredData>>>(accessor: FirestoreDocumentAccessor<SystemState<SystemStateStoredData>, D>): SystemStateDocument<SchedulerSystemData>;
+/**
+ * Whether the date's hour-of-day is an Nth hour, in the ambient timezone.
+ *
+ * This is a modulo against the hour-of-day, NOT an interval since some epoch — so at hour 12 it is
+ * true for N = 1, 2, 3, 4, 6, and 12, and false for N = 5. Only divisors of 24 divide the day
+ * evenly; a non-divisor (5, 7, 9, …) will still fire, just with a short window across midnight.
+ *
+ * An `everyNHours` of zero or less has no meaningful Nth hour and returns false rather than
+ * dividing by zero.
+ *
+ * @param everyNHours - Run every Nth hour of the day.
+ * @param date - Moment to test; defaults to now.
+ * @returns True when the date's hour-of-day is an Nth hour.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags schedule, hour, throttle, cron, gate, modulo
+ * @dbxUtilRelated has-run-in-current-hour
+ *
+ * @example
+ * ```ts
+ * isNthHourOfDay(3, new Date('2024-01-01T12:30:00')); // true (12 % 3 === 0)
+ * isNthHourOfDay(5, new Date('2024-01-01T12:30:00')); // false (12 % 5 === 2)
+ * ```
+ */
+export declare function isNthHourOfDay(everyNHours: Hours, date?: Maybe<Date>): boolean;
+/**
+ * Whether the last run falls inside the same hour as now.
+ *
+ * This is a same-hour-bucket compare, not an elapsed-time compare: a run at 12:59 and a `now` of
+ * 13:01 are two minutes apart but in different hours, so this returns false. That is what makes the
+ * gate track the hourly cron rather than drift with it.
+ *
+ * A null `lastRunAt` means nothing has run, so it returns false.
+ *
+ * @param lastRunAt - Moment the work last ran.
+ * @param now - Moment to compare against; defaults to now.
+ * @returns True when both moments fall in the same hour.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags schedule, hour, throttle, cron, gate, window
+ * @dbxUtilRelated is-nth-hour-of-day, round-down-to-hour
+ *
+ * @example
+ * ```ts
+ * hasRunInCurrentHour(new Date('2024-01-01T12:05:00'), new Date('2024-01-01T12:55:00')); // true
+ * hasRunInCurrentHour(new Date('2024-01-01T12:59:00'), new Date('2024-01-01T13:01:00')); // false
+ * ```
+ */
+export declare function hasRunInCurrentHour(lastRunAt: Maybe<Date>, now?: Maybe<Date>): boolean;
+/**
+ * The zero-based index of the date's hour within the day's every-N-hours schedule, or null when the
+ * hour is not an Nth hour.
+ *
+ * At hour 12 with N=3 the day's matching hours are 0, 3, 6, 9, 12 — so the index is 4. Use it to
+ * rotate work across a day's windows ("do the expensive pass only on index 0") without each caller
+ * re-deriving the arithmetic from the hour-of-day.
+ *
+ * Returns null rather than a number for a non-matching hour, so a falsy check cannot confuse
+ * "index 0" — the first window of the day — with "no window".
+ *
+ * @param everyNHours - Run every Nth hour of the day.
+ * @param date - Moment to test; defaults to now.
+ * @returns The zero-based window index, or null when the hour is not an Nth hour.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags schedule, hour, throttle, cron, gate, index, window
+ * @dbxUtilRelated is-nth-hour-of-day
+ *
+ * @example
+ * ```ts
+ * nthHourOfDayIndex(3, new Date('2024-01-01T12:30:00')); // 4 (0, 3, 6, 9, 12)
+ * nthHourOfDayIndex(3, new Date('2024-01-01T13:30:00')); // null (13 % 3 !== 0)
+ * ```
+ */
+export declare function nthHourOfDayIndex(everyNHours: Hours, date?: Maybe<Date>): Maybe<number>;
+/**
+ * A read of the scheduler's gate state, evaluated against a single moment.
+ *
+ * Holds the `now` and the `lastRunAt` it was built from, so every question below is answered against
+ * the same moment. Asking about N=2 and then N=3 cannot straddle an hour boundary mid-evaluation,
+ * and no question re-reads the document.
+ *
+ * This is the pure half of the gate. The Firestore-backed half — read, evaluate, and CLAIM the hour
+ * in a transaction — is `schedulerSystemStateAccessorFactory()` in `@dereekb/firebase-server/model`.
+ */
+export interface SchedulerSystemStateRead {
+    /**
+     * The moment this read was taken at.
+     */
+    readonly now: Date;
+    /**
+     * The hour-of-day of {@link SchedulerSystemStateRead.now}, in the ambient timezone.
+     */
+    readonly hourOfDay: HourOfDay;
+    /**
+     * The moment the most recent passing check claimed its hour, or null if the gate has never been
+     * claimed.
+     */
+    readonly lastRunAt: Maybe<Date>;
+    /**
+     * Whether {@link SchedulerSystemStateRead.lastRunAt} falls inside the same hour as `now` — that is,
+     * whether the gate has already been claimed during this hour.
+     */
+    readonly hasRunInCurrentHour: boolean;
+    /**
+     * Whether the gate is open for the given interval: `now` is an Nth hour of the day AND the gate
+     * has not already been claimed during this hour.
+     *
+     * This is a pure evaluation — it does NOT claim the hour. Use
+     * `SchedulerSystemStateAccessor.checkAndClaim()` to actually gate work.
+     *
+     * @param everyNHours - Run every Nth hour of the day.
+     * @returns True when the gate is open.
+     */
+    isOpen(everyNHours: Hours): boolean;
+    /**
+     * {@link isNthHourOfDay} bound to this read's `now`.
+     *
+     * Unlike {@link SchedulerSystemStateRead.isOpen} this ignores `lastRunAt` entirely, which is what
+     * makes it the right sub-gate for work running INSIDE an already-claimed hour: the hour is spent
+     * either way, so each task only needs to ask whether this is its hour.
+     *
+     * @param everyNHours - Run every Nth hour of the day.
+     * @returns True when this read's hour-of-day is an Nth hour.
+     */
+    isNthHourOfDay(everyNHours: Hours): boolean;
+    /**
+     * {@link nthHourOfDayIndex} bound to this read's `now`.
+     *
+     * @param everyNHours - Run every Nth hour of the day.
+     * @returns The zero-based window index, or null when this read's hour is not an Nth hour.
+     */
+    nthHourOfDayIndex(everyNHours: Hours): Maybe<number>;
+}
+/**
+ * Configuration for {@link schedulerSystemStateRead}.
+ */
+export interface SchedulerSystemStateReadConfig {
+    /**
+     * The moment to evaluate the gate against. Defaults to the current time.
+     */
+    readonly now?: Maybe<Date>;
+    /**
+     * The `lat` read off the scheduler document, or null/undefined when it has never been claimed.
+     */
+    readonly lastRunAt: Maybe<Date>;
+}
+/**
+ * Creates a {@link SchedulerSystemStateRead} from a moment and a last-run.
+ *
+ * Every predicate on the result closes over the single `now` resolved here, so a caller can ask
+ * about any number of intervals off one read without drifting across an hour boundary.
+ *
+ * @param config - The moment and the document's last-run.
+ * @returns The evaluated read.
+ *
+ * @example
+ * ```ts
+ * const read = schedulerSystemStateRead({ now, lastRunAt });
+ *
+ * read.isOpen(3); // should the every-3-hours body run?
+ * read.isNthHourOfDay(6); // is this also a 6th hour, for a sub-gated task?
+ * ```
+ */
+export declare function schedulerSystemStateRead(config: SchedulerSystemStateReadConfig): SchedulerSystemStateRead;

package/test/index.esm.js

@@ -1,7 +1,7 @@
 import { performAsyncTasks, cachedGetter, bitwiseObjectDencoder, modelFieldConversions, compareStrings, waitForMs, isEvenNumber, unique, arrayFactory, mapGetter, randomNumberFactory, randomFromArrayFactory, idBatchFactory, arrayContainsDuplicateValue, useCallback, readableStreamToBuffer, SLASH_PATH_SEPARATOR } from '@dereekb/util';
 import { initializeTestEnvironment } from '@firebase/rules-unit-testing';
 export { assertFails, assertSucceeds } from '@firebase/rules-unit-testing';
-import { firebaseStorageContextFactory, firestoreContextFactory, firebaseFirestoreClientDrivers, firebaseStorageClientDrivers, firestoreModelIdentity, snapshotConverterFunctions, firestoreBoolean, optionalFirestoreNumber, optionalFirestoreDate, optionalFirestoreArray, optionalFirestoreString, firestoreDate, firestoreBitwiseObjectMap, firestoreUniqueStringArray, firestoreNumber, firestoreString, firestoreUID, copyUserRelatedDataAccessorFactoryFunction, firestoreSubObject, defaultPagedItemPageDataConverter, AbstractFirestoreDocument, AbstractFirestoreDocumentWithParent, firebaseModelServiceFactory, grantFullAccessIfAdmin, firebaseModelsService, systemStateFirestoreCollection, allChildDocumentsUnderParent, where, makeDocuments, getDocumentSnapshotPairs, useDocumentSnapshot, useDocumentSnapshotData, firestoreIdBatchVerifierFactory, limit, orderBy, limitToLast, whereDocumentId, loadAllFirestoreDocumentSnapshotPairs, loadAllFirestoreDocumentSnapshot, iterateFirestoreDocumentSnapshotPairs, iterateFirestoreDocumentSnapshots, iterateFirestoreDocumentSnapshotPairBatches, iterateFirestoreDocumentSnapshotBatches, whereStringHasRootIdentityModelKey, whereStringValueHasPrefix, whereDateIsAfterWithSort, whereDateIsBeforeWithSort, whereDateIsOnOrAfterWithSort, whereDateIsOnOrBeforeWithSort, whereDateIsInRange, whereDateIsBetween, startAt, orderByDocumentId, startAtValue, startAfter, endAt, endAtValue, endBefore, streamFromOnSnapshot, latestSnapshotsFromDocuments, newDocuments, loadDocumentsForDocumentReferences, loadDocumentsForDocumentReferencesFromValues, loadDocumentsForKeys, loadDocumentsForKeysFromValues, loadDocumentsForIds, loadDocumentsForIdsFromValues, firestoreDocumentLoader, setIdAndKeyFromKeyIdRefOnDocumentData, firestoreModelIdFromDocument, firestoreModelIdsFromDocuments, firestoreModelKeyFromDocument, firestoreModelKeysFromDocuments, documentReferenceFromDocument, documentReferencesFromDocuments, limitedFirestoreDocumentAccessorSnapshotCache, mapLatestSnapshotsFromDocuments, streamDocumentSnapshotsData, dataFromDocumentSnapshots, streamDocumentSnapshotDataPairs, streamDocumentSnapshotDataPairsWithData, getDocumentSnapshots, getDocumentSnapshotPair, getDocumentSnapshotDataPair, getDocumentSnapshotDataPairs, getDocumentSnapshotDataPairsWithData, getDocumentSnapshotDataTuples, getDocumentSnapshotData, getDocumentSnapshotsData, getDataFromDocumentSnapshots, loadDocumentsForSnapshots, firestoreDocumentSnapshotPairsLoader, documentData, documentDataFunction, documentDataWithIdAndKey, setIdAndKeyFromSnapshotOnDocumentData, firebaseQuerySnapshotAccumulator, firebaseQueryItemAccumulator, uploadFileWithStream, iterateStorageListFilesByEachFile } from '@dereekb/firebase';
+import { firebaseStorageContextFactory, firestoreContextFactory, firebaseFirestoreClientDrivers, firebaseStorageClientDrivers, firestoreModelIdentity, snapshotConverterFunctions, firestoreBoolean, optionalFirestoreNumber, optionalFirestoreDate, optionalFirestoreArray, optionalFirestoreString, firestoreDate, firestoreBitwiseObjectMap, firestoreUniqueStringArray, firestoreNumber, firestoreString, firestoreUID, copyUserRelatedDataAccessorFactoryFunction, firestoreSubObject, defaultPagedItemPageDataConverter, AbstractFirestoreDocument, AbstractFirestoreDocumentWithParent, firebaseModelServiceFactory, grantFullAccessIfAdmin, firebaseModelsService, systemStateFirestoreCollection, allChildDocumentsUnderParent, where, makeDocuments, getDocumentSnapshotPairs, useDocumentSnapshot, useDocumentSnapshotData, firestoreIdBatchVerifierFactory, limit, orderBy, limitToLast, whereDocumentId, loadAllFirestoreDocumentSnapshotPairs, loadAllFirestoreDocumentSnapshot, iterateFirestoreDocumentSnapshotPairs, iterateFirestoreDocumentSnapshots, iterateFirestoreDocumentSnapshotPairBatches, iterateFirestoreDocumentSnapshotBatches, whereStringHasRootIdentityModelKey, whereStringValueHasPrefix, whereDateIsAfterWithSort, whereDateIsBeforeWithSort, whereDateIsOnOrAfterWithSort, whereDateIsOnOrBeforeWithSort, whereDateIsInRange, whereDateIsBetween, startAt, orderByDocumentId, startAtValue, startAfter, endAt, endAtValue, endBefore, streamFromOnSnapshot, latestSnapshotsFromDocuments, newDocuments, loadDocumentsForDocumentReferences, loadDocumentsForDocumentReferencesFromValues, loadDocumentsForKeys, loadDocumentsForKeysFromValues, loadDocumentsForIds, loadDocumentsForIdsFromValues, firestoreDocumentLoader, setIdAndKeyFromKeyIdRefOnDocumentData, firestoreModelIdFromDocument, firestoreModelIdsFromDocuments, firestoreModelKeyFromDocument, firestoreModelKeysFromDocuments, documentReferenceFromDocument, documentReferencesFromDocuments, limitedFirestoreDocumentAccessorSnapshotCache, mapLatestSnapshotsFromDocuments, streamDocumentSnapshotsData, dataFromDocumentSnapshots, streamDocumentSnapshotDataPairs, streamDocumentSnapshotDataPairsWithData, getDocumentSnapshots, getDocumentSnapshotPair, getDocumentSnapshotDataPair, getDocumentSnapshotDataPairs, getDocumentSnapshotDataPairsWithData, getDocumentSnapshotDataTuples, getDocumentSnapshotData, getDocumentSnapshotsData, getDataFromDocumentSnapshots, loadDocumentsForSnapshots, firestoreDocumentSnapshotPairsLoader, documentData, documentDataFunction, documentDataWithIdAndKey, setIdAndKeyFromSnapshotOnDocumentData, firebaseQuerySnapshotAccumulator, firebaseQueryItemAccumulator, storagePublicDownloadUrl, uploadFileWithStream, iterateStorageListFilesByEachFile } from '@dereekb/firebase';
 import { setLogLevel } from 'firebase/firestore';
 import { AbstractTestContextFixture, instanceWrapTestContextFactory, AbstractWrappedFixtureWithInstance, itShouldFail, callbackTest, expectFail } from '@dereekb/util/test';
 import { existsSync, readFileSync, createReadStream } from 'node:fs';
@@ -13221,6 +13221,29 @@ function _ts_generator(thisArg, body) {
                     })();
                 });
             });
+            describe('getPublicUrl()', function() {
+                it('should be reproducible by storagePublicDownloadUrl() from the bucket and path alone.', function() {
+                    // The point of this case: the CLIENT derives a public url with storagePublicDownloadUrl() rather
+                    // than calling anything, and that derivation is only useful if it matches what the SERVER actually
+                    // produces. Only the server driver implements getPublicUrl(), so this pins the shared function
+                    // against the real `@google-cloud/storage` output instead of against a reading of its source.
+                    if (existsFile.getPublicUrl) {
+                        var publicUrl = existsFile.getPublicUrl();
+                        var _existsFile_storagePath = existsFile.storagePath, bucketId = _existsFile_storagePath.bucketId, pathString = _existsFile_storagePath.pathString;
+                        // split off the origin the server resolved (localhost in the emulator, GCS in production) and
+                        // hand it back, so what is under test is the bucket + path half of the url
+                        var apiEndpoint = publicUrl.slice(0, publicUrl.indexOf("/".concat(bucketId, "/")));
+                        expect(apiEndpoint).toBeTruthy();
+                        expect(storagePublicDownloadUrl({
+                            apiEndpoint: apiEndpoint,
+                            storagePath: {
+                                bucketId: bucketId,
+                                pathString: pathString
+                            }
+                        })).toBe(publicUrl);
+                    }
+                });
+            });
             // Cannot be tested, will throw "Could not load the default credentials. Browse to https://cloud.google.com/docs/authentication/getting-started for more information."
             describe('getSignedUrl()', function() {
                 it('should return the signed read url.', function() {

package/test/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.41.0",
-    "@dereekb/firebase": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.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",