@dereekb/firebase-server 13.6.17 → 13.8.0

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

@@ -9,3 +9,4 @@ export * from './create.model.function';
 export * from './read.model.function';
 export * from './update.model.function';
 export * from './delete.model.function';
+export * from './query.model.function';

package/src/lib/nest/model/query.model.function.d.ts

@@ -0,0 +1,207 @@
+import { type Maybe, type PromiseOrValue } from '@dereekb/util';
+import { type FirestoreModelType, type FirestoreModelIdentity, type FirestoreModelTypes, type OnCallQueryModelParams, type OnCallQueryModelRequestParams, type OnCallQueryModelResult, type ModelFirebaseCrudFunctionSpecifierRef, type FirestoreModelKey, type FirestoreCollectionLike, type FirestoreQueryConstraint, type DocumentSnapshot, type QueryDocumentSnapshot } from '@dereekb/firebase';
+import { type OnCallWithAuthAwareNestRequireAuthRef, type OnCallWithNestContext } from '../function/call';
+import { type NestContextCallableRequestWithAuth, type NestContextCallableRequestWithOptionalAuth } from '../function/nest';
+import { type AssertModelCrudRequestFunction } from './crud.assert.function';
+/**
+ * Request type for model query handlers that require authentication.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type for the query operation. Must extend {@link OnCallQueryModelRequestParams}.
+ */
+export type OnCallQueryModelRequest<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams> = NestContextCallableRequestWithAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model query handler function that requires an authenticated caller.
+ */
+export type OnCallQueryModelFunctionWithAuth<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams, O = unknown> = ((request: OnCallQueryModelRequest<N, I>) => PromiseOrValue<O>) & {
+    readonly _requiresAuth?: true;
+};
+/**
+ * Request type for model query handlers that allow unauthenticated callers.
+ */
+export type OnCallQueryModelRequestWithOptionalAuth<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams> = NestContextCallableRequestWithOptionalAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model query handler function that does not require authentication.
+ *
+ * Useful for public-facing query endpoints such as listing public content.
+ */
+export type OnCallQueryModelFunctionWithOptionalAuth<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams, O = unknown> = ((request: OnCallQueryModelRequestWithOptionalAuth<N, I>) => PromiseOrValue<O>) & {
+    readonly _requireAuth: false;
+};
+/**
+ * Standard model query handler requiring auth (the common case).
+ */
+export type OnCallQueryModelFunction<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams, O = unknown> = OnCallQueryModelFunctionWithAuth<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef;
+/**
+ * Union of auth-required and optional-auth query handlers.
+ */
+export type OnCallQueryModelFunctionAuthAware<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams, O = unknown> = OnCallQueryModelFunction<N, I, O> | OnCallQueryModelFunctionWithOptionalAuth<N, I, O>;
+/**
+ * Maps Firestore model type strings to their query handler functions.
+ *
+ * Pass this map to {@link onCallQueryModel} to register all model types
+ * that support querying through the call model system.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam T - The Firestore model identity constraining valid model type keys.
+ */
+export type OnCallQueryModelMap<N, T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
+    readonly [K in FirestoreModelTypes<T>]?: OnCallQueryModelFunctionAuthAware<N, any, any>;
+};
+/**
+ * Configuration for {@link onCallQueryModel}.
+ */
+export interface OnCallQueryModelConfig<N> {
+    /**
+     * Optional assertion run before the query handler; throw to reject.
+     */
+    readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallQueryModelParams>;
+}
+/**
+ * Factory that creates a callable function handling model queries for multiple model types.
+ *
+ * Dispatches to the correct handler based on the `modelType` field in the request,
+ * enforces auth requirements per handler, and aggregates API details for MCP introspection.
+ *
+ * Query handlers receive filter/pagination params in the request data and should return
+ * an {@link OnCallQueryModelResult} with paginated results. Use {@link executeOnCallQuery}
+ * within handlers to handle cursor pagination automatically.
+ *
+ * @param map - Maps model type strings to their query handler functions.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function for the 'query' call type.
+ *
+ * @example
+ * ```typescript
+ * const queryHandler = onCallQueryModel<DemoNestContext>({
+ *   profile: queryProfiles,
+ *   guestbook: queryGuestbooks
+ * });
+ *
+ * // Register as the 5th call type in onCallModel:
+ * const callModel = onCallModel({
+ *   create: onCallCreateModel({ ... }),
+ *   read: onCallReadModel({ ... }),
+ *   update: onCallUpdateModel({ ... }),
+ *   delete: onCallDeleteModel({ ... }),
+ *   query: queryHandler
+ * });
+ * ```
+ */
+export declare function onCallQueryModel<N>(map: OnCallQueryModelMap<N>, config?: OnCallQueryModelConfig<N>): OnCallWithNestContext<N, OnCallQueryModelParams, unknown>;
+/**
+ * Creates a bad-request error indicating the requested model type is not valid for querying.
+ *
+ * @param modelType - The unrecognized model type string.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
+ */
+export declare function queryModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates a bad-request error indicating the cursor document key is invalid or inaccessible.
+ *
+ * @param cursorDocumentKey - The cursor document key that failed to resolve.
+ * @returns A bad-request error with {@link BAD_DOCUMENT_QUERY_CURSOR_ERROR_CODE} code.
+ */
+export declare function queryModelBadCursorError(cursorDocumentKey: Maybe<FirestoreModelKey>): import("firebase-functions/https").HttpsError;
+/**
+ * Configuration for {@link executeOnCallQuery}.
+ *
+ * @typeParam T - The Firestore document data type.
+ * @typeParam R - The mapped result type for each document. Defaults to T.
+ */
+export interface ExecuteOnCallQueryConfig<T, R = T> {
+    /**
+     * The query request params containing limit and cursorDocumentKey.
+     */
+    readonly params: OnCallQueryModelRequestParams;
+    /**
+     * The Firestore collection to query against.
+     *
+     * Used for building queries (via {@link FirestoreQueryFactory}).
+     */
+    readonly collection: FirestoreCollectionLike<T>;
+    /**
+     * Loads and permission-checks the cursor document when {@link OnCallQueryModelRequestParams.cursorDocumentKey} is provided.
+     *
+     * This function must verify that the caller has read access to the cursor document.
+     * Typically implemented using `nest.useModel()` which enforces permission checking.
+     * Must return the document's snapshot for use with `startAfter`.
+     *
+     * If the cursor document does not exist or the caller lacks permission, this function
+     * should throw an appropriate error (e.g., forbidden or not-found).
+     *
+     * @param cursorDocumentKey - The Firestore model key of the cursor document.
+     * @returns A promise resolving to the cursor document's snapshot.
+     *
+     * @example
+     * ```typescript
+     * loadCursorDocument: async (key) => {
+     *   const doc = await nest.useModel('guestbook', {
+     *     request,
+     *     key,
+     *     roles: 'read',
+     *     use: (x) => x.document
+     *   });
+     *   return doc.accessor.get();
+     * }
+     * ```
+     */
+    readonly loadCursorDocument: (cursorDocumentKey: FirestoreModelKey) => PromiseOrValue<DocumentSnapshot<T>>;
+    /**
+     * Builds query constraints to apply to the query.
+     *
+     * Return where/orderBy constraints here. Do NOT add limit or startAfter —
+     * those are managed by {@link executeOnCallQuery} automatically.
+     *
+     * @returns Array of query constraints to apply. May be async if constraints depend on external data.
+     */
+    readonly buildConstraints: () => PromiseOrValue<FirestoreQueryConstraint[]>;
+    /**
+     * Optional maximum items per page override. Defaults to {@link MAX_ON_CALL_QUERY_MODEL_LIMIT}.
+     *
+     * The effective limit is: `min(params.limit ?? DEFAULT, maxLimit)`.
+     */
+    readonly maxLimit?: number;
+    /**
+     * Optional transform applied to each document snapshot's data before returning.
+     *
+     * Defaults to `snapshot.data()`.
+     */
+    readonly mapResult?: (snapshot: QueryDocumentSnapshot<T>) => R;
+}
+/**
+ * Executes a paginated query using cursor-based pagination.
+ *
+ * Handles the mechanics of:
+ * - Clamping the page limit to the configured maximum
+ * - Resolving the cursor document key to a snapshot for `startAfter`
+ * - Fetching one extra document to detect whether more results exist
+ * - Building the {@link OnCallQueryModelResult} with cursorDocumentKey and hasMore
+ *
+ * @example
+ * ```typescript
+ * export const queryGuestbooks: DemoQueryModelFunction<QueryGuestbooksParams, OnCallQueryModelResult<Guestbook>> = async (request) => {
+ *   const { nest, data } = request;
+ *   return executeOnCallQuery({
+ *     params: data,
+ *     collection: nest.demoFirestoreCollections.guestbookCollection,
+ *     loadCursorDocument: async (key) => {
+ *       const doc = await nest.useModel('guestbook', { request, key, roles: 'read', use: (x) => x.document });
+ *       return doc.accessor.get();
+ *     },
+ *     buildConstraints: () => {
+ *       const constraints: FirestoreQueryConstraint[] = [];
+ *       if (data.published != null) {
+ *         constraints.push(where('published', '==', data.published));
+ *       }
+ *       constraints.push(orderBy('name', 'asc'));
+ *       return constraints;
+ *     }
+ *   });
+ * };
+ * ```
+ *
+ * @param config - Query configuration including collection, constraints, and pagination params.
+ * @returns Paginated query result with cursor for the next page.
+ */
+export declare function executeOnCallQuery<T, R = T>(config: ExecuteOnCallQueryConfig<T, R>): Promise<OnCallQueryModelResult<R>>;

