@programisto/edrm-search 1.0.0

package/.eslintrc.json

@@ -0,0 +1,13 @@
+{
+  "env": { "node": true, "es2021": true },
+  "extends": ["standard"],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": { "ecmaVersion": 12, "sourceType": "module" },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "semi": ["error", "always"],
+    "indent": "off",
+    "space-before-function-paren": "off"
+  },
+  "ignorePatterns": ["dist/", "node_modules/"]
+}

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [1.0.0] (unreleased)
+
+### Added
+
+- Initial release: EDRM Search module for Endurance.
+- Listener for `postSave` and `postDeleteOne` events to sync indexes with MongoDB collections.
+- OpenSearch provider (index, remove, search, ensureIndex).
+- Search service with configurable prefix and lazy index creation.
+- Adapter implementing `EnduranceSearchProvider` and registration via `EnduranceSearchMiddleware.setInstance()`.
+- Optional routes POST/GET `/search` (disabled by default via `EDRM_SEARCH_ROUTES_ENABLED`).
+- Support for `q`, `filter`, `sort`, `from`, `size`, and raw `body` in search options.

package/README.md

@@ -0,0 +1,66 @@
+# EDRM Search
+
+## Description
+
+EDRM Search is an Endurance module that provides full-text search via OpenSearch (or Elasticsearch). It listens to Endurance schema events (`postSave`, `postDeleteOne`) to keep search indexes in sync with MongoDB collections. Search is exposed through the **Endurance search middleware**, so other EDRM modules can call search without depending on edrm-search.
+
+## Features
+
+- Automatic index sync: documents are indexed on save and removed on delete.
+- One index per MongoDB collection (with optional prefix).
+- Search via **middleware**: use `EnduranceSearchMiddleware.getInstance().search(collection, options)` in any module.
+- Optional unified route `POST /search` (disabled by default; enable with `EDRM_SEARCH_ROUTES_ENABLED=true`).
+
+## Installation
+
+```bash
+npm install @programisto/edrm-search
+```
+
+## Requirements
+
+- **@programisto/endurance** ≥ 1.0.x (with `EnduranceSearchMiddleware` and `postSave` / `postDeleteOne` events)
+- Node.js ≥ 18
+- OpenSearch (or compatible) cluster
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+| -------- | -------- | ------- | ----------- |
+| `SEARCH_ENGINE_URL` | Yes (if search enabled) | - | OpenSearch/Elasticsearch cluster URL (e.g. `https://localhost:9200`) |
+| `SEARCH_ENGINE_ENABLED` | No | - | Set to `true` to enable indexing and the search provider |
+| `SEARCH_ENGINE_INDEX_PREFIX` | No | `''` | Prefix for index names (e.g. `app_` → `app_users`) |
+| `SEARCH_ENGINE_PROVIDER` | No | `opensearch` | `opensearch` or `elasticsearch` |
+| `SEARCH_ENGINE_USERNAME` | No | - | Basic auth username |
+| `SEARCH_ENGINE_PASSWORD` | No | - | Basic auth password |
+| `EDRM_SEARCH_ROUTES_ENABLED` | No | `false` | Set to `true` to enable the `/search` HTTP routes (disabled by default for security) |
+
+## Using search from another module (middleware)
+
+In any EDRM module, use the Endurance search middleware so you do not depend on edrm-search:
+
+```ts
+import { EnduranceSearchMiddleware } from '@programisto/endurance';
+
+// In a route handler:
+const provider = EnduranceSearchMiddleware.getInstance();
+if (provider.isSearchEnabled()) {
+  const result = await provider.search('users', { q: req.query.q, size: 20 });
+  res.json(result);
+} else {
+  // Fallback to Model.find() or other logic
+}
+```
+
+## Routes (when enabled)
+
+When `EDRM_SEARCH_ROUTES_ENABLED=true`:
+
+- **POST /search** – Body: `{ collection, q?, filter?, sort?, from?, size?, body? }`
+- **GET /search** – Query: `collection` (required), `q`, `filter`, `sort`, `from`, `size`
+
+By default these routes return **503** with `code: "SEARCH_ROUTES_DISABLED"` so that search is used only via the middleware from your modules.
+
+## Collection name convention
+
+If the document does not expose a collection name via `constructor.getModel().collection.name`, the listener derives it from the event name (e.g. `User:postSave` → collection `users`).

