feat: generator updates

packages/es-mapping-generator/package.json

@@ -5,8 +5,8 @@
   "type": "module",
   "license": "GPL-3.0-only",
   "author": "Thea Schöbl <dev@theaninova.de>",
-  "main": "./lib/index.js",
-  "types": "./lib/index.d.ts",
+  "main": "./src/index.js",
+  "types": "./src/types.d.ts",
   "files": [
     "app.js",
     "lib",
@@ -15,20 +15,19 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsup-node --dts",
     "format": "prettier . -c --ignore-path ../../.gitignore",
     "format:fix": "prettier --write . --ignore-path ../../.gitignore",
-    "lint": "eslint --ext .ts src/",
-    "lint:fix": "eslint --ext .ts src/",
+    "lint": "tsc --noEmit && eslint --ext .js src/",
+    "lint:fix": "eslint --ext .js src/",
     "test": "c8 mocha"
   },
   "dependencies": {
-    "ajv": "8.12.0",
-    "ajv-formats": "2.1.1",
     "@elastic/elasticsearch": "8.10.0",
     "@openstapps/json-schema-generator": "workspace:*",
     "@openstapps/tsup-plugin": "workspace:*",
-    "@types/json-schema": "7.0.14"
+    "@types/json-schema": "7.0.14",
+    "ajv": "8.12.0",
+    "ajv-formats": "2.1.1"
   },
   "devDependencies": {
     "@openstapps/eslint-config": "workspace:*",
@@ -47,7 +46,7 @@
     "mocha-junit-reporter": "2.2.0",
     "nock": "13.3.1",
     "ts-node": "10.9.1",
-    "tsup": "6.7.0",
+    "tsup": "7.2.0",
     "typedoc": "0.24.8",
     "typescript": "5.1.6"
   },

packages/es-mapping-generator/src/dsl/schema.ts

@@ -1,60 +0,0 @@
-import {MappingProperty, SearchRequest} from '@elastic/elasticsearch/lib/api/types.js';
-import Ajv from 'ajv';
-import {readFile} from 'fs/promises';
-import {fileURLToPath} from 'url';
-import path from 'path';
-import {Context} from '../generator/context.js';
-
-/**
- * @validatable
- */
-export interface ElasticsearchOptionsDSL {
-  /**
-   * Mark an interface as indexable
-   */
-  indexable?: true;
-  /**
-   * Inherit customization options from another item
-   */
-  extends?: string[];
-  /**
-   * Completely override the property
-   */
-  override?: MappingProperty;
-  /**
-   * Merge property values
-   */
-  merge?: MappingProperty;
-  /**
-   * Modify the search request
-   *
-   * Supports `{name}`, `{type}` and `{prop}` templates substitutions anywhere
-   */
-  search?: Partial<SearchRequest>;
-}
-
-const schema = JSON.parse(
-  await readFile(path.join(path.dirname(fileURLToPath(import.meta.url)), 'index.schema.json'), 'utf8'),
-);
-const ajv = new Ajv.default({schemas: [schema], allowUnionTypes: true});
-
-/**
- * Validate that the options are valid
- */
-export function validateElasticsearchOptionsDsl(
-  context: Context,
-  value: unknown,
-): value is ElasticsearchOptionsDSL {
-  return ajv.validate('#/definitions/ElasticsearchOptionsDSL', value)
-    ? true
-    : context.bail(JSON.stringify(ajv.errors));
-}
-
-/**
- * Validate that the mapping result is correct
- */
-export function validateMappingResult(context: Context, value: unknown): value is MappingProperty {
-  return ajv.validate('#/definitions/MappingProperty', value)
-    ? true
-    : context.bail(JSON.stringify(ajv.errors));
-}

packages/es-mapping-generator/src/generator/base.js

@@ -1,22 +1,24 @@
-import {JSONSchema7} from 'json-schema';
-import {MappingProperty} from '@elastic/elasticsearch/lib/api/types.js';
 import {transformObject} from './transformers/object.js';
 import {transformString} from './transformers/string.js';
-import {Context} from './context.js';
 import {transformDefinition} from './definition.js';
 
 /**
  * Transform JSONSchema without applying custom tag logic
+ * @typedef {import('json-schema').JSONSchema7} JSONSchema
+ *
+ * @param context {import('./context.js').Context}
+ * @param definition {JSONSchema}
+ * @returns {import('../types.js').MappingProperty}
  */