package/src/lib/nest/model/read.model.function.d.ts

@@ -80,6 +80,6 @@ export declare function onCallReadModel<N>(map: OnCallReadModelMap<N>, config?:
  * Creates a bad-request error indicating the requested model type is not valid for reading.
  *
  * @param modelType - The unrecognized model type string.
- * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
  */
 export declare function readModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

package/src/lib/nest/model/update.model.function.d.ts

@@ -81,6 +81,6 @@ export declare function onCallUpdateModel<N>(map: OnCallUpdateModelMap<N>, confi
  * Creates a bad-request error indicating the requested model type is not valid for updating.
  *
  * @param modelType - The unrecognized model type string.
- * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
  */
 export declare function updateModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

package/src/lib/nest/nest.provider.d.ts

@@ -87,6 +87,20 @@ export declare abstract class AbstractFirebaseNestContext<A, Y extends FirebaseM
      * @returns An in-context models service scoped to the given auth context.
      */
     model(context: AuthDataRef, buildFn?: BuildFunction<FirebaseAppModelContext<A>>): InContextFirebaseModelsService<Y>;
+    /**
+     * Loads a model document by key, checks permissions against the requested roles,
+     * and optionally transforms the result via a `use` function.
+     *
+     * When called without a `use` function, returns the {@link ContextGrantedModelRolesReader}
+     * which provides access to the document and its granted roles.
+     *
+     * @throws Throws {@link nestFirebaseDoesNotExistError} if the document does not exist.
+     * @throws Throws {@link nestFirebaseForbiddenPermissionError} if the caller lacks the requested roles.
+     *
+     * @param type - The model type string (e.g., 'profile', 'guestbook').
+     * @param select - Selection params including key, roles, and optional use function.
+     * @returns The result of the `use` function, or the roles reader if no `use` function is provided.
+     */
     useModel<T extends FirebaseModelsServiceTypes<Y>, O>(type: T, select: UseModelInput<FirebaseAppModelContext<A>, Y, T, O>): Promise<O>;
     useModel<T extends FirebaseModelsServiceTypes<Y>>(type: T, select: UseModelInputForRolesReader<FirebaseAppModelContext<A>, Y, T>): Promise<FirebaseModelsServiceSelectionResultRolesReader<Y, T>>;
     /**
@@ -95,6 +109,11 @@ export declare abstract class AbstractFirebaseNestContext<A, Y extends FirebaseM
      * Uses {@link performAsyncTasks} internally. The `use` function receives the array of
      * successful {@link ContextGrantedModelRolesReader} values and an array of failed items.
      *
+     * Individual documents that do not exist throw {@link nestFirebaseDoesNotExistError},
+     * and documents where the caller lacks the requested roles throw
+     * {@link nestFirebaseForbiddenPermissionError}. These errors are captured per-key
+     * and passed to the `use` function via the failure array (unless `throwOnFirstError` is true).
+     *
      * @param type - the model type to load
      * @param select - selection params including keys array, roles, and use function
      * @returns the result of the use function