@rebasepro/server-mongo 0.21.2-canary.g1ea48be → 0.23.0

package/dist/auth/services.d.ts

@@ -20,6 +20,14 @@ export declare class MongoUserService implements UserRepository {
     getUserIdentities(uid: string): Promise<UserIdentityData[]>;
     linkUserIdentity(uid: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
     updateUser(id: string, data: Partial<Omit<CreateUserData, "id">>): Promise<UserData | null>;
+    /**
+     * Everything keyed by the user goes with them. Postgres does this by
+     * foreign-key cascade; Mongo has none, so it is spelled out — and the
+     * refresh tokens are the part that matters: left behind, a deleted user's
+     * session kept minting access tokens for a uid that no longer exists.
+     * Sessions first, so a failure part-way leaves an account that cannot sign
+     * in rather than a session with no account.
+     */
     deleteUser(id: string): Promise<void>;
     listUsers(): Promise<UserData[]>;
     listUsersPaginated(options?: ListUsersOptions): Promise<PaginatedUsersResult>;

package/dist/db/MongoConditionBuilder.d.ts

@@ -4,6 +4,7 @@
  * Translates Rebase filter conditions to MongoDB query operators.
  */
 import { CollectionConfig, FilterValues, LogicalCondition, OrderByTuple } from "@rebasepro/types";
+import { type FieldViewer } from "@rebasepro/common";
 import { Filter, Document } from "mongodb";
 /**
  * MongoDB Condition Builder
@@ -29,24 +30,53 @@ export declare class MongoConditionBuilder {
      *
      * Always returns a condition or throws: there is no operator this can be
      * given that legitimately means "no condition".
+     *
+     * `negated` asks for the documents where the condition is *false* — not
+     * merely not true. The two differ by the documents where it is unknown,
+     * which in SQL is a comparison against NULL: `NOT (status = 'draft')` does
+     * not return a row whose status is NULL, and the Postgres driver is the
+     * reference every caller of this API writes against. So a comparison is
+     * false only where the field holds a value and the comparison fails on it.
+     * The null tests are never unknown, and negate to each other.
      */
     private static buildCondition;
     /**
-     * Translate an `or(...)` / `and(...)` group, nesting included.
+     * Translate an `or(...)` / `and(...)` / `not(...)` group, nesting included.
+     *
+     * `not` negates the conjunction of its conditions — the rule stated on
+     * `LogicalCondition`. It used to fall through to the `and` branch, so
+     * `not(status = 'draft')` returned exactly the drafts. It is compiled by
+     * pushing the negation down to the leaves (De Morgan), each of which knows
+     * which documents make it false rather than merely not true — see
+     * {@link buildCondition}. A `$nor` around the group would be shorter and
+     * wrong: it also matches every document where the condition is unknown.
      *
      * Returns `undefined` for a group with nothing in it. `$or: []` is an error
      * in Mongo and `$and: []` matches every document, so neither is a
      * defensible reading of "no conditions".
      */
-    static buildLogicalConditions(logical: LogicalCondition | undefined): Filter<Document> | undefined;
+    static buildLogicalConditions(logical: LogicalCondition | undefined, negated?: boolean): Filter<Document> | undefined;
     /**
-     * Build search conditions for text search
+     * Build search conditions for text search.
+     *
+     * Terms are split on whitespace and AND-ed, while the fields are OR-ed
+     * within each term: a person typing `sebastian melendez` into a search box
+     * means both words, and the two live in different fields, so matching the
+     * whole string per field finds nothing. See {@link splitSearchTerms}; the
+     * Postgres driver's fallback path answers the same way.
      *
      * @param searchString - Text to search for
      * @param properties - The collection's properties, searched for string fields
-     * @returns Array of MongoDB filter objects for text search
+     * @param viewer - Who the search is for. A field they cannot read is not
+     *   one they may search: the strip keeps its value out of the response, and
+     *   without this the value is still recoverable a substring at a time by
+     *   watching which searches return the row. Absent is the trusted server
+     *   plane, which still does not search an `excludeFromApi` field — the same
+     *   answer the Postgres builder gives.
+     * @returns At most one MongoDB filter — callers OR what they get back, which
+     *   is right across fields and wrong across terms, so the AND is built here
      */
-    static buildSearchConditions(searchString: string, properties: CollectionConfig["properties"]): Filter<Document>[];
+    static buildSearchConditions(searchString: string, properties: CollectionConfig["properties"], viewer?: FieldViewer): Filter<Document>[];
     /**
      * Combine multiple conditions with AND operator
      *
@@ -78,6 +108,8 @@ export declare class MongoConditionBuilder {
         logical?: LogicalCondition;
         searchString?: string;
         properties?: CollectionConfig["properties"];
+        /** Who the query is for — see {@link buildSearchConditions}. */
+        viewer?: FieldViewer;
     }): Filter<Document>;
     /**
      * The primary key's name in a stored document.

package/dist/db/MongoDataService.d.ts

@@ -96,8 +96,39 @@ export declare class MongoDataService implements DataRepository {
      * partial row everywhere it went: the REST response, `afterSave`, the
      * history entry a revert restores from, and the row pushed to realtime
      * subscribers. Postgres returns the whole row here (`RETURNING *`).
+     *
+     * `mode` is which write the caller means when it names an `id`:
+     *
+     * - `"create"` inserts under that id, and a taken id is a 409. The driver
+     *   authorizes a create as an insert, against the values sent — so a
+     *   create that could land on an existing row is an update no update rule
+     *   ever saw. It was one: an upsert with `$set`, which let a caller name
+     *   another user's id with `status: "new"` and rewrite their row.
+     * - `"update"` updates that row and nothing else, and a missing one is a
+     *   404 — never a row conjured under an id nobody created.
+     * - absent, the repository's own "create or update": an upsert. Only the
+     *   repository's direct callers reach it; the driver always says which.
+     *
+     * `values` may carry field operations (`{ views: { $inc: 1 } }`), which
+     * change the stored value in the same write rather than replace it — see
+     * {@link compileFieldOp}. They were written into the document as literal
+     * objects, so a counter became `{ "$inc": 1 }` behind a 200. Only an
+     * update can carry one: there is no stored value for an insert to act on,
+     * and an upsert may be an insert.
+     */
+    save<M extends Record<string, any>>(collectionPath: string, values: Partial<M>, id?: string | number, _databaseId?: string, mode?: "create" | "update"): Promise<Record<string, unknown>>;
+    /**
+     * The aggregation expression one field operation compiles to, in an update
+     * pipeline's `$set`.
+     *
+     * The same meaning the Postgres compiler gives each one, NULL-safety
+     * included: an unset or null counter increments from zero and an absent
+     * array is pushed onto as an empty one, rather than the write failing on
+     * the first use of a field. `$push` and `$pull` take a value or a list of
+     * values, `$pull` removes every occurrence, and `$merge` is shallow — a
+     * nested object replaces, it is not merged into.
      */
