@mongalayer/client

Operations

All supported operations and how to use them from the client SDK.

The Collection class provides typed methods for all supported MongoDB operations. Each method sends an HTTP request to your Mongalayer server.

The method signatures intentionally mirror the MongoDB Node.js driver, so the API feels familiar whether you're writing server-side or client-side code.

Mongalayer does not support the full MongoDB API. Only a subset of operations, filters, aggregations and options that make sense in a client-server context are implemented. Check out the compatibility section for details on supported features and limitations.

Read operations

`findOne(filter, options?, context?)`

Find a single document matching a filter.

const project = await projects.findOne<Project>(
  { _id: "project-123" },
  { projection: { name: 1, owner: 1 } }
);
// Returns: Project | null

Option	Type	Description
`projection`	`Projection`	Fields to include or exclude
`sort`	`Sort`	Sort order for selecting which document to return

`find(filter, options?, context?)`

Find multiple documents matching a filter.

const allProjects = await projects.find<Project>(
  { owner: "user-1" },
  { sort: { createdAt: -1 }, limit: 10, skip: 0 }
);
// Returns: Project[]

Option	Type	Description
`projection`	`Projection`	Fields to include or exclude
`limit`	`number`	Maximum number of documents to return
`skip`	`number`	Number of documents to skip
`sort`	`Sort`	Sort order for the results

`aggregate(pipeline, options?, context?)`

Run an aggregation pipeline.

const stats = await projects.aggregate<{ _id: string; count: number }>(
  [
    { $match: { status: "active" } },
    { $group: { _id: "$owner", count: { $sum: 1 } } }
  ]
);
// Returns: { _id: string; count: number }[]

When using access definitions with aggregate, add a $sort stage to your pipeline as the results order may vary due to role resolution.

Create operations

`insertOne(document, options?, context?)`

Insert a single document. The document is validated against the collection schema.

const inserted = await projects.insertOne<Project>({
  _id: crypto.randomUUID(),
  name: "New Project",
  owner: "user-1",
  members: [],
  createdAt: new Date()
});

`insertMany(documents, options?, context?)`

Insert multiple documents. All documents are validated against the collection schema.

const inserted = await projects.insertMany<Project>([
  { _id: "p1", name: "Project 1", ... },
  { _id: "p2", name: "Project 2", ... }
]);

Option	Type	Description
`ordered`	`boolean`	When `true`, inserts documents in order and stops on first error. When `false`, attempts all inserts regardless of errors

Update operations

`updateOne(filter, update, options?, context?)`

Update a single document matching a filter.

const result = await projects.updateOne<Project>(
  { _id: "project-123" },
  { $set: { name: "Updated Name", "config.tags": ["new-tag"] } }
);

Option	Type	Description
`upsert`	`boolean`	When `true`, creates a new document if no match is found
`sort`	`Sort`	Sort order for selecting which document to update

`updateMany(filter, update, options?, context?)`

Update multiple documents matching a filter.

const result = await projects.updateMany<Project>(
  { status: "draft" },
  { $set: { status: "published", updatedAt: new Date() } }
);

`findOneAndUpdate(filter, update, options?, context?)`

Find a document, update it, and return the result.

const updated = await projects.findOneAndUpdate<Project>(
  { _id: "project-123" },
  { $set: { name: "Updated" } },
  { projection: { name: 1 } }
);
// Returns: Project | null

Option	Type	Description
`projection`	`Projection`	Fields to include or exclude in the returned document
`upsert`	`boolean`	When `true`, creates a new document if no match is found
`sort`	`Sort`	Sort order for selecting which document to update
`returnDocument`	`"before" \| "after"`	Whether to return the document before or after the update

Supported update operators

Operator	Description
`$set`	Set the value of a field
`$unset`	Remove a field (must be `optional()` in schema)
`$inc`	Increment a numeric field

Dot notation is supported for nested fields:

{
  $set: {
    "config.tags": ["updated"],
    "data.location.city": "New York"
  }
}

Positional $ operators are supported for updating array elements:

{
  filter: { "items.id": "item-1" },
  update: {
    $set: { "items.$.status": "completed" }
  }
}

Delete operations

`deleteOne(filter, options?, context?)`

Delete a single document matching a filter.

const result = await projects.deleteOne<Project>(
  { _id: "project-123" }
);

`deleteMany(filter, options?, context?)`

Delete multiple documents matching a filter.

const result = await projects.deleteMany<Project>(
  { status: "archived" }
);

Delete operations require the delete: true permission on the matching access role, or accessDefaults.delete set to true.

Type safety

All methods accept a generic type parameter <TSchema> for type-safe filters, updates, and return values:

import type { Document, Filter, Update, Projection } from "@mongalayer/client";

Serialization

The client automatically handles serialization of special types:

Date objects are serialized and deserialized correctly
Request bodies are sent as JSON with a custom stringifyReplacer
Response bodies are parsed with a custom parseReviver

This ensures that types like Date survive the HTTP round-trip without losing their type information.

Edit this pageorReport an issue

Configuration

Set up and configure the Mongalayer client SDK.

Performance

Pitfalls and tips for optimizing Mongalayer performance.