@flaghoist/adapter-postgres 0.1.2 → 0.2.0

package/README.md

@@ -28,6 +28,11 @@ await pool.query(postgresSchema())
 
 Pass a name if you want it somewhere other than `flaghoist_flags`.
 
+Webhook endpoints (if you use them) live in a second table, `flaghoist_webhooks` by default.
+`postgresWebhookSchema()` gives you that table's SQL the same way, and `postgresAdapter(pool, {
+webhookTable: '...' })` renames it. `initPostgres(pool)` creates every table the adapter uses in one call, if you'd
+rather not run the statements by hand.
+
 This is the one to choose when your flags should live in a database you already back up, or when the
 database sits inside a VPC that a Worker cannot reach anyway. Note that it wants a real TCP
 connection, so it suits Node, Bun or a container rather than an edge runtime.

package/dist/index.cjs

@@ -22,7 +22,9 @@ var index_exports = {};
 __export(index_exports, {
   initPostgres: () => initPostgres,
   postgresAdapter: () => postgresAdapter,
-  postgresSchema: () => postgresSchema
+  postgresRecordSchema: () => postgresRecordSchema,
+  postgresSchema: () => postgresSchema,
+  postgresWebhookSchema: () => postgresWebhookSchema
 });
 module.exports = __toCommonJS(index_exports);
 var import_core = require("@flaghoist/core");
@@ -38,8 +40,31 @@ function assertIdentifier(name) {
 function postgresSchema(table = "flaghoist_flags") {
   return `CREATE TABLE IF NOT EXISTS ${assertIdentifier(table)} (key text PRIMARY KEY, value jsonb NOT NULL)`;
 }
-async function initPostgres(client, table = "flaghoist_flags") {
+function postgresWebhookSchema(table = "flaghoist_webhooks") {
+  return `CREATE TABLE IF NOT EXISTS ${assertIdentifier(table)} (id text PRIMARY KEY, value jsonb NOT NULL)`;
+}
+function postgresRecordSchema(table = "flaghoist_records") {
+  return `CREATE TABLE IF NOT EXISTS ${assertIdentifier(table)} (collection text NOT NULL, id text NOT NULL, value jsonb NOT NULL, PRIMARY KEY (collection, id))`;
+}
+async function initPostgres(client, table = "flaghoist_flags", webhookTable = "flaghoist_webhooks", recordTable = "flaghoist_records") {
   await client.query(postgresSchema(table));
+  await client.query(postgresWebhookSchema(webhookTable));
+  await client.query(postgresRecordSchema(recordTable));
+}
+var wrapRecord = (value) => JSON.stringify({ flaghoistRecord: 1, value });
+function unwrapRecord(raw) {
+  let parsed = raw;
+  if (typeof raw === "string") {
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  if (parsed === null || typeof parsed !== "object") return null;
+  const envelope = parsed;
+  if (envelope.flaghoistRecord !== 1) return null;
+  return envelope.value ?? null;
 }
 function toFlag(value) {
   if (value == null) return null;
@@ -54,6 +79,8 @@ function toFlag(value) {
 }
 function postgresAdapter(client, options = {}) {
   const table = assertIdentifier(options.table ?? "flaghoist_flags");
+  const whTable = assertIdentifier(options.webhookTable ?? "flaghoist_webhooks");
+  const recTable = assertIdentifier(options.recordTable ?? "flaghoist_records");
   return {
     async get(key) {
       const { rows } = await client.query(`SELECT value FROM ${table} WHERE key = $1`, [key]);
@@ -78,6 +105,66 @@ function postgresAdapter(client, options = {}) {
         if (flag) flags.push(flag);
       }
       return flags;
+    },
+    async putWebhook(id, webhook) {
+      await client.query(
+        `INSERT INTO ${whTable} (id, value) VALUES ($1, $2::jsonb)
+         ON CONFLICT (id) DO UPDATE SET value = EXCLUDED.value`,
+        [id, JSON.stringify(webhook)]
+      );
+    },
+    async getWebhook(id) {
+      const { rows } = await client.query(`SELECT value FROM ${whTable} WHERE id = $1`, [id]);
+      const row = rows[0];
+      if (!row) return null;
+      return typeof row.value === "string" ? JSON.parse(row.value) : row.value;
+    },
+    async deleteWebhook(id) {
+      await client.query(`DELETE FROM ${whTable} WHERE id = $1`, [id]);
+    },
+    async listWebhooks() {
+      const { rows } = await client.query(`SELECT value FROM ${whTable}`);
+      return rows.map((row) => {
+        const v = row.value;
+        return typeof v === "string" ? JSON.parse(v) : v;
+      });
+    },
+    async getRecord(collection, id) {
+      (0, import_core.assertRecordAddress)(collection, id);
+      const { rows } = await client.query(
+        `SELECT value FROM ${recTable} WHERE collection = $1 AND id = $2`,
+        [collection, id]
+      );
+      const row = rows[0];
+      return row ? unwrapRecord(row.value) : null;
+    },
+    async putRecord(collection, id, value) {
+      (0, import_core.assertRecordAddress)(collection, id);
+      await client.query(
+        `INSERT INTO ${recTable} (collection, id, value) VALUES ($1, $2, $3::jsonb)
+         ON CONFLICT (collection, id) DO UPDATE SET value = EXCLUDED.value`,
+        [collection, id, wrapRecord(value)]
+      );
+    },
+    async deleteRecord(collection, id) {
+      (0, import_core.assertRecordAddress)(collection, id);
+      await client.query(`DELETE FROM ${recTable} WHERE collection = $1 AND id = $2`, [
+        collection,
+        id
+      ]);
+    },
+    async listRecords(collection) {
+      (0, import_core.assertRecordAddress)(collection);
+      const { rows } = await client.query(
+        `SELECT id, value FROM ${recTable} WHERE collection = $1`,
+        [collection]
+      );
+      const entries = [];
+      for (const row of rows) {
+        const value = unwrapRecord(row.value);
+        if (value !== null) entries.push({ id: row.id, value });
+      }
+      return entries;
     }
   };
 }
@@ -85,5 +172,7 @@ function postgresAdapter(client, options = {}) {
 0 && (module.exports = {
   initPostgres,
   postgresAdapter,
-  postgresSchema
+  postgresRecordSchema,
+  postgresSchema,
+  postgresWebhookSchema
 });

package/dist/index.d.cts

@@ -12,11 +12,19 @@ interface PgQueryable {
 interface PostgresAdapterOptions {
     /** Table name. Must be a plain SQL identifier. Default: `"flaghoist_flags"`. */
     table?: string;
+    /** Webhook table name. Must be a plain SQL identifier. Default: `"flaghoist_webhooks"`. */
+    webhookTable?: string;
+    /** Record-store table name. Must be a plain SQL identifier. Default: `"flaghoist_records"`. */
+    recordTable?: string;
 }
 /** SQL that creates the flags table. Run once (or via `initPostgres`). */
 declare function postgresSchema(table?: string): string;
-/** Create the flags table if it does not already exist. */
-declare function initPostgres(client: PgQueryable, table?: string): Promise<void>;
+/** SQL that creates the webhooks table. */
+declare function postgresWebhookSchema(table?: string): string;
+/** SQL that creates the record-store table. */
+declare function postgresRecordSchema(table?: string): string;
+/** Create the flags, webhooks and record-store tables if they do not already exist. */
+declare function initPostgres(client: PgQueryable, table?: string, webhookTable?: string, recordTable?: string): Promise<void>;
 /**
  * A StorageAdapter backed by Postgres. Flags live in a `jsonb` table keyed by flag key. All
  * queries are parameterized; every read is re-validated through `parseFlag`, so corrupt rows
@@ -24,4 +32,4 @@ declare function initPostgres(client: PgQueryable, table?: string): Promise<void
  */
 declare function postgresAdapter(client: PgQueryable, options?: PostgresAdapterOptions): StorageAdapter;
 
-export { type PgQueryable, type PostgresAdapterOptions, initPostgres, postgresAdapter, postgresSchema };
+export { type PgQueryable, type PostgresAdapterOptions, initPostgres, postgresAdapter, postgresRecordSchema, postgresSchema, postgresWebhookSchema };

package/dist/index.d.ts

@@ -12,11 +12,19 @@ interface PgQueryable {
 interface PostgresAdapterOptions {
     /** Table name. Must be a plain SQL identifier. Default: `"flaghoist_flags"`. */
     table?: string;
+    /** Webhook table name. Must be a plain SQL identifier. Default: `"flaghoist_webhooks"`. */
+    webhookTable?: string;
+    /** Record-store table name. Must be a plain SQL identifier. Default: `"flaghoist_records"`. */
+    recordTable?: string;
 }
 /** SQL that creates the flags table. Run once (or via `initPostgres`). */
 declare function postgresSchema(table?: string): string;
-/** Create the flags table if it does not already exist. */
-declare function initPostgres(client: PgQueryable, table?: string): Promise<void>;
+/** SQL that creates the webhooks table. */
+declare function postgresWebhookSchema(table?: string): string;
+/** SQL that creates the record-store table. */
+declare function postgresRecordSchema(table?: string): string;
+/** Create the flags, webhooks and record-store tables if they do not already exist. */
+declare function initPostgres(client: PgQueryable, table?: string, webhookTable?: string, recordTable?: string): Promise<void>;
 /**
  * A StorageAdapter backed by Postgres. Flags live in a `jsonb` table keyed by flag key. All
  * queries are parameterized; every read is re-validated through `parseFlag`, so corrupt rows
@@ -24,4 +32,4 @@ declare function initPostgres(client: PgQueryable, table?: string): Promise<void
  */
 declare function postgresAdapter(client: PgQueryable, options?: PostgresAdapterOptions): StorageAdapter;
 
-export { type PgQueryable, type PostgresAdapterOptions, initPostgres, postgresAdapter, postgresSchema };
+export { type PgQueryable, type PostgresAdapterOptions, initPostgres, postgresAdapter, postgresRecordSchema, postgresSchema, postgresWebhookSchema };

package/dist/index.js

@@ -1,5 +1,8 @@
 // src/index.ts
-import { parseFlag } from "@flaghoist/core";
+import {
+  assertRecordAddress,
+  parseFlag
+} from "@flaghoist/core";
 var IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function assertIdentifier(name) {
   if (!IDENTIFIER.test(name)) {
@@ -12,8 +15,31 @@ function assertIdentifier(name) {
 function postgresSchema(table = "flaghoist_flags") {
   return `CREATE TABLE IF NOT EXISTS ${assertIdentifier(table)} (key text PRIMARY KEY, value jsonb NOT NULL)`;
 }
-async function initPostgres(client, table = "flaghoist_flags") {
+function postgresWebhookSchema(table = "flaghoist_webhooks") {
+  return `CREATE TABLE IF NOT EXISTS ${assertIdentifier(table)} (id text PRIMARY KEY, value jsonb NOT NULL)`;
+}
+function postgresRecordSchema(table = "flaghoist_records") {
+  return `CREATE TABLE IF NOT EXISTS ${assertIdentifier(table)} (collection text NOT NULL, id text NOT NULL, value jsonb NOT NULL, PRIMARY KEY (collection, id))`;
+}
+async function initPostgres(client, table = "flaghoist_flags", webhookTable = "flaghoist_webhooks", recordTable = "flaghoist_records") {
   await client.query(postgresSchema(table));
+  await client.query(postgresWebhookSchema(webhookTable));
+  await client.query(postgresRecordSchema(recordTable));
+}
+var wrapRecord = (value) => JSON.stringify({ flaghoistRecord: 1, value });
+function unwrapRecord(raw) {
+  let parsed = raw;
+  if (typeof raw === "string") {
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  if (parsed === null || typeof parsed !== "object") return null;
+  const envelope = parsed;
+  if (envelope.flaghoistRecord !== 1) return null;
+  return envelope.value ?? null;
 }
 function toFlag(value) {
   if (value == null) return null;
@@ -28,6 +54,8 @@ function toFlag(value) {
 }
 function postgresAdapter(client, options = {}) {
   const table = assertIdentifier(options.table ?? "flaghoist_flags");
+  const whTable = assertIdentifier(options.webhookTable ?? "flaghoist_webhooks");
+  const recTable = assertIdentifier(options.recordTable ?? "flaghoist_records");
   return {
     async get(key) {
       const { rows } = await client.query(`SELECT value FROM ${table} WHERE key = $1`, [key]);
@@ -52,11 +80,73 @@ function postgresAdapter(client, options = {}) {
         if (flag) flags.push(flag);
       }
       return flags;
+    },
+    async putWebhook(id, webhook) {
+      await client.query(
+        `INSERT INTO ${whTable} (id, value) VALUES ($1, $2::jsonb)
+         ON CONFLICT (id) DO UPDATE SET value = EXCLUDED.value`,
+        [id, JSON.stringify(webhook)]
+      );
+    },
+    async getWebhook(id) {
+      const { rows } = await client.query(`SELECT value FROM ${whTable} WHERE id = $1`, [id]);
+      const row = rows[0];
+      if (!row) return null;
+      return typeof row.value === "string" ? JSON.parse(row.value) : row.value;
+    },
+    async deleteWebhook(id) {
+      await client.query(`DELETE FROM ${whTable} WHERE id = $1`, [id]);
+    },
+    async listWebhooks() {
+      const { rows } = await client.query(`SELECT value FROM ${whTable}`);
+      return rows.map((row) => {
+        const v = row.value;
+        return typeof v === "string" ? JSON.parse(v) : v;
+      });
+    },
+    async getRecord(collection, id) {
+      assertRecordAddress(collection, id);
+      const { rows } = await client.query(
+        `SELECT value FROM ${recTable} WHERE collection = $1 AND id = $2`,
+        [collection, id]
+      );
+      const row = rows[0];
+      return row ? unwrapRecord(row.value) : null;
+    },
+    async putRecord(collection, id, value) {
+      assertRecordAddress(collection, id);
+      await client.query(
+        `INSERT INTO ${recTable} (collection, id, value) VALUES ($1, $2, $3::jsonb)
+         ON CONFLICT (collection, id) DO UPDATE SET value = EXCLUDED.value`,
+        [collection, id, wrapRecord(value)]
+      );
+    },
+    async deleteRecord(collection, id) {
+      assertRecordAddress(collection, id);
+      await client.query(`DELETE FROM ${recTable} WHERE collection = $1 AND id = $2`, [
+        collection,
+        id
+      ]);
+    },
+    async listRecords(collection) {
+      assertRecordAddress(collection);
+      const { rows } = await client.query(
+        `SELECT id, value FROM ${recTable} WHERE collection = $1`,
+        [collection]
+      );
+      const entries = [];
+      for (const row of rows) {
+        const value = unwrapRecord(row.value);
+        if (value !== null) entries.push({ id: row.id, value });
+      }
+      return entries;
     }
   };
 }
 export {
   initPostgres,
   postgresAdapter,
-  postgresSchema
+  postgresRecordSchema,
+  postgresSchema,
+  postgresWebhookSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaghoist/adapter-postgres",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Postgres StorageAdapter for Flaghoist — stores flags in a jsonb table via any node-postgres client.",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@flaghoist/core": "0.1.2"
+    "@flaghoist/core": "0.2.0"
   },
   "devDependencies": {
     "pg-mem": "^3.0.14",