@lde/search 0.7.0 → 0.8.0

package/README.md

@@ -309,18 +309,20 @@ unrepresentable; the port enforces them for everyone else (deployment
 An engine is **bound to the whole `SearchSchema` at construction** – like
 every other schema consumer (`projectGraph(quads, schema)`,
 `buildGraphQLSchema(schema)`): the adapter factory takes the deployment’s
-declaration together with each type’s physical location, so a query can never
-meet the wrong index, and deployment-level concerns (the label cache,
-cross-type search, facet batching) have one home. A search names its type per
+declaration, so a query can never meet the wrong index, and deployment-level
+concerns (the label cache, cross-type search, facet batching) have one home.
+Where each type physically lives is the **adapter’s** to decide – it derives a
+collection/index name from the type, by its own engine’s naming conventions,
+and a deployment only overrides that where it must. A search names its type per
 call. Because `searchSchema()` captures the declared types as a literal
 tuple, `search()` accepts **only the deployment’s own types** (a foreign type
 is a compile error) and returns facet/document keys typed by the type passed
 – no caller-side generics:
 
 ```ts
-const engine = createTypesenseSearchEngine(client, schema, {
-  collections: { Dataset: 'datasets', Person: 'people' }, // omitting one = type error
-});
+// No `collections`: each type reads the collection the adapter names it,
+// which is the one its writer builds. Pass `collections` only to override.
+const engine = createTypesenseSearchEngine(client, schema);
 
 const result = await engine.search(DATASET, query);
 result.facets.publisher; // typed: only DATASET’s facetable fields are keys

package/dist/adapter.d.ts

@@ -8,6 +8,7 @@
  */
 export { assertTypeInSchema, physicalFields, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, labelFieldOf, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
 export type { PhysicalFields } from './schema.js';
+export { physicalNameTokens } from './physical-name.js';
 export { filterOperatorFor, filterOperator, validateQuery, assertValidQuery, pageForOffset, } from './query.js';
 export type { FilterOperator, QueryIssue } from './query.js';
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/adapter.js

@@ -7,4 +7,5 @@
  * this; the main entry point carries that (small) authoring surface.
  */
 export { assertTypeInSchema, physicalFields, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, labelFieldOf, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { physicalNameTokens } from './physical-name.js';
 export { filterOperatorFor, filterOperator, validateQuery, assertValidQuery, pageForOffset, } from './query.js';

package/dist/physical-name.d.ts

@@ -0,0 +1,40 @@
+import type { SearchType } from './schema.js';
+/**
+ * The engine-neutral word tokens an adapter formats into the physical name of a
+ * {@link SearchType}’s container – a Typesense collection, an Elasticsearch or
+ * OpenSearch index: the type’s `name` split into words, lowercased, with the
+ * last word pluralized (`CreativeWork` → `['creative', 'works']`).
+ *
+ * Both engines document the same convention – name a container after the plural
+ * of what it holds – and differ only in how they join the words: Typesense
+ * snake_case (`blog_articles`), Elasticsearch/OpenSearch kebab-case
+ * (`blog-articles`). So the split and the inflection are shared here, and only
+ * the join and the engine’s own legality rules live in the adapter – which is
+ * why this returns tokens rather than a formatted name, and why it is spelled
+ * neutrally (‘container’, not ‘collection’ or ‘index’).
+ *
+ * Acronyms stay whole (`DCATDataset` → `['dcat', 'datasets']`, `TVSeries` →
+ * `['tv', 'series']`), which is why the split is hand-rolled rather than
+ * delegated to an inflector’s `underscore`/`tableize` – those split on every
+ * capital (`t_v_series`).
+ *
+ * Pluralization is a real inflector, so irregular and invariant nouns land the
+ * way the engines’ own docs write them (`Person` → `people`, `TVSeries` →
+ * `tv_series`, `Analysis` → `analyses`) rather than as the non-words regular
+ * rules produce (`serieses`, `analysises`). An already-plural name is
+ * idempotent (`People` → `people`).
+ *
+ * **Throws rather than name the wrong container.** Dropping what it cannot
+ * match is what lets `creative_work` tokenize like `CreativeWork`, but it would
+ * just as quietly turn `Café` into `['cafs']` and `Musée` into `['mus', 'es']`
+ * – a perfectly legal name for a container nobody meant. So a name is spellable
+ * only when it is ASCII words and word separators, and only when it leaves at
+ * least one word to name anything after; anything else throws here. This guard
+ * lives with the split it protects, not in each adapter: an adapter cannot
+ * derive a name without going through this function, so it cannot forget to
+ * check – and `SearchType.name` is otherwise unvalidated
+ * ({@link validateSearchType} rules on field names only). A deployment whose
+ * type name this cannot spell passes its adapter an explicit name instead.
+ */
+export declare function physicalNameTokens(searchType: SearchType): readonly string[];
+//# sourceMappingURL=physical-name.d.ts.map

package/dist/physical-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physical-name.d.ts","sourceRoot":"","sources":["../src/physical-name.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,CAiB5E"}

package/dist/physical-name.js

@@ -0,0 +1,72 @@
+import { pluralize } from 'inflection';
+/**
+ * The engine-neutral word tokens an adapter formats into the physical name of a
+ * {@link SearchType}’s container – a Typesense collection, an Elasticsearch or
+ * OpenSearch index: the type’s `name` split into words, lowercased, with the
+ * last word pluralized (`CreativeWork` → `['creative', 'works']`).
+ *
+ * Both engines document the same convention – name a container after the plural
+ * of what it holds – and differ only in how they join the words: Typesense
+ * snake_case (`blog_articles`), Elasticsearch/OpenSearch kebab-case
+ * (`blog-articles`). So the split and the inflection are shared here, and only
+ * the join and the engine’s own legality rules live in the adapter – which is
+ * why this returns tokens rather than a formatted name, and why it is spelled
+ * neutrally (‘container’, not ‘collection’ or ‘index’).
+ *
+ * Acronyms stay whole (`DCATDataset` → `['dcat', 'datasets']`, `TVSeries` →
+ * `['tv', 'series']`), which is why the split is hand-rolled rather than
+ * delegated to an inflector’s `underscore`/`tableize` – those split on every
+ * capital (`t_v_series`).
+ *
+ * Pluralization is a real inflector, so irregular and invariant nouns land the
+ * way the engines’ own docs write them (`Person` → `people`, `TVSeries` →
+ * `tv_series`, `Analysis` → `analyses`) rather than as the non-words regular
+ * rules produce (`serieses`, `analysises`). An already-plural name is
+ * idempotent (`People` → `people`).
+ *
+ * **Throws rather than name the wrong container.** Dropping what it cannot
+ * match is what lets `creative_work` tokenize like `CreativeWork`, but it would
+ * just as quietly turn `Café` into `['cafs']` and `Musée` into `['mus', 'es']`
+ * – a perfectly legal name for a container nobody meant. So a name is spellable
+ * only when it is ASCII words and word separators, and only when it leaves at
+ * least one word to name anything after; anything else throws here. This guard
+ * lives with the split it protects, not in each adapter: an adapter cannot
+ * derive a name without going through this function, so it cannot forget to
+ * check – and `SearchType.name` is otherwise unvalidated
+ * ({@link validateSearchType} rules on field names only). A deployment whose
+ * type name this cannot spell passes its adapter an explicit name instead.
+ */
+export function physicalNameTokens(searchType) {
+    const { name } = searchType;
+    if (!SPELLABLE_NAME.test(name)) {
+        throw new Error(`Cannot name search type “${name}”: a physical name is derived from the type’s name, and this one carries characters outside ASCII words and word separators – deriving would silently drop them and name the wrong container. Rename the type, or give the adapter an explicit name.`);
+    }
+    const tokens = (name.match(NAME_WORD_PATTERN) ?? []).map((word) => word.toLowerCase());
+    const last = tokens.at(-1);
+    if (last === undefined) {
+        throw new Error(`Cannot name search type “${name}”: its name carries no word to name a container after. Rename the type, or give the adapter an explicit name.`);
+    }
+    return [...tokens.slice(0, -1), pluralize(last)];
+}
+/**
+ * A name the split can spell without losing part of it: ASCII letters and
+ * digits, plus the separators a name may already be written with (`creative
+ * work`, `creative_work`, `creative-work` all tokenize like `CreativeWork`).
+ * Deliberately narrower than what {@link NAME_WORD_PATTERN} would tolerate –
+ * that one skips anything it does not match, which is precisely the silent
+ * mangling this rejects.
+ *
+ * Matches the empty name too, on purpose: nothing about it is *unspellable*,
+ * there is simply nothing to spell, which the no-word check below reports far
+ * better than a complaint about characters it does not carry.
+ */
+const SPELLABLE_NAME = /^[A-Za-z0-9 _-]*$/;
+/**
+ * One word of a PascalCase/camelCase name, in precedence order: a run of
+ * capitals not followed by a lowercase letter (an acronym – `DCAT` in
+ * `DCATDataset`, `TV` in `TVSeries`); a capital starting an ordinary word; or a
+ * lowercase run. Anything else (a separator, punctuation) matches nothing and
+ * is dropped, so a name already written as `creative_work` or `creative-work`
+ * tokenizes the same way.
+ */
+const NAME_WORD_PATTERN = /[A-Z]+(?![a-z])|[A-Z][a-z0-9]*|[a-z0-9]+/g;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Engine- and domain-agnostic core for RDF-backed search: a unified declarative field model (SearchField/SearchType/SearchSchema), a neutral query IR, the SearchEngine port with logical result types, and a streaming CONSTRUCT-to-document projection. Bakes in no engine, protocol, or domain.",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -40,6 +40,7 @@
     "@lde/text-normalization": "^0.1.1",
     "@rdfjs/types": "^2.0.1",
     "@tpluscode/rdf-ns-builders": "^5.0.0",
+    "inflection": "^3.0.2",
     "jsonld": "^9.0.0",
     "tslib": "^2.3.0"
   },