-    save<M extends Record<string, any>>(collectionPath: string, values: Partial<M>, id?: string | number, _databaseId?: string): Promise<Record<string, unknown>>;
+    private compileFieldOp;
     /**
      * Read the document back after a write, falling back to the caller's own
      * values if it has already been removed by a concurrent delete.
@@ -115,9 +146,21 @@ export declare class MongoDataService implements DataRepository {
      */
     delete(collectionPath: string, id: string | number, _databaseId?: string): Promise<void>;
     /**
-     * Check if a field value is unique in a collection
+     * Check if a field value is unique in a collection.
+     *
+     * An equality test on one field, and nothing else a query can express. The
+     * name and the value arrive from a socket frame, and this used to be
+     * `countDocuments({ [name]: value })`: a value of `{ $regex: "^123" }`
+     * answered, one prefix at a time, what a field of a row the caller cannot
+     * see begins with, and a name of `$expr` evaluated an aggregation
+     * expression. So an operator name is refused, the value must be a scalar,
+     * and it is compared with `$eq` — which reads an object as a literal even
+     * if one got this far.
+     *
+     * An absent value is unique, as it is on Postgres: an empty optional field
+     * is not "taken" by every row that also left it empty.
      */
-    checkUniqueField(collectionPath: string, fieldName: string, value: any, excludeEntityId?: string, _databaseId?: string): Promise<boolean>;
+    checkUniqueField(collectionPath: string, fieldName: string, value: unknown, excludeEntityId?: string, _databaseId?: string): Promise<boolean>;
     /**
      * Generate a new row ID
      */