package/dist/bin/www.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin/www.js

@@ -0,0 +1,14 @@
+/// <reference types="node" />
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const localAppPath = path.join(__dirname, '../lib/app.js');
+const coreAppPath = path.join(__dirname, '../../node_modules/@programisto/endurance/dist/internal/app.js');
+if (fs.existsSync(localAppPath)) {
+    await import(localAppPath);
+}
+else {
+    await import(coreAppPath);
+}

package/dist/lib/opensearch-provider.d.ts

@@ -0,0 +1,2 @@
+import type { InternalSearchProvider } from './types.js';
+export declare function createOpenSearchProvider(): InternalSearchProvider;

package/dist/lib/opensearch-provider.js

@@ -0,0 +1,70 @@
+import { Client } from '@opensearch-project/opensearch';
+let clientInstance = null;
+function getClient() {
+    if (!clientInstance) {
+        const node = process.env.SEARCH_ENGINE_URL ?? '';
+        const clientConfig = { node };
+        const username = process.env.SEARCH_ENGINE_USERNAME;
+        const password = process.env.SEARCH_ENGINE_PASSWORD;
+        if (username && password) {
+            clientConfig.auth = { username, password };
+        }
+        clientInstance = new Client(clientConfig);
+    }
+    return clientInstance;
+}
+export function createOpenSearchProvider() {
+    const client = getClient();
+    return {
+        async index(indexName, id, body) {
+            await client.index({
+                index: indexName,
+                id: String(id),
+                body: body,
+                refresh: false
+            });
+        },
+        async remove(indexName, id) {
+            await client.delete({
+                index: indexName,
+                id: String(id),
+                refresh: false
+            });
+        },
+        async search(indexName, body) {
+            const response = await client.search({
+                index: indexName,
+                body: body
+            });
+            const hits = (response.body.hits?.hits ?? []).map((h) => ({
+                _id: h._id,
+                _source: h._source ?? {}
+            }));
+            return { hits };
+        },
+        async ensureIndex(indexName) {
+            try {
+                const exists = await client.indices.exists({ index: indexName });
+                const existsBody = exists.body;
+                if (!existsBody) {
+                    await client.indices.create({
+                        index: indexName,
+                        body: { settings: { 'index.mapping.total_fields.limit': 2000 } }
+                    });
+                }
+            }
+            catch (err) {
+                const status = err?.meta?.statusCode;
+                if (status === 404) {
+                    await client.indices.create({
+                        index: indexName,
+                        body: { settings: { 'index.mapping.total_fields.limit': 2000 } }
+                    });
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+    };
+}

package/dist/lib/search-provider-adapter.d.ts

@@ -0,0 +1,5 @@
+import { EnduranceSearchProvider, type SearchOptions, type SearchResult } from '@programisto/endurance';
+export declare class EdrmSearchProviderAdapter extends EnduranceSearchProvider {
+    isSearchEnabled(): boolean;
+    search(collection: string, options: SearchOptions): Promise<SearchResult>;
+}

package/dist/lib/search-provider-adapter.js

@@ -0,0 +1,10 @@
+import { EnduranceSearchProvider } from '@programisto/endurance';
+import { searchService } from './search-service.js';
+export class EdrmSearchProviderAdapter extends EnduranceSearchProvider {
+    isSearchEnabled() {
+        return searchService.isEnabled();
+    }
+    async search(collection, options) {
+        return searchService.search(collection, { ...options, collection });
+    }
+}

package/dist/lib/search-service.d.ts

@@ -0,0 +1,13 @@
+import type { SearchOptions, SearchResult } from '@programisto/endurance';
+declare class SearchService {
+    private provider;
+    private prefix;
+    private getProvider;
+    isEnabled(): boolean;
+    getIndexName(collectionName: string): string;
+    index(collectionName: string, id: string, document: object): Promise<void>;
+    remove(collectionName: string, id: string): Promise<void>;
+    search(collectionName: string, options: SearchOptions): Promise<SearchResult>;
+}
+export declare const searchService: SearchService;
+export {};

package/dist/lib/search-service.js

@@ -0,0 +1,100 @@
+import { createOpenSearchProvider } from './opensearch-provider.js';
+const DEFAULT_SIZE = 20;
+const MAX_SIZE = 100;
+function buildSearchBody(options) {
+    if (options.body && typeof options.body === 'object') {
+        return options.body;
+    }
+    const body = {
+        from: options.from ?? 0,
+        size: Math.min(options.size ?? DEFAULT_SIZE, MAX_SIZE)
+    };
+    const must = [];
+    if (options.q && String(options.q).trim()) {
+        must.push({
+            query_string: {
+                query: String(options.q).trim(),
+                default_field: '*'
+            }
+        });
+    }
+    if (options.filter && typeof options.filter === 'object' && Object.keys(options.filter).length > 0) {
+        const filterClauses = Object.entries(options.filter).map(([field, value]) => ({
+            term: { [field]: value }
+        }));
+        must.push({ bool: { filter: filterClauses } });
+    }
+    if (must.length > 0) {
+        body.query = { bool: { must } };
+    }
+    else if (!body.query) {
+        body.query = { match_all: {} };
+    }
+    if (options.sort && options.sort.length > 0) {
+        body.sort = options.sort;
+    }
+    return body;
+}
+class SearchService {
+    provider = null;
+    prefix = process.env.SEARCH_ENGINE_INDEX_PREFIX ?? '';
+    getProvider() {
+        if (!this.provider) {
+            this.provider = createOpenSearchProvider();
+        }
+        return this.provider;
+    }
+    isEnabled() {
+        const url = process.env.SEARCH_ENGINE_URL;
+        const enabled = process.env.SEARCH_ENGINE_ENABLED;
+        return Boolean(url && (enabled === 'true' || enabled === '1'));
+    }
+    getIndexName(collectionName) {
+        return this.prefix + collectionName;
+    }
+    async index(collectionName, id, document) {
+        if (!this.isEnabled())
+            return;
+        try {
+            const indexName = this.getIndexName(collectionName);
+            const provider = this.getProvider();
+            await provider.ensureIndex(indexName);
+            await provider.index(indexName, String(id), document);
+        }
+        catch (err) {
+            console.error('[edrm-search] Index error:', err);
+        }
+    }
+    async remove(collectionName, id) {
+        if (!this.isEnabled())
+            return;
+        try {
+            const indexName = this.getIndexName(collectionName);
+            const provider = this.getProvider();
+            await provider.remove(indexName, String(id));
+        }
+        catch (err) {
+            const status = err?.meta?.statusCode;
+            if (status !== 404) {
+                console.error('[edrm-search] Remove error:', err);
+            }
+        }
+    }
+    async search(collectionName, options) {
+        if (!this.isEnabled()) {
+            return { hits: [] };
+        }
+        try {
+            const indexName = this.getIndexName(collectionName);
+            const body = buildSearchBody({ ...options, collection: collectionName });
+            const provider = this.getProvider();
+            const result = await provider.search(indexName, body);
+            return { hits: result.hits };
+        }
+        catch (err) {
+            console.error('[edrm-search] Search error:', err);
+            return { hits: [] };
+        }
+    }
+}
+export const searchService = new SearchService();

package/dist/lib/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Internal provider interface for the search engine (OpenSearch/ES).
+ * Public search contract is EnduranceSearchProvider from @programisto/endurance.
+ */
+export interface InternalSearchProvider {
+    index(indexName: string, id: string, body: object): Promise<void>;
+    remove(indexName: string, id: string): Promise<void>;
+    search(indexName: string, body: object): Promise<InternalSearchResponse>;
+    ensureIndex(indexName: string): Promise<void>;
+}
+export interface InternalSearchResponse {
+    hits: Array<{
+        _id: string;
+        _source: object;
+    }>;
+}

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/listeners/search.listener.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/listeners/search.listener.js

@@ -0,0 +1,62 @@
+import { enduranceListener, EnduranceSearchMiddleware } from '@programisto/endurance';
+import { searchService } from '../lib/search-service.js';
+import { EdrmSearchProviderAdapter } from '../lib/search-provider-adapter.js';
+function getCollectionNameFromDoc(doc, eventName) {
+    const ctor = doc
+        ?.constructor;
+    const name = ctor?.getModel?.()?.collection?.name;
+    if (name)
+        return name;
+    const className = eventName.split(':')[0] ?? '';
+    const lower = className.toLowerCase();
+    return lower.endsWith('s') ? lower : lower + 's';
+}
+function docToPlainObject(doc) {
+    if (doc === null || doc === undefined)
+        return {};
+    const d = doc;
+    if (typeof d.toJSON === 'function')
+        return d.toJSON();
+    if (typeof d.toObject === 'function')
+        return d.toObject();
+    if (typeof doc === 'object' && doc !== null)
+        return { ...doc };
+    return {};
+}
+if (searchService.isEnabled()) {
+    EnduranceSearchMiddleware.setInstance(new EdrmSearchProviderAdapter());
+}
+enduranceListener.createAnyListener(async (...args) => {
+    if (!searchService.isEnabled())
+        return;
+    if (!args?.length || typeof args[0] !== 'string')
+        return;
+    const event = args[0];
+    const data = args.length > 1 ? args[1] : undefined;
+    try {
+        if (event.endsWith(':postSave') && data) {
+            const doc = data;
+            const id = doc._id != null ? String(doc._id) : undefined;
+            if (id == null)
+                return;
+            const collectionName = getCollectionNameFromDoc(doc, event);
+            const payload = docToPlainObject(doc);
+            searchService.index(collectionName, id, payload).catch((err) => {
+                console.error('[edrm-search] postSave index error:', err);
+            });
+        }
+        else if (event.endsWith(':postDeleteOne') && data && typeof data === 'object') {
+            const payload = data;
+            const id = payload.id != null ? String(payload.id) : undefined;
+            const collectionName = payload.collectionName;
+            if (id != null && collectionName) {
+                searchService.remove(collectionName, id).catch((err) => {
+                    console.error('[edrm-search] postDeleteOne remove error:', err);
+                });
+            }
+        }
+    }
+    catch (err) {
+        console.error('[edrm-search] Listener error:', err);
+    }
+});

package/dist/routes/search.router.d.ts

@@ -0,0 +1,8 @@
+import { EnduranceRouter } from '@programisto/endurance';
+declare class SearchRouter extends EnduranceRouter {
+    protected setupRoutes(): void;
+    private searchPost;
+    private searchGet;
+}
+declare const _default: SearchRouter;
+export default _default;

package/dist/routes/search.router.js

@@ -0,0 +1,78 @@
+import { EnduranceRouter, EnduranceSearchMiddleware } from '@programisto/endurance';
+const ROUTES_DISABLED_MESSAGE = 'Search routes are disabled. Use the search middleware from your module.';
+const ROUTES_DISABLED_CODE = 'SEARCH_ROUTES_DISABLED';
+function routesEnabled() {
+    return process.env.EDRM_SEARCH_ROUTES_ENABLED === 'true';
+}
+class SearchRouter extends EnduranceRouter {
+    setupRoutes() {
+        this.router.use((req, res, next) => {
+            if (!routesEnabled()) {
+                res.status(503).json({ message: ROUTES_DISABLED_MESSAGE, code: ROUTES_DISABLED_CODE });
+                return;
+            }
+            next();
+        });
+        const securityOptions = { requireAuth: true, permissions: [] };
+        this.post('/', securityOptions, this.searchPost.bind(this));
+        this.get('/', securityOptions, this.searchGet.bind(this));
+    }
+    async searchPost(req, res) {
+        try {
+            const collection = req.body?.collection ?? req.query?.collection;
+            if (!collection || typeof collection !== 'string') {
+                res.status(400).json({ error: 'Missing or invalid "collection" (string)' });
+                return;
+            }
+            const provider = EnduranceSearchMiddleware.getInstance();
+            if (!provider.isSearchEnabled()) {
+                res.status(503).json({ error: 'Search is not enabled', code: 'SEARCH_NOT_ENABLED' });
+                return;
+            }
+            const options = {
+                collection,
+                q: req.body?.q ?? req.query?.q,
+                filter: req.body?.filter ?? req.query?.filter,
+                sort: req.body?.sort ?? req.query?.sort,
+                from: req.body?.from ?? req.query?.from,
+                size: req.body?.size ?? req.query?.size,
+                body: req.body?.body
+            };
+            const result = await provider.search(collection, options);
+            res.json(result);
+        }
+        catch (err) {
+            console.error('[edrm-search] Search error:', err);
+            res.status(500).json({ error: 'Search failed' });
+        }
+    }
+    async searchGet(req, res) {
+        try {
+            const collection = req.query?.collection;
+            if (!collection || typeof collection !== 'string') {
+                res.status(400).json({ error: 'Missing or invalid "collection" query (string)' });
+                return;
+            }
+            const provider = EnduranceSearchMiddleware.getInstance();
+            if (!provider.isSearchEnabled()) {
+                res.status(503).json({ error: 'Search is not enabled', code: 'SEARCH_NOT_ENABLED' });
+                return;
+            }
+            const options = {
+                collection,
+                q: req.query?.q,
+                filter: req.query?.filter,
+                sort: req.query?.sort,
+                from: req.query?.from != null ? Number(req.query.from) : undefined,
+                size: req.query?.size != null ? Number(req.query.size) : undefined
+            };
+            const result = await provider.search(collection, options);
+            res.json(result);
+        }
+        catch (err) {
+            console.error('[edrm-search] Search error:', err);
+            res.status(500).json({ error: 'Search failed' });
+        }
+    }
+}
+export default new SearchRouter();

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@programisto/edrm-search",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/routes/search.router.js",
+  "types": "./dist/routes/search.router.d.ts",
+  "scripts": {
+    "start": "node ./dist/bin/www.js",
+    "dev": "tsc-watch --onSuccess \"node ./dist/bin/www.js\"",
+    "test": "echo \"Tests skipped\"",
+    "build": "tsc",
+    "lint": "eslint \"**/*.ts\"",
+    "prepare": "husky install 2>/dev/null || true"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/programisto-labs/edrm-search"
+  },
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/programisto-labs/edrm-search/issues"
+  },
+  "homepage": "https://github.com/programisto-labs/edrm-search#readme",
+  "description": "EDRM module for full-text search via OpenSearch/Elasticsearch, synced from Endurance schema events",
+  "dependencies": {
+    "@programisto/endurance": "^1.0.8",
+    "@opensearch-project/opensearch": "^2.10.0"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.8.1",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.35.0",
+    "@typescript-eslint/parser": "^8.35.0",
+    "eslint": "^8.57.1",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^16.6.2",
+    "eslint-plugin-promise": "^6.6.0",
+    "commitlint": "^19.8.1",
+    "husky": "^9.0.0",
+    "reflect-metadata": "^0.2.2",
+    "tsc-watch": "^6.2.1",
+    "typescript": "^5.8.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    ".eslintrc.json",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "rootDir": "./src/",
+    "outDir": "./dist",
+    "moduleResolution": "node",
+    "declaration": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"],
+  "exclude": ["node_modules", "dist", "__tests__", "**/*.test.ts"]
+}