@geonosis/search 0.1.1

package/dist/index.js

@@ -0,0 +1,485 @@
+// src/conformance.ts
+import { assertRefuses, assertThat, ConformanceFailure } from "@geonosis/conformance";
+var A = "tenant_conformance_a";
+var B = "tenant_conformance_b";
+var twoExamples = (subject) => {
+  const [first, second] = subject.examples;
+  if (first === void 0 || second === void 0) {
+    throw new ConformanceFailure(
+      "this subject offers fewer than two examples, and the tenant wall is a claim about one tenant\u2019s document being invisible to another: supply two documents with different ids"
+    );
+  }
+  return [first, second];
+};
+var found = (hits, document) => hits.some((hit) => hit.id === document.id && hit.kind === document.kind);
+var anyFilter = (index) => {
+  const [name] = Object.keys(index.vocabulary.filters);
+  if (name === void 0) {
+    throw new ConformanceFailure(
+      "this index declares no filter at all, so nothing here can ask it for one it does not have \u2014 a vocabulary with no names is not a vocabulary"
+    );
+  }
+  return { name, values: index.vocabulary.filters[name] ?? [] };
+};
+var vocabularyConformance = (subject) => {
+  const [first] = twoExamples(subject);
+  return [
+    {
+      name: "a query inside the declared vocabulary is answered",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, async (index) => {
+          await index.index(first.document);
+          const page = await index.query(first.findableBy);
+          assertThat(
+            found(page.hits, first.document),
+            "a document this index took cannot be found by a word its own projection derives \u2014 every refusal this exam makes below would be an index that refuses everything"
+          );
+        });
+      }
+    },
+    {
+      name: "a filter this index never declared is refused",
+      run: async () => {
+        await subject.inTenant(
+          A,
+          (index) => assertRefuses(
+            () => index.query(first.findableBy, { filters: { conformance_unknown: "x" } }),
+            "a filter no vocabulary declares was answered rather than refused, and the empty answer it gives reads as a count of zero"
+          )
+        );
+      }
+    },
+    {
+      name: "a value that filter does not take is refused",
+      run: async () => {
+        await subject.inTenant(A, async (index) => {
+          const filter = anyFilter(index);
+          await assertRefuses(
+            () => index.query(first.findableBy, {
+              filters: { [filter.name]: "conformance_undeclared_value" }
+            }),
+            `"${filter.name}" takes ${[...filter.values].toSorted().join(", ")} and answered a value outside that list: publishing filter names without their values is how a caller filters for something nothing emits and reports the empty result as a count`
+          );
+        });
+      }
+    },
+    {
+      name: "an ordering this index never declared is refused",
+      run: async () => {
+        await subject.inTenant(
+          A,
+          (index) => assertRefuses(
+            () => index.query(first.findableBy, { order: "conformance_unknown" }),
+            "an ordering nobody declared was accepted, so the rows came back in whatever order the storage felt like and the page after them is unreachable"
+          )
+        );
+      }
+    },
+    {
+      name: "every filter it declares publishes the values it takes",
+      run: async () => {
+        await subject.inTenant(A, (index) => {
+          const empty = Object.entries(index.vocabulary.filters).filter(([, values]) => values.length === 0).map(([name]) => name);
+          assertThat(
+            empty.length === 0,
+            `${empty.join(", ")} is published as a filter with no values, which is exactly the catalog that gets asked for a value nothing emits`
+          );
+          return Promise.resolve();
+        });
+      }
+    }
+  ];
+};
+var derivedProjectionConformance = (subject) => {
+  const [first] = twoExamples(subject);
+  return [
+    {
+      name: "a document is findable by the text its projection derives",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, async (index) => {
+          await index.index(first.document);
+          assertThat(
+            found((await index.query(first.findableBy)).hits, first.document),
+            `a document indexed under "${first.findableBy}" cannot be found by it`
+          );
+        });
+      }
+    },
+    {
+      name: "and not by a value its projection never read",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, async (index) => {
+          await index.index(first.document);
+          const page = await index.query(first.notFindableBy);
+          assertThat(
+            !found(page.hits, first.document),
+            `"${first.notFindableBy}" is carried by the document and read by no projection, and it found the row: this index stored the record it was handed rather than the text its projection derives, so what is searchable is whatever each call site remembered to fill`
+          );
+        });
+      }
+    },
+    {
+      name: "indexing the same document again replaces the row rather than adding one",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, async (index) => {
+          await index.index(first.document);
+          await index.index(first.document);
+          const page = await index.query(first.findableBy);
+          assertThat(
+            page.hits.filter((hit) => hit.id === first.document.id).length === 1,
+            "the same document was indexed twice and is found twice: every edit of a document leaves another copy of it in the results"
+          );
+        });
+      }
+    },
+    {
+      name: "a retired document is not findable",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, async (index) => {
+          await index.index(first.document);
+          await index.retire({ id: first.document.id, kind: first.document.kind });
+          assertThat(
+            !found((await index.query(first.findableBy)).hits, first.document),
+            "a retired document is still in the results, so deleting something leaves it findable"
+          );
+        });
+      }
+    }
+  ];
+};
+var outsideOf = (subject) => {
+  const outside = subject.outsideAnySession;
+  if (typeof outside !== "function") {
+    throw new ConformanceFailure(
+      'this subject has no `outsideAnySession`, and "a read that names no tenant sees nothing" is a claim about what the policies alone let through: supply the index over a handle outside every session \u2014 or this claim is untested rather than passing'
+    );
+  }
+  return outside;
+};
+var tenantIsolationConformance = (subject) => {
+  const [first, second] = twoExamples(subject);
+  return [
+    {
+      name: "a tenant finds only its own documents",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, (index) => index.index(first.document));
+        await subject.inTenant(B, (index) => index.index(second.document));
+        const page = await subject.inTenant(A, (index) => index.query(second.findableBy));
+        assertThat(
+          !found(page.hits, second.document),
+          "a search inside one tenant returned a document another tenant indexed"
+        );
+      }
+    },
+    {
+      name: "a read that names no tenant finds nothing",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, (index) => index.index(first.document));
+        const page = await outsideOf(subject)((index) => index.query(first.findableBy));
+        assertThat(
+          page.hits.length === 0,
+          "a search outside every tenant session answered with rows: the wall defaults to visible, so a query that forgot its session reads the whole index"
+        );
+      }
+    },
+    {
+      name: "a tenant cannot retire another tenant\u2019s document",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, (index) => index.index(first.document));
+        await subject.inTenant(
+          B,
+          (index) => index.retire({ id: first.document.id, kind: first.document.kind })
+        );
+        const page = await subject.inTenant(A, (index) => index.query(first.findableBy));
+        assertThat(
+          found(page.hits, first.document),
+          "one tenant deleted another tenant\u2019s document: the isolation policy is on the read and not on the write"
+        );
+      }
+    }
+  ];
+};
+var searchConformance = (subject) => [
+  ...vocabularyConformance(subject),
+  ...derivedProjectionConformance(subject),
+  ...tenantIsolationConformance(subject)
+];
+
+// src/contract.ts
+var SearchRefusal = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SearchRefusal";
+  }
+};
+var NOT_ZERO = "an empty answer to this is not a count of zero \u2014 it is a question nothing could match, and it is refused rather than answered";
+var DEFAULT_LIMIT = 50;
+var readSearchQuery = (vocabulary, terms, options = {}) => {
+  const orderings = vocabulary.orderings;
+  const first = orderings[0];
+  if (first === void 0) {
+    throw new SearchRefusal(
+      "this index declares no ordering, and a page of results is a sequence: declare at least one, because unordered rows cannot be paged by their key at all"
+    );
+  }
+  const order = options.order ?? first;
+  if (!orderings.includes(order)) {
+    throw new SearchRefusal(
+      `"${order}" is not an ordering this index declares \u2014 it orders by ${[...orderings].toSorted().join(", ")}. ${NOT_ZERO}`
+    );
+  }
+  const filters = Object.entries(options.filters ?? {}).map(([name, value]) => {
+    const values = vocabulary.filters[name];
+    if (values === void 0) {
+      throw new SearchRefusal(
+        `"${name}" is not a filter this index declares \u2014 it filters by ${Object.keys(vocabulary.filters).toSorted().join(", ")}. ${NOT_ZERO}`
+      );
+    }
+    if (!values.includes(value)) {
+      throw new SearchRefusal(
+        `"${name}" takes ${[...values].toSorted().join(", ")}, and was asked for "${value}". ${NOT_ZERO}`
+      );
+    }
+    return { name, value };
+  });
+  return {
+    ...options.after === void 0 ? {} : { after: readCursor(options.after, { order, terms }) },
+    filters,
+    limit: options.limit ?? DEFAULT_LIMIT,
+    order,
+    terms
+  };
+};
+var encodeCursor = (key) => encodeURIComponent(JSON.stringify(key));
+var KEYS = ["at", "id", "kind", "order", "rank", "terms"];
+var parsed = (cursor) => {
+  let value;
+  try {
+    value = JSON.parse(decodeURIComponent(cursor));
+  } catch {
+    throw new SearchRefusal(
+      "this cursor was not minted by this index: a page is reached by the key of the row before it, and that key is not readable here"
+    );
+  }
+  if (typeof value !== "object" || value === null) {
+    throw new SearchRefusal("this cursor holds no key at all");
+  }
+  const held = value;
+  const missing = KEYS.filter((key) => held[key] === void 0);
+  if (missing.length > 0) {
+    throw new SearchRefusal(`this cursor is missing ${missing.join(", ")}`);
+  }
+  return held;
+};
+var readCursor = (cursor, asked) => {
+  const key = parsed(cursor);
+  if (key.terms !== asked.terms) {
+    throw new SearchRefusal(
+      `this cursor was minted for "${key.terms}" and the query asks "${asked.terms}": ranks are comparable only within one question, so the page after it would be another query's`
+    );
+  }
+  if (key.order !== asked.order) {
+    throw new SearchRefusal(
+      `this cursor was minted under the "${key.order}" ordering and the query asks for "${asked.order}"`
+    );
+  }
+  return key;
+};
+
+// src/provider/ddl.ts
+var SEARCH_INDEX_TABLE = "search_index";
+var MIGRATION_PLACEHOLDERS = {
+  opsSetting: "{{opsSetting}}",
+  tenantSetting: "{{tenantSetting}}"
+};
+var DEFAULT_OPS_VALUE = "on";
+var CUSTOM_SETTING = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
+var readSettings = (settings) => {
+  for (const named of ["opsSetting", "tenantSetting"]) {
+    const name = settings[named];
+    if (typeof name !== "string" || name === "") {
+      throw new SearchRefusal(
+        `${named} is required and has no default: the policies and the session that opens them have to agree on the name exactly, and only the consumer knows it`
+      );
+    }
+    if (!CUSTOM_SETTING.test(name)) {
+      throw new SearchRefusal(
+        `${named} is "${name}", and Postgres reads a parameter an application defines as \`prefix.name\` \u2014 anything else is rejected as unrecognised the first time a session sets it`
+      );
+    }
+  }
+  return { ...settings, opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE };
+};
+var quoted = (identifier) => `"${identifier}"`;
+var setting = (name) => `current_setting('${name}', true)`;
+var both = (predicate) => `using (${predicate}) with check (${predicate})`;
+var table = quoted(SEARCH_INDEX_TABLE);
+var searchIndexTable = (tenantSetting) => [
+  `create table if not exists ${table} (
+  "tenant_id" text not null default ${setting(tenantSetting)},
+  "kind" text not null,
+  "id" text not null,
+  "title" text not null,
+  "body" text not null,
+  "indexed_at" bigint not null,
+  "search" tsvector generated always as (to_tsvector('simple', regexp_replace(coalesce("title", '') || ' ' || coalesce("body", ''), '[^[:alnum:]]+', ' ', 'g'))) stored,
+  constraint "search_index_pkey" primary key ("tenant_id", "kind", "id")
+)`,
+  `create index if not exists "search_index_search_idx" on ${table} using gin ("search")`,
+  `create index if not exists "search_index_recent_idx" on ${table} ("tenant_id", "indexed_at" desc)`
+];
+var policy = (name, as, predicate) => [
+  `drop policy if exists ${quoted(name)} on ${table}`,
+  `create policy ${quoted(name)} on ${table} as ${as} for all ${both(predicate)}`
+];
+var searchIndexPolicies = (settings) => [
+  `alter table ${table} enable row level security`,
+  `alter table ${table} force row level security`,
+  ...policy(
+    "tenant_isolation",
+    "permissive",
+    `"tenant_id" = (select ${setting(settings.tenantSetting)})`
+  ),
+  ...policy(
+    "ops_maintenance",
+    "permissive",
+    `(select ${setting(settings.opsSetting)}) = '${settings.opsValue}'`
+  )
+];
+var renderMigrations = (settings) => [
+  { name: "0001_search_index.sql", statements: searchIndexTable(settings.tenantSetting) },
+  {
+    name: "0002_search_index_policies.sql",
+    statements: searchIndexPolicies({
+      ...settings,
+      opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE
+    })
+  }
+];
+var searchIndexMigrations = (settings) => renderMigrations(readSettings(settings));
+
+// src/provider/pg-fts.ts
+import { rowsOf } from "@geonosis/conformance";
+var TOKEN = /[\p{L}\p{N}]+/gu;
+var toTsQuery = (terms) => (terms.match(TOKEN) ?? []).map((token) => `${token.toLowerCase()}:*`).join(" & ");
+var table2 = `"${SEARCH_INDEX_TABLE}"`;
+var COLUMN_OF = { kind: '"kind"' };
+var ORDERINGS = ["relevance", "recent"];
+var pgFtsSearchIndex = ({
+  executor,
+  nowMs,
+  projections
+}) => {
+  const kinds = Object.keys(projections);
+  const vocabulary = {
+    filters: { kind: kinds },
+    kinds,
+    orderings: [...ORDERINGS]
+  };
+  const projectionFor = (kind) => {
+    const projection = projections[kind];
+    if (projection === void 0) {
+      throw new SearchRefusal(
+        `"${kind}" is not a kind this index has a projection for \u2014 it indexes ${kinds.toSorted().join(", ")}, and a document whose searchable text nothing derives would be stored unfindable`
+      );
+    }
+    return projection;
+  };
+  return {
+    index: async (document) => {
+      const projection = projectionFor(document.kind);
+      await executor.execute({
+        params: [
+          document.kind,
+          document.id,
+          projection.title(document.fields),
+          projection.body(document.fields),
+          nowMs()
+        ],
+        text: `insert into ${table2} ("kind", "id", "title", "body", "indexed_at") values ($1, $2, $3, $4, $5) on conflict on constraint "search_index_pkey" do update set "title" = excluded."title", "body" = excluded."body", "indexed_at" = excluded."indexed_at"`
+      });
+    },
+    query: async (terms, options) => {
+      const read = readSearchQuery(vocabulary, terms, options);
+      const params = [];
+      const bind = (value) => {
+        params.push(value);
+        return `$${params.length}`;
+      };
+      const expression = toTsQuery(read.terms);
+      const matched = expression === "" ? void 0 : bind(expression);
+      const rank = matched === void 0 ? "0::real" : `ts_rank("search", to_tsquery('simple', ${matched}))`;
+      const where = matched === void 0 ? [] : [`"search" @@ to_tsquery('simple', ${matched})`];
+      for (const filter of read.filters) {
+        const column = COLUMN_OF[filter.name];
+        if (column === void 0) {
+          throw new SearchRefusal(`"${filter.name}" is a filter no column of this index answers`);
+        }
+        where.push(`${column} = ${bind(filter.value)}`);
+      }
+      const recent = read.order === "recent";
+      const key = recent ? '"indexed_at"' : rank;
+      const after = read.after;
+      if (after !== void 0) {
+        const head = recent ? `${bind(after.at)}::bigint` : `${bind(after.rank)}::real`;
+        where.push(`(${key}, "kind", "id") < (${head}, ${bind(after.kind)}, ${bind(after.id)})`);
+      }
+      const answer = await executor.execute({
+        params,
+        text: `select "kind", "id", "title", "indexed_at", ${rank} as "rank" from ${table2}${where.length === 0 ? "" : ` where ${where.join(" and ")}`} order by ${key} desc, "kind" desc, "id" desc limit ${bind(read.limit + 1)}`
+      });
+      const rows = rowsOf(answer);
+      const hits = rows.slice(0, read.limit).map((row) => ({
+        id: row.id,
+        indexedAt: Number(row.indexed_at),
+        kind: row.kind,
+        title: row.title
+      }));
+      const ended = rows[hits.length - 1];
+      return {
+        hits,
+        ...rows.length > read.limit && ended !== void 0 ? {
+          next: encodeCursor({
+            at: Number(ended.indexed_at),
+            id: ended.id,
+            kind: ended.kind,
+            order: read.order,
+            rank: Number(ended.rank),
+            terms: read.terms
+          })
+        } : {}
+      };
+    },
+    retire: async (document) => {
+      await executor.execute({
+        params: [document.kind, document.id],
+        text: `delete from ${table2} where "kind" = $1 and "id" = $2`
+      });
+    },
+    vocabulary
+  };
+};
+export {
+  DEFAULT_LIMIT,
+  DEFAULT_OPS_VALUE,
+  MIGRATION_PLACEHOLDERS,
+  SEARCH_INDEX_TABLE,
+  SearchRefusal,
+  derivedProjectionConformance,
+  encodeCursor,
+  pgFtsSearchIndex,
+  readCursor,
+  readSearchQuery,
+  searchConformance,
+  searchIndexMigrations,
+  tenantIsolationConformance,
+  vocabularyConformance
+};