-export function transformBase(context: Context, definition: JSONSchema7): MappingProperty {
+export function transformBase(context, definition) {
   if (definition.anyOf) {
-    return context.resolveUnion(definition.anyOf as JSONSchema7[]);
+    return context.resolveUnion(/** @type {JSONSchema[]} */ (definition.anyOf));
   }
 
   switch (definition.type) {
     case 'array': {
       if (Array.isArray(definition.items)) {
-        return context.resolveUnion(definition.items as JSONSchema7[]);
+        return context.resolveUnion(/** @type {JSONSchema[]} */ (definition.items));
       } else if (typeof definition.items === 'object') {
         return transformDefinition(context, definition.items);
       } else {

packages/es-mapping-generator/src/generator/context.js

@@ -0,0 +1,159 @@
+import {transformDefinition} from './definition.js';
+import crypto from 'crypto';
+import deepmerge from 'deepmerge';
+import {sanitizeTypeName} from './mapping-generator.js';
+import {renderTemplate} from '../template.js';
+
+/**
+ * Get the name from a $ref such as `#/definitions/SCThing`
+ * @param ref {string}
+ * @returns {string}
+ */
+function getNameFromRef(ref) {
+  return decodeURI(ref).replace(/^#\/definitions\//, '');
+}
+
+/**
+ * @typedef {import('@elastic/elasticsearch/lib/api/types.d.ts').MappingProperty} MappingProperty
+ * @typedef {import('@elastic/elasticsearch/lib/api/types.d.ts').MappingDynamicProperty} MappingDynamicProperty
+ * @typedef {import('@elastic/elasticsearch/lib/api/types.d.ts').SearchRequest} SearchRequest
+ * @typedef {import('json-schema').JSONSchema7} JSONSchema
+ *
+ *
+ * @property {string} thingType
+ * @property {string[]} path
+ * @property {string[]} propertyPath
+ * @property {Map<string, Set<string>>} dependencies
+ */
+export class Context {
+  /**
+   * @param generator {import('./mapping-generator.js').MappingGenerator}
+   * @param thingType {string}
+   * @param path {string[]}
+   * @param propertyPath {string[]}
+   * @param dependencies {Map<string, Set<string>>}
+   */
+  constructor(generator, thingType, path, propertyPath, dependencies) {
+    this.generator = generator;
+    this.thingType = thingType;
+    this.path = path;
+    this.propertyPath = propertyPath;
+    this.dependencies = dependencies;
+  }
+
+  /**
+   * @param reference {string}
+   * @returns {MappingProperty}
+   */
+  resolveReference(reference) {
+    return this.deriveContext(reference)[1];
+  }
+
+  /**
+   * @param types {JSONSchema[]}
+   * @returns {MappingDynamicProperty}
+   */
+  resolveUnion(types) {
+    for (const type of types) {
+      const [name] = this.deriveContext(type.$ref ?? type);
+      this.addDependency(name, this.propertyPath.join('.'));
+    }
+
+    return {
+      type: '{dynamic_property}',
+    };
+  }
+
+  /**
+   * @private
+   * @param reference {string | JSONSchema}
+   * @returns {[dependency: string, mapping: MappingProperty]}
+   */
+  deriveContext(reference) {
+    let referenceName = typeof reference === 'string' ? getNameFromRef(reference) : undefined;
+    if (referenceName === undefined) this.bail(`Can't find reference name for ${reference}`);
+    let definition = /** @type {JSONSchema} */ (typeof reference === 'string' ? undefined : reference);
+
+    if (!definition && !this.generator.cache.has(referenceName)) {
+      const reference = this.generator.project.definitions[referenceName];
+      if (typeof reference === 'boolean') this.bail('Invalid schema');
+      definition = reference;
+      if (typeof definition !== 'object') this.bail(`Invalid path ${referenceName}`);
+    }
+
+    if (!referenceName || !this.generator.cache.has(referenceName)) {
+      const derivedContext = new Context(
+        this.generator,
+        this.thingType,
+        referenceName ? [referenceName] : [],
+        this.propertyPath,
+        new Map(),
+      );
+      const result = transformDefinition(derivedContext, definition);
+      referenceName ??= crypto.createHash('md5').update(JSON.stringify(result)).digest('hex');
+
+      this.generator.cache.set(referenceName, {mapping: result, dependencies: derivedContext.dependencies});
+    }
+
+    const cached = this.generator.cache.get(referenceName);
+    if (!cached) this.bail('Internal error');
+    for (const [name, paths] of cached.dependencies) {
+      for (const path of paths) {
+        this.addDependency(name, [...this.propertyPath.slice(0, -1), path].join('.'));
+      }
+    }
+    return [referenceName, cached.mapping];
+  }
+
+  /**
+   * @param modification {Partial<SearchRequest>}
+   */
+  registerSearchMod(modification) {
+    this.generator.searchMods.mods = deepmerge(
+      this.generator.searchMods.mods,
+      renderTemplate(modification, [
+        ['{name}', this.path[0]],
+        ['{prop}', this.propertyPath.join('.')],
+        ['{type}', this.thingType],
+        ['{_type}', sanitizeTypeName(this.thingType)],
+      ]),
+    );
+  }
+
+  /**
+   * @private
+   * @param name {string}
+   * @param path {string}
+   */
+  addDependency(name, path) {
+    if (!this.dependencies.has(name)) {
+      this.dependencies.set(name, new Set([path]));
+    } else {
+      this.dependencies.get(name)?.add(path);
+    }
+  }
+
+  /**
+   * Step down into a property
+   * @param property {string}
+   * @returns {Context}
+   */
+  step(property) {
+    return new Context(
+      this.generator,
+      this.thingType,
+      [...this.path, property],
+      [...this.propertyPath, property],
+      this.dependencies,
+    );
+  }
+
+  /**
+   * Bail and throw
+   * @param reason {string}
+   * @returns {never}
+   */
+  bail(reason) {
+    throw new Error(`${this.path.join('.')} ${reason}`);
+  }
+}

packages/es-mapping-generator/src/generator/context.ts

@@ -1,115 +0,0 @@
-import {JSONSchema7} from 'json-schema';
-import {transformDefinition} from './definition.js';
-import crypto from 'crypto';
-import {
-  MappingProperty,
-  MappingDynamicProperty,
-  SearchRequest,
-} from '@elastic/elasticsearch/lib/api/types.js';
-import deepmerge from 'deepmerge';
-import {MappingGenerator, sanitizeTypeName} from './mapping-generator.js';
-import {renderTemplate} from '../template.js';
-
-/**
- * Get the name from a $ref such as `#/definitions/SCThing`
- */
-function getNameFromRef(ref: string): string {
-  return decodeURI(ref).replace(/^#\/definitions\//, '');
-}
-
-export class Context {
-  constructor(
-    readonly generator: MappingGenerator,
-    readonly thingType: string,
-    readonly path: string[],
-    readonly propertyPath: string[],
-    readonly dependencies: Map<string, Set<string>>,
-  ) {}
-
-  resolveReference(reference: string): MappingProperty {
-    return this.deriveContext(reference)[1];
-  }
-
-  resolveUnion(types: JSONSchema7[]): MappingDynamicProperty {
-    for (const type of types) {
-      const [name] = this.deriveContext(type.$ref ?? type);
-      this.addDependency(name, this.propertyPath.join('.'));
-    }
-
-    return {
-      type: '{dynamic_property}',
-    };
-  }
-
-  private deriveContext(reference: string | JSONSchema7): [dependencyName: string, mapping: MappingProperty] {
-    let referenceName = typeof reference === 'string' ? getNameFromRef(reference) : undefined;
-    let definition = typeof reference === 'string' ? undefined : reference;
-
-    if (!definition && !this.generator.cache.has(referenceName!)) {
-      definition = this.generator.project.definitions![referenceName!] as JSONSchema7;
-      if (typeof definition !== 'object') this.bail(`Invalid path ${referenceName!}`);
-    }
-
-    if (!referenceName || !this.generator.cache.has(referenceName)) {
-      const derivedContext = new Context(
-        this.generator,
-        this.thingType,
-        referenceName ? [referenceName] : [],
-        this.propertyPath,
-        new Map(),
-      );
-      const result = transformDefinition(derivedContext, definition!);
-      referenceName ??= crypto.createHash('md5').update(JSON.stringify(result)).digest('hex');
-
-      this.generator.cache.set(referenceName, {mapping: result, dependencies: derivedContext.dependencies});
-    }
-
-    const {mapping, dependencies} = this.generator.cache.get(referenceName)!;
-    for (const [name, paths] of dependencies) {
-      for (const path of paths) {
-        this.addDependency(name, [...this.propertyPath.slice(0, -1), path].join('.'));
-      }
-    }
-    return [referenceName, mapping];
-  }
-
-  registerSearchMod(modification: Partial<SearchRequest>) {
-    this.generator.searchMods.mods = deepmerge<Partial<SearchRequest>>(
-      this.generator.searchMods.mods,
-      renderTemplate(modification, [
-        ['{name}', this.path[0]],
-        ['{prop}', this.propertyPath.join('.')],
-        ['{type}', this.thingType],
-        ['{_type}', sanitizeTypeName(this.thingType)],
-      ]),
-    );
-  }
-
-  private addDependency(name: string, path: string) {
-    if (!this.dependencies.has(name)) {
-      this.dependencies.set(name, new Set([path]));
-    } else {
-      this.dependencies.get(name)!.add(path);
-    }
-  }
-
-  /**
-   * Step down into a property
-   */
-  step(property: string): Context {
-    return new Context(
-      this.generator,
-      this.thingType,
-      [...this.path, property],
-      [...this.propertyPath, property],
-      this.dependencies,
-    );
-  }
-
-  /**
-   * Bail and throw
-   */
-  bail(reason: string): never {
-    throw new Error(`${this.path.join('.')} ${reason}`);
-  }
-}

packages/es-mapping-generator/src/generator/definition.js

@@ -1,27 +1,29 @@
-import {JSONSchema7} from 'json-schema';
-import {MappingProperty} from '@elastic/elasticsearch/lib/api/types.js';
 import {transformBase} from './base.js';
 import {Context} from './context.js';
 import deepmerge from 'deepmerge';
-import {resolveDsl} from './dsl.js';
+import {resolveOptions} from './options.js';
 import {getTags, INDEXABLE_TAG_NAME} from './tags.js';
 
 /**
  * Transform JSONSchema
+ * @typedef {import('../types.js').MappingProperty} MappingProperty
+ * @param context {Context}
+ * @param definition {import('json-schema').JSONSchema7}
+ * @returns {MappingProperty}
  */
-export function transformDefinition(context: Context, definition: JSONSchema7): MappingProperty {
+export function transformDefinition(context, definition) {
   if (definition.$ref) return context.resolveReference(definition.$ref);
   const tags = getTags(definition);
   tags.delete(INDEXABLE_TAG_NAME);
   let base = transformBase(context, definition);
 
   if (tags.size > 0) {
-    const options = resolveDsl(context, {extends: [...tags]});
+    const options = resolveOptions(context, {extends: [...tags]});
     if (options.override) {
       base = options.override;
     }
     if (options.merge) {
-      base = deepmerge<MappingProperty>(base, options.merge);
+      base = /** @type {typeof deepmerge<MappingProperty>} */ (deepmerge)(base, options.merge);
     }
     if (options.search) {
       context.registerSearchMod(options.search);

packages/es-mapping-generator/src/generator/index.js

@@ -1,34 +1,16 @@
-import type {JSONSchema7} from 'json-schema';
-import {ElasticsearchOptionsDSL} from '../dsl/schema.js';
-import {IndicesPutTemplateRequest, MappingProperty} from '@elastic/elasticsearch/lib/api/types.js';
 import {MappingGenerator} from './mapping-generator.js';
 import {getTags, INDEXABLE_TAG_NAME} from './tags.js';
-import {ElasticsearchConfig} from '../../schema/mappings.js';
-
-export interface GeneratorOptions {
-  /**
-   * Presets you can extend
-   */
-  presets: Record<string, ElasticsearchOptionsDSL>;
-  /**
-   * Override specific types
-   */
-  overrides: Record<string, MappingProperty>;
-  /**
-   * Template for the generated index request
-   *
-   * Supports `{type}` and `{sanitized_type}` (same as `{type}`, but no spaces) template substitutions
-   */
-  template: Partial<IndicesPutTemplateRequest>;
-}
 
 /**
  * Fully transform a project
+ * @param project {import('json-schema').JSONSchema7}
+ * @returns {import('../../schema/mappings.js').default}
  */
-export function transformProject(project: JSONSchema7): ElasticsearchConfig {
+export function transformProject(project) {
   const context = new MappingGenerator(project, OPTIONS);
 
-  const results: Record<string, IndicesPutTemplateRequest> = {};
+  /** @type {Record<string, import('../types.js').IndicesPutTemplateRequest>} */
+  const results = {};
   for (const name in project.definitions) {
     const definition = project.definitions[name];
     if (typeof definition !== 'object' || !getTags(definition).has(INDEXABLE_TAG_NAME)) continue;
@@ -42,7 +24,8 @@ export function transformProject(project: JSONSchema7): ElasticsearchConfig {
   };
 }
 
-const OPTIONS: GeneratorOptions = {
+/** @type {import('../types.js').GeneratorOptions} */
+const OPTIONS = {
   template: {
     name: 'template_{_type}',
     index_patterns: 'stapps_{_type}*',
@@ -132,7 +115,7 @@ const OPTIONS: GeneratorOptions = {
             language: 'de',
             country: 'DE',
             variant: '@collation=phonebook',
-          } as never,
+          },
         },
       },
     },

packages/es-mapping-generator/src/generator/mapping-generator.js

@@ -0,0 +1,88 @@
+import {Context} from './context.js';
+import deepmerge from 'deepmerge';
+import {renderTemplate} from '../template.js';
+
+/**
+ * Sanitize a type name
+ * @param typeName {string}
+ * @returns {string}
+ */
+export function sanitizeTypeName(typeName) {
+  return typeName.replaceAll(' ', '_');
+}
+
+/**
+ * @typedef {import('json-schema').JSONSchema7} JSONSchema
+ * @typedef {import('../types.js').MappingProperty} MappingProperty
+ * @typedef {import('../types.js').MappingTypeMapping} MappingTypeMapping
+ * @typedef {import('../types.js').IndicesPutTemplateRequest} IndicesPutTemplateRequest
+ * @typedef {import('../types.js').SearchRequest} SearchRequest
+ */
+export class MappingGenerator {
+  /** @type {Map<string, {mapping: MappingProperty; dependencies: Map<string, Set<string>>}>} */
+  cache;
+
+  /** @type {{mods: Partial<SearchRequest>}} */
+  searchMods = {mods: {}};
+
+  /**
+   * @param project {JSONSchema & Pick<Required<JSONSchema>, 'definitions'>}
+   * @param options {import('../types.js').GeneratorOptions}
+   */
+  constructor(project, options) {
+    if (!project.definitions) throw new Error('Invalid schema');
+    this.project = project;
+    this.template = options.template ?? {};
+    this.presets = new Map(Object.entries(options.presets));
+    this.cache = new Map(
+      Object.entries(options.overrides).map(([name, mapping]) => [
+        name,
+        {
+          mapping,
+          dependencies: new Map(),
+        },
+      ]),
+    );
+  }
+
+  /**
+   * @param name {string}
+   * @returns {[string, IndicesPutTemplateRequest]}
+   */
+  buildTemplate(name) {
+    const definition = this.project.definitions[name];
+    if (typeof definition === 'boolean' || !definition.properties) throw new Error('Invalid schema');
+    const thingTypeDefinition = definition.properties.type;
+    if (typeof thingTypeDefinition === 'boolean') throw new Error('Invalid schema');
+    const thingType = thingTypeDefinition.const;
+
+    if (typeof thingType !== 'string') {
+      throw new TypeError(`${name} needs a valid thing type`);
+    }
+    const mappingContext = new Context(this, thingType, [name], [], new Map());
+    const mappings = mappingContext.resolveReference(name);
+
+    const request = deepmerge(
+      {mappings: mappings},
+      renderTemplate(this.template, [
+        ['{name}', name],
+        ['{type}', thingType],
+        ['{_type}', sanitizeTypeName(thingType)],
+      ]),
+    );
+
+    if (mappingContext.dependencies.size > 0) {
+      request.mappings.dynamic_templates = [];
+      for (const [name, paths] of mappingContext.dependencies) {
+        request.mappings.dynamic_templates.push({
+          [name]: {
+            path_match: paths.size > 1 ? [...paths] : paths.values().next().value,
+            mapping: mappingContext.resolveReference(name),
+          },
+        });
+      }
+    }
+
+    return [thingType, request];
+  }
+}

packages/es-mapping-generator/src/generator/mapping-generator.ts

@@ -1,76 +0,0 @@
-import {GeneratorOptions} from './index.js';
-import {JSONSchema7} from 'json-schema';
-import {ElasticsearchOptionsDSL} from '../dsl/schema.js';
-import {
-  IndicesPutTemplateRequest,
-  MappingProperty,
-  MappingTypeMapping,
-  SearchRequest,
-} from '@elastic/elasticsearch/lib/api/types.js';
-import {Context} from './context.js';
-import deepmerge from 'deepmerge';
-import {renderTemplate} from '../template.js';
-
-/**
- * Sanitize a type name
- */
-export function sanitizeTypeName(typeName: string): string {
-  return typeName.replaceAll(' ', '_');
-}
-
-export class MappingGenerator {
-  readonly presets: Map<string, ElasticsearchOptionsDSL>;
-
-  readonly cache: Map<string, {mapping: MappingProperty; dependencies: Map<string, Set<string>>}>;
-
-  readonly searchMods: {mods: Partial<SearchRequest>} = {mods: {}};
-
-  readonly template: Partial<IndicesPutTemplateRequest>;
-
-  constructor(readonly project: JSONSchema7, options: GeneratorOptions) {
-    this.template = options.template ?? {};
-    this.presets = new Map(Object.entries(options.presets));
-    this.cache = new Map(
-      Object.entries(options.overrides).map(([name, mapping]) => [
-        name,
-        {
-          mapping,
-          dependencies: new Map(),
-        },
-      ]),
-    );
-  }
-
-  buildTemplate(name: string): [string, IndicesPutTemplateRequest] {
-    const thingType = ((this.project.definitions![name] as JSONSchema7).properties!.type as JSONSchema7)
-      .const;
-    if (typeof thingType !== 'string') {
-      throw new TypeError(`${name} needs a valid thing type`);
-    }
-    const mappingContext = new Context(this, thingType, [name], [], new Map());
-    const mappings = mappingContext.resolveReference(name);
-
-    const request: IndicesPutTemplateRequest = deepmerge(
-      {mappings: mappings as MappingTypeMapping},
-      renderTemplate(this.template, [
-        ['{name}', name],
-        ['{type}', thingType],
-        ['{_type}', sanitizeTypeName(thingType)],
-      ]),
-    );
-
-    if (mappingContext.dependencies.size > 0) {
-      request.mappings!.dynamic_templates = [];
-      for (const [name, paths] of mappingContext.dependencies) {
-        request.mappings!.dynamic_templates.push({
-          [name]: {
-            path_match: paths.size > 1 ? [...paths] : paths.values().next().value,
-            mapping: mappingContext.resolveReference(name),
-          },
-        });
-      }
-    }
-
-    return [thingType, request];
-  }
-}

packages/es-mapping-generator/src/generator/options.js

@@ -1,18 +1,15 @@
 import {Context} from './context.js';
-import {ElasticsearchOptionsDSL} from '../dsl/schema.js';
 import deepmerge from 'deepmerge';
 
-type ResolvedOptions = Omit<ElasticsearchOptionsDSL, 'extends'>;
-
 /**
- * Resolve DSL inheritance
+ * Resolve option inheritance
+ * @param context {Context}
+ * @param options {import('../types.js').ElasticsearchOptions}
+ * @returns {import('../types.js').ResolvedOptions}
  */
-export function resolveDsl(
-  context: Context,
-  {extends: parents, ...result}: ElasticsearchOptionsDSL,
-): ResolvedOptions {
+export function resolveOptions(context, {extends: parents, ...result}) {
   for (const reference of parents ?? []) {
-    result = deepmerge<ResolvedOptions>(
+    result = deepmerge(
       result,
       reference.startsWith('@')
         ? resolveReferencePath(context, reference)
@@ -25,20 +22,27 @@ export function resolveDsl(
 
 /**
  * Resolve preset references
+ * @param context {Context}
+ * @param reference {string}
+ * @returns {import('../types.js').ResolvedOptions}
  */
-function resolvePresetReference(context: Context, reference: string): ResolvedOptions {
+function resolvePresetReference(context, reference) {
   if (!context.generator.presets.has(reference)) return context.bail(`Missing preset ${reference}`);
-  return resolveDsl(context, context.generator.presets.get(reference)!);
+  return resolveOptions(context, context.generator.presets.get(reference));
 }
 
 /**
  * Resolve @references
+ * @param context {Context}
+ * @param reference {string}
+ * @returns {import('../types.js').ResolvedOptions}
  */
-function resolveReferencePath(context: Context, reference: string): ResolvedOptions {
+function resolveReferencePath(context, reference) {
   const [type, ...path] = reference.replace(/^@/, '').split('.');
   let declaration = context.resolveReference(type);
   while (path.length > 0) {
-    const property = path.shift()!;
+    const property = path.shift();
+    if (!property) context.bail('internal logic error');
     if (!('properties' in declaration && declaration.properties && property in declaration.properties))
       context.bail(`Invalid reference ${reference}`);
 

packages/es-mapping-generator/src/generator/tags.js

@@ -0,0 +1,14 @@
+export const INDEXABLE_TAG_NAME = 'indexable';
+
+/**
+ * Get elasticsearch tags
+ * @param definition {import('json-schema').JSONSchema7}
+ * @returns {Set<string>}
+ */
+export function getTags(definition) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return new Set(
+    /** @type {{elasticsearch?: string}} */ (definition).elasticsearch?.split(/\s/).map(it => it.trim()) ??
+      [],
+  );
+}

packages/es-mapping-generator/src/generator/tags.ts

@@ -1,13 +0,0 @@
-import {JSONSchema7} from 'json-schema';
-
-export const INDEXABLE_TAG_NAME = 'indexable';
-
-/**
- * Get elasticsearch tags
- */
-export function getTags(definition: JSONSchema7): Set<string> {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return new Set(
-    (definition as {elasticsearch: string}).elasticsearch?.split(/\s/).map(it => it.trim()) ?? [],
-  );
-}

packages/es-mapping-generator/src/generator/transformers/object.js

@@ -0,0 +1,27 @@
+import {transformDefinition} from '../definition.js';
+
+/**
+ * Transform a JSON Schema with `object` type
+ * @typedef {import('../../types.js').MappingProperty} MappingProperty
+ * @typedef {import('json-schema').JSONSchema7} JSONSchema
+ *
+ * @param context {import('../context.js').Context}
+ * @param definition {JSONSchema}
+ * @returns {MappingProperty}
+ */
+export function transformObject(context, definition) {
+  /** @satisfies {MappingProperty} */
+  const value = {
+    dynamic: definition.additionalProperties === true ? undefined : 'strict',
+    properties: /** @type {Record<string, MappingProperty>} */ ({}),
+  };
+
+  for (const key in definition.properties) {
+    value.properties[key] = transformDefinition(
+      context.step(key),
+      /** @type {JSONSchema} */ (definition.properties[key]),
+    );
+  }
+
+  return value;
+}

packages/es-mapping-generator/src/generator/transformers/object.ts

@@ -1,20 +0,0 @@
-import {JSONSchema7} from 'json-schema';
-import {MappingProperty} from '@elastic/elasticsearch/lib/api/types.js';
-import {transformDefinition} from '../definition.js';
-import {Context} from '../context.js';
-
-/**
- * Transform a JSON Schema with `object` type
- */
-export function transformObject(context: Context, definition: JSONSchema7): MappingProperty {
-  const value = {
-    dynamic: definition.additionalProperties === true ? undefined : 'strict',
-    properties: {} as Record<string, MappingProperty>,
-  } satisfies MappingProperty;
-
-  for (const key in definition.properties!) {
-    value.properties[key] = transformDefinition(context.step(key), definition.properties[key] as JSONSchema7);
-  }
-
-  return value;
-}

packages/es-mapping-generator/src/generator/transformers/string.js

@@ -1,7 +1,7 @@
-import {JSONSchema7} from 'json-schema';
-import {MappingProperty} from '@elastic/elasticsearch/lib/api/types.js';
-
-const stringFormats = new Map<string, MappingProperty>([
+/**
+ * @type {Map<string, import('../../types.js').MappingProperty>}
+ */
+const stringFormats = new Map([
   ['date', {type: 'date', format: 'date'}],
   ['time', {type: 'date', format: 'time'}],
   ['date-time', {type: 'date', format: 'date_optional_time'}],
@@ -11,9 +11,11 @@ const stringFormats = new Map<string, MappingProperty>([
 
 /**
  * Transform a JSON Schema with `string` type
+ * @param definition {import('json-schema').JSONSchema7}
+ * @returns {import('../../types.js').MappingProperty}
  */
-export function transformString(definition: JSONSchema7): MappingProperty {
+export function transformString(definition) {
   return definition.format && stringFormats.has(definition.format)
-    ? stringFormats.get(definition.format)!
+    ? stringFormats.get(definition.format) ?? {type: 'keyword'}
     : {type: 'keyword'};
 }

packages/es-mapping-generator/src/index.js

@@ -1,18 +1,19 @@
 import {transformProject} from './generator/index.js';
-import {SchemaConsumer} from '@openstapps/json-schema-generator';
 import {readFile} from 'fs/promises';
-import path from 'path';
+import {join, dirname} from 'path';
 import {fileURLToPath} from 'url';
 
 const mappingTypes = await readFile(
-  path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'schema', 'mappings.d.ts'),
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'schema', 'mappings.d.ts'),
   'utf8',
 );
 
 /**
  * JSON Schema Generator plugin for Elasticsearch Mappings
+ * @param fileName {string}
+ * @returns {[string, import('@openstapps/json-schema-generator').SchemaConsumer]}
  */
-export function elasticsearchMappingGenerator(fileName: string): [string, SchemaConsumer] {
+export function elasticsearchMappingGenerator(fileName) {
   return [
     'Elasticsearch-Mappings',
     function (schema) {

packages/es-mapping-generator/src/template.js

@@ -0,0 +1,15 @@
+/**
+ * Render a template
+ * @template T
+ * @param template {T} The template to render (must be stringify-able)
+ * @param substitutions {[string, string][]} the substitutions
+ * @returns {T}
+ */
+export function renderTemplate(template, substitutions) {
+  return JSON.parse(
+    substitutions.reduce(
+      (template, [search, replace]) => template.replaceAll(search, replace),
+      JSON.stringify(template),
+    ),
+  );
+}

packages/es-mapping-generator/src/template.ts

@@ -1,13 +0,0 @@
-/**
- * Render a template
- * @param template The template to render (must be stringify-able)
- * @param substitutions the substitutions
- */
-export function renderTemplate<T>(template: T, substitutions: [string, string][]): T {
-  return JSON.parse(
-    substitutions.reduce(
-      (template, [search, replace]) => template.replaceAll(search, replace),
-      JSON.stringify(template),
-    ),
-  );
-}

packages/es-mapping-generator/src/types.d.ts

@@ -0,0 +1,56 @@
+import {MappingProperty, SearchRequest} from '@elastic/elasticsearch/lib/api/types.d.ts';
+import {IndicesPutTemplateRequest} from '@elastic/elasticsearch/lib/api/types.js';
+
+export {
+  MappingProperty,
+  SearchRequest,
+  MappingDynamicProperty,
+  MappingTypeMapping,
+  IndicesPutTemplateRequest,
+} from '@elastic/elasticsearch/lib/api/types.d.ts';
+
+export interface ElasticsearchOptions {
+  /**
+   * Mark an interface as indexable
+   */
+  indexable?: true;
+  /**
+   * Inherit customization options from another item
+   */
+  extends?: string[];
+  /**
+   * Completely override the property
+   */
+  override?: MappingProperty;
+  /**
+   * Merge property values
+   */
+  merge?: MappingProperty;
+  /**
+   * Modify the search request
+   *
+   * Supports `{name}`, `{type}` and `{prop}` templates substitutions anywhere
+   */
+  search?: Partial<SearchRequest>;
+}
+
+export interface GeneratorOptions {
+  /**
+   * Presets you can extend
+   */
+  presets: Record<string, ElasticsearchOptionsDSL>;
+  /**
+   * Override specific types
+   */
+  overrides: Record<string, MappingProperty>;
+  /**
+   * Template for the generated index request
+   *
+   * Supports `{type}` and `{sanitized_type}` (same as `{type}`, but no spaces) template substitutions
+   */
+  template: Partial<IndicesPutTemplateRequest>;
+}
+
+export type ResolvedOptions = Omit<ElasticsearchOptions, 'extends'>;
+
+export {elasticsearchMappingGenerator} from './index.js';