@mantlejs/supabase

Supabase adapter for Mantle JS. Provides a supabase() plugin, an abstract SupabaseRepository<T> base class backed by Supabase PostgREST, a supabaseAdapter() for cross-instance event sync via Supabase Realtime Broadcast, and optional Postgres Changes subscriptions that translate direct DB mutations into Mantle service events.

Installation

npm install @mantlejs/supabase @supabase/supabase-js

Concepts

The supabase() plugin

supabase(config) is a Mantle plugin. It creates a SupabaseClient and stores it on the application at app.get("supabase"). Call it once during app configuration before registering any repositories.

SupabaseRepository<T>

SupabaseRepository is an abstract base class that implements all eight Repository<T> methods against a Supabase-hosted PostgreSQL table via the Supabase PostgREST API. Extend it, set tableName, and optionally override primaryKey and timestamps.

supabaseAdapter() — Realtime Broadcast sync transport

supabaseAdapter() returns a SyncAdapter compatible with @mantlejs/sync. It replaces Redis with Supabase Realtime Broadcast channels so teams already using Supabase get horizontal scaling with zero additional infrastructure.

listenToChanges — Postgres Changes subscription

When a SupabaseRepository<T> subclass sets readonly listenToChanges = true, it opens a Supabase Realtime Postgres Changes subscription. Direct database mutations from PostgREST, Supabase Studio, migrations, or any other source are automatically translated to Mantle service:event emissions and fan out through the app event bus. This works alongside @mantlejs/sync — both can be active simultaneously.

QueryParams support

All standard Mantle QueryParams operators are translated to PostgREST filter calls:

| Operator | PostgREST equivalent | | ---------------------------- | --------------------------------------------- | | { field: value } | .eq(field, value) | | { field: null } | .is(field, null) | | $lt, $lte, $gt, $gte | .lt(), .lte(), .gt(), .gte() | | $ne | .neq() / .not(field, "is", null) for null | | $in | .in(field, []) | | $nin | .not(field, "in", "(…)") | | $like, $ilike | .like(), .ilike() | | $notlike | .not(field, "like", pattern) | | $contains | .contains(field, value) — PostgREST cs (@> containment) | | $or | .or(filter) | | $and | chained calls |

Nested paths and $contains

Dot-path field names address JSON columns and are translated to PostgREST arrow syntax: "metadata.owner.name" becomes metadata->owner->>name when compared against a string (text comparison) and metadata->owner->name otherwise (jsonb comparison).

$contains uses jsonb @> semantics: an array operand requires the field array to contain every element, a scalar operand is treated as a single element, and an object operand requires the field object to be a recursive superset. Scalar operands are wrapped in an array before being passed to .contains(). $contains is not supported inside $or — move it to the top level of the where clause (top-level conditions are ANDed).

await repo.findAll({
  where: {
    "metadata.owner.name": "alice",          // metadata->owner->>name = 'alice'
    "metadata.level": { $gt: 4 },            // metadata->level > 4 (jsonb)
    tags: { $contains: ["red", "blue"] },    // tags @> '["red","blue"]'
    metadata: { $contains: { owner: { name: "alice" } } },
  },
});

Quick start

import { mantle } from "@mantlejs/mantle";
import { express } from "@mantlejs/express";
import { supabase, SupabaseRepository } from "@mantlejs/supabase";

// 1. Configure the plugin
const app = mantle()
  .configure(express())
  .configure(
    supabase({
      url: process.env.SUPABASE_URL!,
      key: process.env.SUPABASE_KEY!,
    }),
  );

// 2. Define your entity
interface User {
  id: string;
  name: string;
  email: string;
  created_at?: string;
  updated_at?: string;
}

// 3. Create a repository
class UserRepository extends SupabaseRepository<User> {
  readonly tableName = "users";
}

// 4. Wire it up
app.use("/users", new UserService(new UserRepository(app)));

app.listen(3030);

Custom queries

Access the raw PostgREST query builder via this.db inside your repository:

class UserRepository extends SupabaseRepository<User> {
  readonly tableName = "users";

  async findByEmail(email: string): Promise<User | null> {
    const { data, error } = await this.db.select("*").eq("email", email).maybeSingle();
    if (error) throw this.wrapError(error);
    return data ?? null;
  }
}

API

supabase(config)

Returns a MantlePlugin. Call via app.configure(supabase(config)).

app.configure(
  supabase({
    url: process.env.SUPABASE_URL!, // required — Supabase project URL
    key: process.env.SUPABASE_KEY!, // required — anon or service_role key
    options: {
      // optional — SupabaseClientOptions
      auth: { autoRefreshToken: false },
    },
  }),
);

Side effects:

• Stores the SupabaseClient at app.get("supabase")

SupabaseConfig

| Field | Type | Default | Description | | --------- | ----------------------- | ------- | ------------------------------------------------------------------------------------ | | url | string | — | Supabase project URL (required) | | key | string | — | Supabase API key — anon for client-side, service_role for server-side (required) | | options | SupabaseClientOptions | — | Additional Supabase client options (optional) |

SupabaseRepository<T, D>

Abstract base class. Extend with a concrete tableName.

abstract class SupabaseRepository<T, D = Partial<T>> implements Repository<T, D> {
  abstract readonly tableName: string;
  readonly primaryKey: string; // default: "id"
  readonly timestamps: boolean; // default: true
}

