fhirsmith 0.6.0 → 0.7.0

package/tx/ocl/cs-ocl.js

@@ -1,39 +1,2 @@
-/**
- * Abstract base class for value set providers
- * Defines the interface that all value set providers must implement
- */
-// eslint-disable-next-line no-unused-vars
-class OCLCodeSystemProvider {
-  /**
-   * {int} Unique number assigned to this provider
-   */
-  spaceId;
+module.exports = require('./cs-ocl.cjs');
 
-  /**
-   * ensure that the ids on the code systems are unique, if they are
-   * in the global namespace
-   *
-   * @param {Set<String>} ids
-   */
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
-    throw new Error('assignIds must be implemented by subclass');
-  }
-
-  /**
-  * Returns the list of CodeSystems this provider provides
-   *
-  * @param {string} fhirVersion - The FHIRVersion in scope - if relevant (there's always a stated version, though R5 is always used)
-  * @param {string} context - The client's stated context - if provided.
-  * @returns {Map<String, CodeSystem>} The list of CodeSystems
-  * @throws {Error} Must be implemented by subclasses
-  */
-  // eslint-disable-next-line no-unused-vars
-  async listCodeSystems(fhirVersion, context) {
-    throw new Error('listCodeSystems must be implemented by AbstractCodeSystemProvider subclass');
-  }
-}
-
-module.exports = {
-  AbstractCodeSystemProvider
-};

package/tx/ocl/fingerprint/fingerprint.cjs

@@ -0,0 +1,67 @@
+const crypto = require('crypto');
+
+function hashSortedLines(lines) {
+  const hash = crypto.createHash('sha256');
+  for (const line of lines.sort()) {
+    hash.update(line);
+    hash.update('\n');
+  }
+  return hash.digest('hex');
+}
+
+function computeCodeSystemFingerprint(concepts) {
+  if (!Array.isArray(concepts) || concepts.length === 0) {
+    return null;
+  }
+
+  const normalized = concepts
+    .map(concept => {
+      if (!concept || !concept.code) {
+        return null;
+      }
+
+      const code = String(concept.code || '');
+      const display = String(concept.display || '');
+      const definition = String(concept.definition || '');
+      const retired = concept.retired === true ? '1' : '0';
+      return `${code}|${display}|${definition}|${retired}`;
+    })
+    .filter(Boolean);
+
+  if (normalized.length === 0) {
+    return null;
+  }
+
+  return hashSortedLines(normalized);
+}
+
+function computeValueSetExpansionFingerprint(expansion) {
+  if (!expansion || !Array.isArray(expansion.contains) || expansion.contains.length === 0) {
+    return null;
+  }
+
+  const normalized = expansion.contains
+    .map(entry => {
+      if (!entry || !entry.code) {
+        return null;
+      }
+
+      const system = String(entry.system || '');
+      const code = String(entry.code || '');
+      const display = String(entry.display || '');
+      const inactive = entry.inactive === true ? '1' : '0';
+      return `${system}|${code}|${display}|${inactive}`;
+    })
+    .filter(Boolean);
+
+  if (normalized.length === 0) {
+    return null;
+  }
+
+  return hashSortedLines(normalized);
+}
+
+module.exports = {
+  computeCodeSystemFingerprint,
+  computeValueSetExpansionFingerprint
+};

package/tx/ocl/fingerprint/fingerprint.js

@@ -0,0 +1,2 @@
+module.exports = require('./fingerprint.cjs');
+

package/tx/ocl/http/client.cjs

@@ -0,0 +1,31 @@
+const axios = require('axios');
+const { DEFAULT_BASE_URL } = require('../shared/constants');
+
+function createOclHttpClient(config = {}) {
+  const options = typeof config === 'string' ? { baseUrl: config } : (config || {});
+
+  const baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  const headers = {
+    Accept: 'application/json',
+    'User-Agent': 'FHIRSmith-OCL-Provider/1.0'
+  };
+
+  if (options.token) {
+    headers.Authorization = options.token.startsWith('Token ') || options.token.startsWith('Bearer ')
+      ? options.token
+      : `Token ${options.token}`;
+  }
+
+  return {
+    baseUrl,
+    client: axios.create({
+      baseURL: baseUrl,
+      timeout: options.timeout || 30000,
+      headers
+    })
+  };
+}
+
+module.exports = {
+  createOclHttpClient
+};

package/tx/ocl/http/client.js

@@ -0,0 +1,2 @@
+module.exports = require('./client.cjs');
+

package/tx/ocl/http/pagination.cjs