package/migrations/0001_search_index.sql

@@ -0,0 +1,14 @@
+create table if not exists "search_index" (
+  "tenant_id" text not null default current_setting('{{tenantSetting}}', true),
+  "kind" text not null,
+  "id" text not null,
+  "title" text not null,
+  "body" text not null,
+  "indexed_at" bigint not null,
+  "search" tsvector generated always as (to_tsvector('simple', regexp_replace(coalesce("title", '') || ' ' || coalesce("body", ''), '[^[:alnum:]]+', ' ', 'g'))) stored,
+  constraint "search_index_pkey" primary key ("tenant_id", "kind", "id")
+);
+
+create index if not exists "search_index_search_idx" on "search_index" using gin ("search");
+
+create index if not exists "search_index_recent_idx" on "search_index" ("tenant_id", "indexed_at" desc);

package/migrations/0002_search_index_policies.sql

@@ -0,0 +1,11 @@
+alter table "search_index" enable row level security;
+
+alter table "search_index" force row level security;
+
+drop policy if exists "tenant_isolation" on "search_index";
+
+create policy "tenant_isolation" on "search_index" as permissive for all using ("tenant_id" = (select current_setting('{{tenantSetting}}', true))) with check ("tenant_id" = (select current_setting('{{tenantSetting}}', true)));
+
+drop policy if exists "ops_maintenance" on "search_index";
+
+create policy "ops_maintenance" on "search_index" as permissive for all using ((select current_setting('{{opsSetting}}', true)) = 'on') with check ((select current_setting('{{opsSetting}}', true)) = 'on');

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@geonosis/search",
+  "version": "0.1.1",
+  "types": "./dist/index.d.ts",
+  "description": "Full-text search as a domain: an index whose write path derives its own searchable projection, queries answered only inside a declared vocabulary with keyset cursors, and a Postgres provider that runs over an injected executor and ships its DDL as migrations.",
+  "keywords": [
+    "search",
+    "full-text",
+    "postgres",
+    "tsvector",
+    "keyset",
+    "multi-tenant"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/domains/search",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "domains/search"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "migrations"
+  ],
+  "dependencies": {
+    "@geonosis/conformance": "^0.2.0",
+    "@geonosis/db": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.15.5",
+    "embedded-postgres-17": "npm:embedded-postgres@17.10.0-beta.17",
+    "embedded-postgres-18": "npm:embedded-postgres@18.4.0-beta.17",
+    "pg": "^8.16.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}