Instance properties

| Property | Type | Default | Description | | ------------ | --------- | ------- | ------------------------------------------------------- | | tableName | string | — | Supabase table name (abstract — must be set) | | primaryKey | string | "id" | Primary key column name | | timestamps | boolean | true | Auto-write created_at / updated_at ISO-8601 strings |

Repository<T> methods

| Method | Description | | ---------------------- | ------------------------------------------------------------------------ | | findAll(params?) | Fetch all rows matching QueryParams (where, sort, limit, skip, select) | | findById(id) | Fetch a single row by primary key; returns null if not found | | save(data) | Insert a new row and return it | | saveAll(data[]) | Insert multiple rows and return them | | updateById(id, data) | Replace all non-key columns; throws NotFound if missing | | patchById(id, data) | Merge supplied fields only; throws NotFound if missing | | deleteById(id) | Delete a row and return it; throws NotFound if missing | | count(params?) | Count rows matching optional where clause |

protected db

Returns a PostgREST PostgrestQueryBuilder scoped to tableName. Use it in subclass custom queries.

listenToChanges

Set readonly listenToChanges = true in a subclass to subscribe to Postgres Changes for that table. Requires Realtime to be enabled for the table in your Supabase project settings.

class PostRepository extends SupabaseRepository<Post> {
  readonly tableName = "posts";
  readonly listenToChanges = true; // subscribe to WAL-based DB events
}

Changes are emitted as service:event on the app event bus:

| Postgres event | Mantle event | | -------------- | ------------ | | INSERT | created | | UPDATE | patched | | DELETE | removed |

External events carry { external: true }

These re-emissions did not pass through the hook pipeline — no before/after hooks ran, no validation, no params.user. So their params argument is { external: true } (typed on ServiceParams), letting event consumers (socket.io broadcasts, @mantlejs/sync, custom listeners) distinguish them from hook-pipeline events and, for example, skip authorization-derived filtering that assumes hook context.

Why UPDATE maps to patched — never updated

In Mantle, updated means "a caller replaced the full record via update()" while patched means "some fields changed". A WAL-level UPDATE only tells us the row's new state — the intent (full replace vs. partial mutation) is unknowable from outside the service layer. patched is the honest, conservative claim: consumers reacting to patched must already tolerate partial change, whereas mislabeling a partial write as updated would let them assume every field was intentionally set.

protected wrapError(err)

Maps Supabase / PostgreSQL error codes to typed MantleError subclasses. Call it in custom query methods to keep error handling consistent.

supabaseAdapter(options?)

Returns a SyncAdapter for use with @mantlejs/sync. Credentials fall back to SUPABASE_URL and SUPABASE_SERVICE_KEY (or SUPABASE_KEY) environment variables.

import { sync } from "@mantlejs/sync";
import { supabase, supabaseAdapter } from "@mantlejs/supabase";

const app = mantle()
  .configure(express())
  .configure(supabase({ url: process.env.SUPABASE_URL!, key: process.env.SUPABASE_SERVICE_KEY! }))
  .configure(socketio())
  .configure(sync({ adapter: supabaseAdapter() }));

SupabaseAdapterOptions

| Field | Type | Default | Description | | ----- | -------- | -------------------------------- | ---------------------------- | | url | string | SUPABASE_URL env var | Supabase project URL | | key | string | SUPABASE_SERVICE_KEY env var | Service role key |

Types

import type { SupabaseConfig, SupabaseAdapterOptions, SyncAdapter, SyncMessage } from "@mantlejs/supabase";
import { SupabaseRepository, supabaseAdapter } from "@mantlejs/supabase";

| Export | Kind | Description | | ------------------------ | -------------- | --------------------------------------------- | | SupabaseConfig | interface | Options passed to supabase() | | SupabaseRepository | abstract class | Base repository class to extend | | SupabaseAdapterOptions | interface | Options passed to supabaseAdapter() | | SyncAdapter | interface | Pluggable transport interface for sync | | SyncMessage | interface | Cross-instance sync message shape | | supabaseAdapter | function | Factory that returns a Supabase SyncAdapter |

Error mapping

All errors are converted to typed MantleError subclasses:

| PostgreSQL / PostgREST code | Error thrown | Condition | | --------------------------- | -------------------- | ---------------------------------------- | | PGRST116 | NotFound (404) | Zero rows returned by a .single() call | | 23505 | Conflict (409) | Unique constraint violation | | 23503, 23514, 23502 | BadRequest (400) | FK, check, or NOT NULL violation | | 42501, 28000, 28P01 | Forbidden (403) | Insufficient privilege | | anything else | GeneralError (500) | Unexpected error |

Development

npx nx build supabase   # compile
npx nx test supabase    # run tests
npx nx lint supabase    # lint

Publishing

Build before publishing:

npx nx build supabase

First publish (scoped packages require --access public):

cd packages/supabase
npm publish --access public

Subsequent releases — bump version in packages/supabase/package.json, then:

cd packages/supabase
npm publish

Testing locally with Verdaccio

# Terminal 1 — start the local registry
npx nx run @mantle/source:local-registry

# Terminal 2 — publish to it
cd packages/supabase
npm publish --registry http://localhost:4873

# Install from it in another project
npm install @mantlejs/supabase --registry http://localhost:4873