Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,94 @@
/**
* Tenant-scoped index lifecycle helper.
*
* `createSearchIndex` is the only sanctioned way to register a new index
* with Meilisearch. It enforces the package-wide invariant: every index
* MUST list `tenantId` as a filterable attribute, otherwise tenant
* isolation cannot be guaranteed at read time.
*
* The helper is idempotent — calling it twice with the same schema is a
* no-op (settings are re-applied; existing documents stay put). Domain
* code is expected to call it during bootstrap before any indexing or
* search happens.
*/
import type { IndexHandle, IndexSettingsInput, SearchClient, SearchDocument } from "./client.js";
import type { SearchIndexSchema } from "./schemas/index.js";
export class IndexSchemaValidationError extends Error {
override readonly name = "IndexSchemaValidationError";
readonly code: "MISSING_TENANT_FILTER" | "EMPTY_PRIMARY_KEY" | "EMPTY_NAME" | "TENANT_FIELD_NOT_ALLOWED";
constructor(message: string, code: IndexSchemaValidationError["code"]) {
super(message);
this.code = code;
}
}
export function validateIndexSchema(schema: SearchIndexSchema): void {
if (!schema || typeof schema.name !== "string" || schema.name.length === 0) {
throw new IndexSchemaValidationError("Search index schema requires a non-empty name.", "EMPTY_NAME");
}
if (typeof schema.primaryKey !== "string" || schema.primaryKey.length === 0) {
throw new IndexSchemaValidationError(
`Search index "${schema.name}" must declare a non-empty primaryKey.`,
"EMPTY_PRIMARY_KEY"
);
}
if (!Array.isArray(schema.filterableAttributes) || !schema.filterableAttributes.includes("tenantId")) {
throw new IndexSchemaValidationError(
`Search index "${schema.name}" must list "tenantId" in filterableAttributes — tenant isolation depends on it.`,
"MISSING_TENANT_FILTER"
);
}
if (!schema.allowedDocumentFields.includes("tenantId")) {
throw new IndexSchemaValidationError(
`Search index "${schema.name}" must list "tenantId" in allowedDocumentFields so the sanitizer keeps it.`,
"TENANT_FIELD_NOT_ALLOWED"
);
}
}
export interface CreateSearchIndexInput {
readonly client: SearchClient;
readonly schema: SearchIndexSchema;
/** Optional overrides merged on top of the schema's settings. */
readonly settingsOverride?: Partial<IndexSettingsInput>;
}
export async function createSearchIndex<TDocument extends SearchDocument = SearchDocument>(
input: CreateSearchIndexInput
): Promise<IndexHandle<TDocument>> {
validateIndexSchema(input.schema);
const settings = mergeSettings(input.schema, input.settingsOverride);
const handle = input.client.index<TDocument>(input.schema.name);
await handle.ensure({ primaryKey: input.schema.primaryKey, settings });
return handle;
}
function mergeSettings(schema: SearchIndexSchema, override: Partial<IndexSettingsInput> | undefined): IndexSettingsInput {
const base: IndexSettingsInput = {
searchableAttributes: schema.searchableAttributes,
filterableAttributes: schema.filterableAttributes,
sortableAttributes: schema.sortableAttributes,
...(schema.rankingRules ? { rankingRules: schema.rankingRules } : {}),
...(schema.stopWords ? { stopWords: schema.stopWords } : {}),
...(schema.synonyms ? { synonyms: toMutableSynonyms(schema.synonyms) } : {}),
};
if (!override) return base;
return {
...base,
...(override.searchableAttributes ? { searchableAttributes: override.searchableAttributes } : {}),
...(override.filterableAttributes ? { filterableAttributes: override.filterableAttributes } : {}),
...(override.sortableAttributes ? { sortableAttributes: override.sortableAttributes } : {}),
...(override.rankingRules ? { rankingRules: override.rankingRules } : {}),
...(override.stopWords ? { stopWords: override.stopWords } : {}),
...(override.synonyms ? { synonyms: override.synonyms } : {}),
};
}
function toMutableSynonyms(synonyms: Record<string, readonly string[]>): Record<string, readonly string[]> {
const out: Record<string, readonly string[]> = {};
for (const key of Object.keys(synonyms)) out[key] = synonyms[key];
return out;
}