@@ -0,0 +1,98 @@
+const { PAGE_SIZE } = require('../shared/constants');
+
+function extractItemsAndNext(payload, baseUrl = null) {
+  if (Array.isArray(payload)) {
+    return { items: payload, next: null };
+  }
+
+  if (!payload || typeof payload !== 'object') {
+    return { items: [], next: null };
+  }
+
+  const items = Array.isArray(payload.results)
+    ? payload.results
+    : Array.isArray(payload.items)
+      ? payload.items
+      : Array.isArray(payload.data)
+        ? payload.data
+        : [];
+
+  const next = payload.next || null;
+  if (!next) {
+    return { items, next: null };
+  }
+
+  if (baseUrl && typeof next === 'string' && next.startsWith(baseUrl)) {
+    return { items, next: next.replace(baseUrl, '') };
+  }
+
+  return { items, next };
+}
+
+async function fetchAllPages(httpClient, path, options = {}) {
+  const {
+    params = {},
+    pageSize = PAGE_SIZE,
+    maxPages = Number.MAX_SAFE_INTEGER,
+    baseUrl = null,
+    useNextLinks = true,
+    logger = null,
+    loggerPrefix = '[OCL]'
+  } = options;
+
+  const results = [];
+  let page = 1;
+  let nextPath = path;
+  let pageCount = 0;
+  let usePageMode = true;
+
+  while (nextPath && pageCount < maxPages) {
+    try {
+      const response = usePageMode
+        ? await httpClient.get(path, { params: { ...params, page, limit: pageSize } })
+        : await httpClient.get(nextPath);
+
+      if (Array.isArray(response.data)) {
+        results.push(...response.data);
+        pageCount += 1;
+
+        if (response.data.length < pageSize) {
+          break;
+        }
+
+        page += 1;
+        nextPath = path;
+        continue;
+      }
+
+      const { items, next } = extractItemsAndNext(response.data, baseUrl);
+      results.push(...items);
+      pageCount += 1;
+
+      if (useNextLinks && next) {
+        usePageMode = false;
+        nextPath = next;
+        continue;
+      }
+
+      if (usePageMode && items.length >= pageSize && pageCount < maxPages) {
+        page += 1;
+        nextPath = path;
+      } else {
+        break;
+      }
+    } catch (error) {
+      if (logger && typeof logger.error === 'function') {
+        logger.error(`${loggerPrefix} Fetch error on page ${page}:`, error.message);
+      }
+      throw error;
+    }
+  }
+
+  return results;
+}
+
+module.exports = {
+  extractItemsAndNext,
+  fetchAllPages
+};

package/tx/ocl/http/pagination.js

@@ -0,0 +1,2 @@
+module.exports = require('./pagination.cjs');
+

package/tx/ocl/jobs/background-queue.cjs

