@centricare/value-sets

@centricare/value-sets adalah TypeScript library dan Value Set Manager untuk mengelola, memuat, menavigasi, serta memvalidasi file definisi Value Set / Code Set JSON dalam ekosistem CentriCare.

Package ini secara otomatis memetakan setiap nilai konsep menjadi bentuk Custom URN berformat crn:{domain}:{name}:{value}.

[!WARNING] Penting: Package ini tidak mem-bundle file definisi data value-set secara bawaan. Aplikasi perlu memuat file JSON value-set sendiri menggunakan fungsi pemuat yang disediakan (load_from_file, load_from_file_sync, load_from_json, atau load_from_directory).

📦 Fitur Utama

• Custom URN Standardization: Setiap kode/nilai otomatis dipetakan ke URN bertipe crn:{domain}:{name}:{value} (misal: crn:common:status:active).
• Flexible Loading: Dukungan membaca file JSON secara asynchronous (load_from_file), synchronous (load_from_file_sync), dari objek memori (load_from_json), maupun memuat seluruh folder (load_from_directory).
• Flexible Key & URN Lookup: Pencarian dapat dilakukan menggunakan key (common/status) ataupun base URN (crn:common:status).
• Value & URN Validation: Memvalidasi apakah suatu kode mentah (misal: "active") atau full URN ("crn:common:status:active") valid berada di dalam suatu value set.
• Conversion & Global Lookup: Mengonversi kode mentah menjadi URN (to_urn), serta lookup global berdasarkan full URN (lookup_urn).
• Search Capabilities: Pencarian nilai/URN di dalam satu value set (search_value_set) maupun pencarian global lintas value set (search_registries).

📄 Format JSON Value Set

File JSON value set CentriCare menggunakan struktur berikut:

{
  "version": "1.2.0",
  "value_sets": [
    {
      "domain": "common",
      "name": "status",
      "values": ["active", "inactive", "suspended"]
    },
    {
      "domain": "common",
      "name": "gender",
      "values": ["male", "female"]
    },
    {
      "domain": "identifier",
      "name": "type",
      "values": ["mrn", "nik", "passport", "satusehat", "bpjs"]
    }
  ]
}

🚀 Panduan Penggunaan

1. Inisialisasi & Memuat Data JSON

import { ValueSetManager } from "@centricare/value-sets";

const manager = new ValueSetManager();

// 1. Memuat dari file JSON secara async
await manager.load_from_file("./examples/value-set.json");

// 2. Memuat dari file JSON secara sync
manager.load_from_file_sync("./examples/value-set.json");

// 3. Memuat dari objek JSON langsung
manager.load_from_json({
  version: "1.2.0",
  value_sets: [
    {
      domain: "common",
      name: "status",
      values: ["active", "inactive", "suspended"],
    },
  ],
});

// 4. Memuat seluruh file JSON dalam satu direktori
await manager.load_from_directory("./examples");

2. Mengambil Data Value Set & Nilai URN

// Ambil objek ValueSetEntry berdasarkan key atau base URN
const status_entry = manager.get_value_set("common/status");
// atau
const status_entry_by_urn = manager.get_value_set("crn:common:status");

console.log(status_entry?.values);
// Output: ["active", "inactive", "suspended"]

console.log(status_entry?.urns);
// Output: ["crn:common:status:active", "crn:common:status:inactive", "crn:common:status:suspended"]

console.log(status_entry?.concepts);
// Output:
// [
//   { value: "active", urn: "crn:common:status:active" },
//   { value: "inactive", urn: "crn:common:status:inactive" },
//   { value: "suspended", urn: "crn:common:status:suspended" }
// ]

3. Validasi & Konversi Kode

// Validasi kode mentah atau full URN
manager.validate_value("common/status", "active"); // true
manager.validate_value("common/status", "crn:common:status:active"); // true
manager.validate_value("common/status", "invalid_code"); // false

// Konversi kode mentah menjadi full URN
const urn = manager.to_urn("common/status", "active");
console.log(urn); // "crn:common:status:active"

// Lookup global berdasarkan full URN
const found = manager.lookup_urn("crn:common:status:active");
console.log(found?.concept.value); // "active"
console.log(found?.entry.key); // "common/status"

4. Pencarian (Search)

// 1. Search di dalam satu Value Set
const matched_concepts = manager.search_value_set(
  "location/bed-status",
  "clean",
);
// Output: [{ value: "cleaning", urn: "crn:location:bed-status:cleaning" }]

// 2. Search global lintas semua Value Set
const search_results = manager.search_registries("gender");
// Output: [{ key: "common/gender", urn: "crn:common:gender", domain: "common", name: "gender", matched_concepts: [...] }]

5. Utility Helper Static

import { ValueSetManager } from "@centricare/value-sets";

// Build URN
const full_urn = ValueSetManager.build_urn("common", "status", "active");
// "crn:common:status:active"

const base_urn = ValueSetManager.build_base_urn("common", "status");
// "crn:common:status"

// Parse URN
const parsed = ValueSetManager.parse_urn("crn:common:status:active");
// {
//   domain: "common",
//   name: "status",
//   value: "active",
//   urn: "crn:common:status:active",
//   base_urn: "crn:common:status",
//   key: "common/status"
// }

🛠️ Development & Build

Requirements

• Node.js (v18+)
• npm

Build Package

npm run build

📄 Lisensi

ISC