#Authorized Collection

subject.data.collection() creates the guarded data facade that combines caller filters, scope fields, policy where, field permissions, and MonSQLize operations.

#Purpose and preconditions

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#What Do You Want To Do

#Signatures

The signatures below are the public contract. The code block is kept executable-looking so TypeScript users can compare argument order, option requirements, and raw return wrappers quickly.

subject.data.collection<TDocument extends object, TCreate extends object = Omit<TDocument, '_id'>>(
  name: string,
  options: AuthorizedCollectionOptions,
): AuthorizedCollection<TDocument, TCreate>

find(filter?: SafeMongoFilter, options?: AuthorizedReadOptions): Promise<AuthorizedDocument<TDocument>[]>
findOne(filter?: SafeMongoFilter, options?: AuthorizedFindOneOptions): Promise<AuthorizedDocument<TDocument> | null>
count(filter?: SafeMongoFilter, options?: Pick<AuthorizedReadOptions, 'maxTimeMS' | 'transaction'>): Promise<number>
findAndCount(filter?: SafeMongoFilter, options?: AuthorizedReadOptions): Promise<{ data: AuthorizedDocument<TDocument>[]; total: number }>
findPage(query?: AuthorizedPageQuery): Promise<AuthorizedPageResult<TDocument>>
insertOne(document: TCreate, options?: { transaction?: Transaction }): Promise<AuthorizedInsertResult>
updateOne(filter: SafeMongoFilter, update: SafeMongoUpdate, options?: { transaction?: Transaction }): Promise<AuthorizedUpdateResult>
updateMany(filter: SafeMongoFilter, update: SafeMongoUpdate, options: AuthorizedBulkWriteOptions): Promise<AuthorizedUpdateResult>
deleteOne(filter: SafeMongoFilter, options?: { transaction?: Transaction }): Promise<AuthorizedDeleteResult>
deleteMany(filter: SafeMongoFilter, options: AuthorizedBulkWriteOptions): Promise<AuthorizedDeleteResult>

#Parameter Objects

The table explains object fields that are easy to confuse at call sites. Required fields are validated before the method mutates persistent authorization state.

#AuthorizedCollectionOptions

#Query and Write Options

#Method Details

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#subject.data.collection(name, options)

• Purpose: Create an AuthorizedCollection bound to the subject, collection name, scope mapping, and optional field policy.
• Parameters: Pass trusted host state only: normalized scope, authenticated user ID, claims/context, and collection options that map every active scope field.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#find(filter?, options?)

• Purpose: Run a scoped find query after permission-core merges tenant scope, row filters, and field projection.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#findOne(filter?, options?)

• Purpose: Read the first authorized document that matches the caller's filter after scope and row rules are applied.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#count(filter?, options?)

• Purpose: Count only the documents visible to the subject after scope and row filters are merged.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#findAndCount(filter?, options?)

• Purpose: Fetch authorized rows and the matching authorized count in one helper for offset-style pages.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#findPage(query?)

• Purpose: Fetch a signed-cursor page while preserving the same permission scope and filter constraints across page turns.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: PageResult<T> or the documented paged business result. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#insertOne(document, options?)

• Purpose: Insert one document only when the subject has write permission and the payload satisfies scope and field rules.
• Parameters: Use the ID, input object, revision or preview options shown in the signature. Values must come from the current scope and from a fresh read or preview when revision protection is required.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#updateOne(filter, update, options?)

• Purpose: Update one authorized document after merging scope filters and checking writeable fields.
• Parameters: Use the ID, input object, revision or preview options shown in the signature. Values must come from the current scope and from a fresh read or preview when revision protection is required.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#updateMany(filter, update, options)

• Purpose: Update many authorized documents while applying the same scope, row, and field checks to the bulk operation.
• Parameters: Use the ID, input object, revision or preview options shown in the signature. Values must come from the current scope and from a fresh read or preview when revision protection is required.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#deleteOne(filter, options?)

• Purpose: Delete one document only if it is visible to the subject and the subject has delete permission.
• Parameters: Use the ID, input object, revision or preview options shown in the signature. Values must come from the current scope and from a fresh read or preview when revision protection is required.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#deleteMany(filter, options)

• Purpose: Delete multiple authorized documents while fail-closed scope and row filters prevent cross-tenant deletion.
• Parameters: Use the ID, input object, revision or preview options shown in the signature. Values must come from the current scope and from a fresh read or preview when revision protection is required.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#Responses and side effects

Side effects are scoped and revisioned. Writes record audit evidence and invalidate affected semantic cache keys; reads preserve bounded detail metadata so callers can tell whether diagnostics were complete.

{
  "read": [{ "orderNo": "A-100", "merchantId": "m-7" }],
  "insert": { "acknowledged": true, "insertedId": "..." },
  "update": { "acknowledged": true, "matchedCount": 1, "modifiedCount": 1 },
  "delete": { "acknowledged": true, "deletedCount": 1 }
}

#Failures and limits

Failures close authorization instead of widening it. Important limits are enforced before state is committed, and stale previews or revisions must be refreshed rather than guessed.

#Example

The example keeps one narrow path per page. It shows the raw method family and a compact response shape, while the full runnable scenarios live in the examples section.

const orders = subject.data.collection('orders', {
  resource: 'db:orders',
  scopeFields: { tenantId: 'tenantId' },
});
const result = await orders.find(
  { status: { $in: ['paid', 'shipped'] } },
  { projection: ['orderNo', 'merchantId'], limit: 20 },
);

[{ "orderNo": "A-100", "merchantId": "m-7" }]

#Related

Continue with the linked guide or neighboring API page when you need workflow context rather than only signatures.

Continue with Audit and Health.