@@ -0,0 +1,200 @@
+class OCLBackgroundJobQueue {
+  static MAX_CONCURRENT = 2;
+  static HEARTBEAT_INTERVAL_MS = 30000;
+  static UNKNOWN_JOB_SIZE = Number.MAX_SAFE_INTEGER;
+  static pendingJobs = [];
+  static activeCount = 0;
+  static queuedOrRunningKeys = new Set();
+  static activeJobs = new Map();
+  static heartbeatTimer = null;
+  static enqueueSequence = 0;
+
+  static enqueue(jobKey, jobType, runJob, options = {}) {
+    if (!jobKey || typeof runJob !== 'function') {
+      return false;
+    }
+
+    if (this.queuedOrRunningKeys.has(jobKey)) {
+      return false;
+    }
+
+    this.queuedOrRunningKeys.add(jobKey);
+    const resolveAndEnqueue = async () => {
+      const resolvedSize = await this.#resolveJobSize(options);
+      const normalizedSize = this.#normalizeJobSize(resolvedSize);
+      this.#insertPendingJobOrdered({
+        jobKey,
+        jobType: jobType || 'background-job',
+        jobId: options?.jobId || jobKey,
+        jobSize: normalizedSize,
+        getProgress: typeof options?.getProgress === 'function' ? options.getProgress : null,
+        runJob,
+        enqueueOrder: this.enqueueSequence++
+      });
+      this.ensureHeartbeatRunning();
+      console.log(`[OCL] ${jobType || 'Background job'} enqueued: ${jobKey} (size=${normalizedSize}, queue=${this.pendingJobs.length}, active=${this.activeCount})`);
+      this.processNext();
+    };
+
+    Promise.resolve()
+      .then(resolveAndEnqueue)
+      .catch((error) => {
+        this.queuedOrRunningKeys.delete(jobKey);
+        const message = error && error.message ? error.message : String(error);
+        console.error(`[OCL] Failed to enqueue background job: ${jobType || 'background-job'} ${jobKey}: ${message}`);
+      });
+
+    return true;
+  }
+
+  static async #resolveJobSize(options = {}) {
+    if (typeof options?.resolveJobSize === 'function') {
+      try {
+        return await options.resolveJobSize();
+      } catch (_error) {
+        return this.UNKNOWN_JOB_SIZE;
+      }
+    }
+
+    if (options && Object.prototype.hasOwnProperty.call(options, 'jobSize')) {
+      return options.jobSize;
+    }
+
+    return this.UNKNOWN_JOB_SIZE;
+  }
+
+  static #normalizeJobSize(jobSize) {
+    const parsed = Number.parseInt(jobSize, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+      return this.UNKNOWN_JOB_SIZE;
+    }
+    return parsed;
+  }
+
+  static #insertPendingJobOrdered(job) {
+    let index = this.pendingJobs.findIndex(existing => {
+      if (existing.jobSize === job.jobSize) {
+        return existing.enqueueOrder > job.enqueueOrder;
+      }
+      return existing.jobSize > job.jobSize;
+    });
+
+    if (index < 0) {
+      index = this.pendingJobs.length;
+    }
+
+    this.pendingJobs.splice(index, 0, job);
+  }
+
+  static isQueuedOrRunning(jobKey) {
+    return this.queuedOrRunningKeys.has(jobKey);
+  }
+
+  static ensureHeartbeatRunning() {
+    if (this.heartbeatTimer) {
+      return;
+    }
+
+    this.heartbeatTimer = setInterval(() => {
+      this.logHeartbeat();
+    }, this.HEARTBEAT_INTERVAL_MS);
+
+    if (typeof this.heartbeatTimer.unref === 'function') {
+      this.heartbeatTimer.unref();
+    }
+  }
+
+  static logHeartbeat() {
+    const activeJobs = Array.from(this.activeJobs.values());
+    const lines = [
+      '[OCL] OCL background status:',
+      ` active jobs: ${activeJobs.length}`,
+      ` queued jobs: ${this.pendingJobs.length}`
+    ];
+
+    activeJobs.forEach((job, index) => {
+      lines.push('');
+      lines.push(` job ${index + 1}:`);
+      lines.push(`   type: ${job.jobType || 'background-job'}`);
+      lines.push(`   id: ${job.jobId || job.jobKey}`);
+      lines.push(`   size: ${job.jobSize}`);
+      lines.push(`   progress: ${this.formatProgress(job.getProgress)}`);
+    });
+
+    console.log(lines.join('\n'));
+  }
+
+  static formatProgress(getProgress) {
+    if (typeof getProgress !== 'function') {
+      return 'unknown';
+    }
+
+    try {
+      const progress = getProgress();
+      if (typeof progress === 'number' && Number.isFinite(progress)) {
+        const bounded = Math.max(0, Math.min(100, progress));
+        return `${Math.round(bounded)}%`;
+      }
+
+      if (progress && typeof progress === 'object') {
+        if (typeof progress.percentage === 'number' && Number.isFinite(progress.percentage)) {
+          const bounded = Math.max(0, Math.min(100, progress.percentage));
+          return `${Math.round(bounded)}%`;
+        }
+
+        if (
+          typeof progress.processed === 'number' &&
+          Number.isFinite(progress.processed) &&
+          typeof progress.total === 'number' &&
+          Number.isFinite(progress.total) &&
+          progress.total > 0
+        ) {
+          const ratio = progress.processed / progress.total;
+          const bounded = Math.max(0, Math.min(100, ratio * 100));
+          return `${Math.round(bounded)}%`;
+        }
+      }
+    } catch (_error) {
+      return 'unknown';
+    }
+
+    return 'unknown';
+  }
+
+  static processNext() {
+    while (this.activeCount < this.MAX_CONCURRENT && this.pendingJobs.length > 0) {
+      const job = this.pendingJobs.shift();
+      this.activeCount += 1;
+      this.activeJobs.set(job.jobKey, {
+        jobKey: job.jobKey,
+        jobType: job.jobType,
+        jobId: job.jobId || job.jobKey,
+        jobSize: job.jobSize,
+        getProgress: job.getProgress || null,
+        startedAt: Date.now()
+      });
+      console.log(`[OCL] Background job started: ${job.jobType} ${job.jobKey} (size=${job.jobSize}, queue=${this.pendingJobs.length}, active=${this.activeCount})`);
+
+      Promise.resolve()
+        .then(() => job.runJob())
+        .then(() => {
+          console.log(`[OCL] Background job completed: ${job.jobType} ${job.jobKey}`);
+        })
+        .catch((error) => {
+          const message = error && error.message ? error.message : String(error);
+          console.error(`[OCL] Background job failed: ${job.jobType} ${job.jobKey}: ${message}`);
+        })
+        .finally(() => {
+          this.activeCount -= 1;
+          this.queuedOrRunningKeys.delete(job.jobKey);
+          this.activeJobs.delete(job.jobKey);
+          console.log(`[OCL] Background queue status: queue=${this.pendingJobs.length}, active=${this.activeCount}`);
+          this.processNext();
+        });
+    }
+  }
+}
+
+module.exports = {
+  OCLBackgroundJobQueue
+};

