Configuration
The Mongalayer client SDK is a lightweight HTTP client that communicates with a Mongalayer server. It works in any JavaScript runtime that supports fetch, mainly built for usage inside browser applications.
The client API is intentionally designed to mirror the server-side MongoDB driver methods (find, findOne, insertOne, updateMany, etc.), so querying from the client feels like writing native MongoDB code — similar to how Atlas App Services allowed client applications to talk to MongoDB directly.
Creating a client
import { MongalayerClient } from "@mongalayer/client";
const client = new MongalayerClient("https://.../api/mongalayer");
The first argument is the URL of your Mongalayer endpoint.
Options
Pass an optional second argument to configure the client:
const client = new MongalayerClient("https://.../api/mongalayer", {
format: "json",
headers: {
"Authorization": "Bearer [my-token]"
},
credentials: "include"
});
format
Controls how the client sends requests:
| Value | Description |
|---|---|
"json" | Sends action and payload as a single JSON body (default) |
"routed" | Uses URL path segments: /{database}/{collection}/{operation} |
This gives you flexibility in how you structure your API routes and can be useful for integrating with existing RESTful endpoints.
JSON format (default):
POST /api/mongalayer
{
"action": { "database": "myapp", "collection": "projects", "operation": "find" },
"payload": { "filter": {} }
}
Routed format:
POST /api/mongalayer/myapp/projects/find
{ "filter": {} }
headers
HTTP headers to include with every request. Can be a static object, a function, or an async function:
// Dynamic headers (re-evaluated on each request)
headers: () => ({
"Authorization": `Bearer ${getToken()}`
})
// Async headers
headers: async () => {
const token = await getToken();
return { "Authorization": `Bearer ${token}` };
}
// Static headers - highly discouraged for auth tokens
headers: {
"Authorization": "Bearer token"
}
credentials
Maps directly to the credentials option of the Fetch API:
credentials: "include" // Send cookies cross-origin
credentials: "same-origin" // Send cookies for same-origin only
credentials: "omit" // Never send cookies
Updating configuration
You can update client settings after creation:
client.setFormat("routed");
client.setHeaders(() => ({
"Authorization": `Bearer ${getToken()}`
}));
client.setCredentials("include");
Database and collection access
The client uses a chainable API similar to the MongoDB driver:
const db = client.db("myapp");
const projects = db.collection("projects");
// Or chain directly
const result = await client.db("myapp").collection("projects").find({});
Context parameter
Every collection method accepts an optional context parameter as the last argument. This value is a JSON stringified and Base64-encoded query parameter, and can be used to pass additional information to your HTTP layer (not to Mongalayer itself):
await projects.find({}, { limit: 10 }, { source: "dashboard" });
// ^^^^^^^^^^^^^^^^^^^^^^^^
// Sent as ?context=... query param
This is useful when your HTTP middleware needs to differentiate between request sources or pass extra metadata.
context parameter is not validated or interpreted by Mongalayer. It is purely for your HTTP layer's use.