package/tx/ocl/jobs/background-queue.js

@@ -0,0 +1,2 @@
+module.exports = require('./background-queue.cjs');
+

package/tx/ocl/mappers/concept-mapper.cjs

@@ -0,0 +1,66 @@
+function toConceptContext(concept) {
+  if (!concept || typeof concept !== 'object') {
+    return null;
+  }
+
+  const code = concept.code || concept.id || null;
+  if (!code) {
+    return null;
+  }
+
+  return {
+    code,
+    display: concept.display_name || concept.display || concept.name || null,
+    definition: concept.description || concept.definition || null,
+    retired: concept.retired === true,
+    designations: extractDesignations(concept)
+  };
+}
+
+function extractDesignations(concept) {
+  const result = [];
+  const seen = new Set();
+
+  const add = (language, value) => {
+    const text = typeof value === 'string' ? value.trim() : '';
+    if (!text) {
+      return;
+    }
+
+    const lang = typeof language === 'string' ? language.trim() : '';
+    const key = `${lang}|${text}`;
+    if (seen.has(key)) {
+      return;
+    }
+
+    seen.add(key);
+    result.push({ language: lang, value: text });
+  };
+
+  if (Array.isArray(concept.names)) {
+    for (const entry of concept.names) {
+      if (!entry || typeof entry !== 'object') {
+        continue;
+      }
+
+      add(entry.locale || entry.language || entry.lang || '', entry.name || entry.display_name || entry.display || entry.value || entry.term);
+    }
+  }
+
+  if (concept.display_name || concept.display || concept.name) {
+    add(concept.locale || concept.default_locale || concept.language || '', concept.display_name || concept.display || concept.name);
+  }
+
+  if (concept.locale_display_names && typeof concept.locale_display_names === 'object') {
+    for (const [lang, value] of Object.entries(concept.locale_display_names)) {
+      add(lang, value);
+    }
+  }
+
+  return result;
+}
+
+module.exports = {
+  toConceptContext,
+  extractDesignations
+};

package/tx/ocl/mappers/concept-mapper.js

@@ -0,0 +1,2 @@
+module.exports = require('./concept-mapper.cjs');
+

package/tx/ocl/model/concept-filter-context.cjs

@@ -0,0 +1,51 @@
+class OCLConceptFilterContext {
+  constructor() {
+    this.concepts = [];
+    this.currentIndex = -1;
+  }
+
+  add(concept, rating = 0) {
+    this.concepts.push({ concept, rating });
+  }
+
+  sort() {
+    this.concepts.sort((a, b) => b.rating - a.rating);
+  }
+
+  size() {
+    return this.concepts.length;
+  }
+
+  hasMore() {
+    return this.currentIndex + 1 < this.concepts.length;
+  }
+
+  next() {
+    if (!this.hasMore()) {
+      return null;
+    }
+    this.currentIndex += 1;
+    return this.concepts[this.currentIndex].concept;
+  }
+
+  reset() {
+    this.currentIndex = -1;
+  }
+
+  findConceptByCode(code) {
+    for (const item of this.concepts) {
+      if (item.concept && item.concept.code === code) {
+        return item.concept;
+      }
+    }
+    return null;
+  }
+
+  containsConcept(concept) {
+    return this.concepts.some(item => item.concept === concept);
+  }
+}
+
+module.exports = {
+  OCLConceptFilterContext
+};

package/tx/ocl/model/concept-filter-context.js

@@ -0,0 +1,2 @@
+module.exports = require('./concept-filter-context.cjs');
+

package/tx/ocl/shared/constants.cjs

@@ -0,0 +1,15 @@
+const DEFAULT_BASE_URL = 'https://api.openconceptlab.org';
+const PAGE_SIZE = 100;
+const CONCEPT_PAGE_SIZE = 1000;
+const FILTERED_CONCEPT_PAGE_SIZE = 200;
+const COLD_CACHE_FRESHNESS_MS = 60 * 60 * 1000;
+const OCL_CODESYSTEM_MARKER_EXTENSION = 'http://fhir.org/FHIRsmith/StructureDefinition/ocl-codesystem';
+
+module.exports = {
+  DEFAULT_BASE_URL,
+  PAGE_SIZE,
+  CONCEPT_PAGE_SIZE,
+  FILTERED_CONCEPT_PAGE_SIZE,
+  COLD_CACHE_FRESHNESS_MS,
+  OCL_CODESYSTEM_MARKER_EXTENSION
+};

package/tx/ocl/shared/constants.js

@@ -0,0 +1,2 @@
+module.exports = require('./constants.cjs');
+