@alizarin/napi 2.0.0-alpha.96 → 2.0.0-alpha.98

package/__test__/index.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-import { NapiStaticGraph, NapiStaticResourceRegistry, NapiResourceModelWrapper, NapiResourceInstanceWrapper } from '../index.js';
+import { NapiStaticGraph, NapiStaticResourceRegistry, NapiResourceModelWrapper, NapiResourceInstanceWrapper, NapiNodeConfigManager } from '../index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEST_DATA = path.resolve(__dirname, '..', '..', '..', 'tests');
@@ -522,3 +522,44 @@ describe('NapiResourceInstanceWrapper methods', () => {
     assert.equal(tiles.length, 0, 'should be empty');
   });
 });
+
+// =============================================================================
+// NapiNodeConfigManager + NapiStaticGraph integration
+// Regression: loadFromGraph used JSON.stringify on a NapiStaticGraph, which
+// produced {} because NAPI class getters are not enumerable own properties.
+// The fix uses buildFromGraph (direct struct reference) instead.
+// =============================================================================
+
+describe('NapiNodeConfigManager', () => {
+  const personJson = fs.readFileSync(
+    path.join(TEST_DATA, 'data', 'models', 'Person.json'),
+    'utf-8'
+  );
+
+  it('buildFromGraph accepts a NapiStaticGraph without error', () => {
+    const graph = NapiStaticGraph.fromJsonString(personJson);
+    const ncm = new NapiNodeConfigManager();
+    // This is the path that failed when using JSON.stringify(napiGraph)
+    ncm.buildFromGraph(graph);
+  });
+
+  it('buildFromGraphJson fails on JSON.stringify of a NapiStaticGraph', () => {
+    const graph = NapiStaticGraph.fromJsonString(personJson);
+    const ncm = new NapiNodeConfigManager();
+    // Demonstrates the bug: NAPI objects don't stringify their getters
+    const stringified = JSON.stringify(graph);
+    assert.throws(
+      () => ncm.buildFromGraphJson(stringified),
+      /Failed to parse graph/i,
+      'JSON.stringify of NapiStaticGraph should produce invalid graph JSON'
+    );
+  });
+
+  it('buildFromGraphJson works with raw graph JSON', () => {
+    const parsed = JSON.parse(personJson);
+    const graphObj = parsed.graph ? parsed.graph[0] : parsed;
+    const ncm = new NapiNodeConfigManager();
+    // Raw JS object stringifies correctly
+    ncm.buildFromGraphJson(JSON.stringify(graphObj));
+  });
+});

package/index.d.ts

@@ -17,7 +17,7 @@ export declare function buildGraphFromCsvs(graphCsv: string, nodesCsv: string, c
  * Returns the resources wrapped in the `{ business_data: { resources: [...] } }`
  * format expected by PrebuildLoader.
  */
-export declare function buildBusinessDataFromCsv(csvData: string, graphJson: string, collectionsJson: string): any
+export declare function buildBusinessDataFromCsv(csvData: string, graphJson: string, collectionsJson: string, defaultLanguage?: string | undefined | null, strictConcepts?: boolean | undefined | null): any
 /**
  * Coerce a value using the registered extension handler for the given datatype.
  *
@@ -44,6 +44,10 @@ export declare function getRegisteredExtensionHandlers(): Array<string>
 export declare function parseSkosXml(xmlContent: string, baseUri: string): any
 /** Parse SKOS RDF/XML and return a single collection (the first one found). */
 export declare function parseSkosXmlToCollection(xmlContent: string, baseUri: string): any
+/** Serialize a single SkosCollection to SKOS RDF/XML. */
+export declare function collectionToSkosXml(collectionJson: any, baseUri: string): string
+/** Serialize multiple SkosCollections to SKOS RDF/XML. */
+export declare function collectionsToSkosXml(collectionsJson: any, baseUri: string): string
 /**
  * Build a mapping from node alias to collection ID based on graph definition.
  *
@@ -193,8 +197,13 @@ export declare class NapiValuesFromNodegroupResult {
   get impliedNodegroups(): Array<string>
 }
 export declare class NapiResourceInstanceWrapper {
-  /** Create a wrapper for a given graph (must be registered). */
-  constructor(graphId: string)
+  /**
+   * Create a wrapper for a given graph (must be registered).
+   *
+   * If `resource_id` is provided, a minimal resource metadata is created so
+   * the tile-source fast path can look up tiles by resource.
+   */
+  constructor(graphId: string, resourceId?: string | undefined | null)
   /** Load tiles from a JSON string (single-pass deserialization). */
   loadTiles(tilesJson: string): void
   /** Load tiles directly from a StaticResource JSON string (single-pass deserialization). */
@@ -368,6 +377,13 @@ export declare class NapiStaticGraph {
   get name(): any
   /** Register this graph in the global registry so NapiResourceInstanceWrapper can use it. */
   register(): void
+  /**
+   * Set a descriptor template for computing resource name/description/slug.
+   *
+   * Template placeholders use `<Node Name>` syntax, e.g. `"<Headword>"`.
+   * Descriptor types: "name", "description", "slug".
+   */
+  setDescriptorTemplate(descriptorType: string, stringTemplate: string): void
 }
 export declare class NapiStaticResourceRegistry {
   constructor()
@@ -384,7 +400,7 @@ export declare class NapiStaticResourceRegistry {
   /** Insert full resources from a business_data JSON file string. */
   mergeFromBusinessDataJson(businessDataJson: string, storeFull?: boolean | undefined | null): void
   /** Build an inverted index: visibility value -> [resource IDs]. */
-  getValueToResourcesIndex(graph: NapiStaticGraph, nodeIdentifier: string, flattenLocalized?: boolean | undefined | null): Record<string, Array<string>>
+  getValueToResourcesIndex(graph: NapiStaticGraph, nodeIdentifier: string, flattenLocalized?: boolean | undefined | null, rdmCache?: NapiRdmCache | undefined | null): Record<string, Array<string>>
   /**
    * Extract values from one node in tiles where another node matches a filter.
    *
@@ -406,4 +422,17 @@ export declare class NapiStaticResourceRegistry {
   memoryStats(): any
   /** Get detailed stats including estimated byte sizes (expensive — re-serializes all data) */
   memoryStatsDetailed(): any
+  /**
+   * Populate __cache on resources with summaries for referenced resources.
+   *
+   * Uses the graph to identify resource-instance nodes, then populates
+   * cache entries for each referenced resource found in this registry.
+   *
+   * If `enrich_relationships` is true, also adds ontologyProperty to tile data.
+   * If `recompute_descriptors` is true, recomputes resource name/description from
+   * descriptor templates set on the graph.
+   *
+   * Returns `{ resources, unknownReferences, hasUnknown }`.
+   */
+  populateCachesFromJson(resourcesJson: string, graph: NapiStaticGraph, enrichRelationships?: boolean | undefined | null, strict?: boolean | undefined | null, recomputeDescriptors?: boolean | undefined | null): any
 }

package/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { NapiRdmCache, NapiNodeConfigManager, NapiTileData, NapiStaticTile, NapiPseudoValue, NapiPseudoList, NapiPopulateResult, NapiEnsureNodegroupResult, NapiValuesFromNodegroupResult, NapiResourceInstanceWrapper, NapiResourceModelWrapper, NapiPrebuildExporter, NapiStaticGraph, NapiStaticResourceRegistry, buildGraphFromCsvs, buildBusinessDataFromCsv, extensionCoerce, extensionRenderDisplay, extensionResolveMarkers, hasExtensionHandler, getRegisteredExtensionHandlers, parseSkosXml, parseSkosXmlToCollection, buildAliasToCollectionMap, findNeededCollections, isValidUuid, getDefaultResolvableDatatypes, getDefaultConfigKeys, importPrebuild } = nativeBinding
+const { NapiRdmCache, NapiNodeConfigManager, NapiTileData, NapiStaticTile, NapiPseudoValue, NapiPseudoList, NapiPopulateResult, NapiEnsureNodegroupResult, NapiValuesFromNodegroupResult, NapiResourceInstanceWrapper, NapiResourceModelWrapper, NapiPrebuildExporter, NapiStaticGraph, NapiStaticResourceRegistry, buildGraphFromCsvs, buildBusinessDataFromCsv, extensionCoerce, extensionRenderDisplay, extensionResolveMarkers, hasExtensionHandler, getRegisteredExtensionHandlers, parseSkosXml, parseSkosXmlToCollection, collectionToSkosXml, collectionsToSkosXml, buildAliasToCollectionMap, findNeededCollections, isValidUuid, getDefaultResolvableDatatypes, getDefaultConfigKeys, importPrebuild } = nativeBinding
 
 module.exports.NapiRdmCache = NapiRdmCache
 module.exports.NapiNodeConfigManager = NapiNodeConfigManager
@@ -335,6 +335,8 @@ module.exports.hasExtensionHandler = hasExtensionHandler
 module.exports.getRegisteredExtensionHandlers = getRegisteredExtensionHandlers
 module.exports.parseSkosXml = parseSkosXml
 module.exports.parseSkosXmlToCollection = parseSkosXmlToCollection
+module.exports.collectionToSkosXml = collectionToSkosXml
+module.exports.collectionsToSkosXml = collectionsToSkosXml
 module.exports.buildAliasToCollectionMap = buildAliasToCollectionMap
 module.exports.findNeededCollections = findNeededCollections
 module.exports.isValidUuid = isValidUuid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alizarin/napi",
-  "version": "2.0.0-alpha.96",
+  "version": "2.0.0-alpha.98",
   "license": "AGPL-3.0-or-later",
   "repository": {
     "type": "git",
@@ -30,8 +30,8 @@
     "@napi-rs/cli": "^2.18.0"
   },
   "optionalDependencies": {
-    "@alizarin/napi-win32-x64-msvc": "2.0.0-alpha.96",
-    "@alizarin/napi-darwin-x64": "2.0.0-alpha.96",
-    "@alizarin/napi-linux-x64-gnu": "2.0.0-alpha.96"
+    "@alizarin/napi-win32-x64-msvc": "2.0.0-alpha.98",
+    "@alizarin/napi-darwin-x64": "2.0.0-alpha.98",
+    "@alizarin/napi-linux-x64-gnu": "2.0.0-alpha.98"
   }
 }

package/src/instance_wrapper_napi.rs

@@ -44,7 +44,14 @@ fn sc_err(e: SemanticChildError) -> napi::Error {
 
 #[napi]
 pub struct NapiRdmCache {
-    inner: RdmCache,
+    pub(crate) inner: RdmCache,
+}
+
+impl NapiRdmCache {
+    /// Crate-internal accessor (field not directly accessible through #[napi] macro).
+    pub(crate) fn inner(&self) -> &RdmCache {
+        &self.inner
+    }
 }
 
 #[napi]
@@ -780,8 +787,11 @@ impl NapiResourceInstanceWrapper {
     // =========================================================================
 
     /// Create a wrapper for a given graph (must be registered).
+    ///
+    /// If `resource_id` is provided, a minimal resource metadata is created so
+    /// the tile-source fast path can look up tiles by resource.
     #[napi(constructor)]
-    pub fn new(graph_id: String) -> Result<Self> {
+    pub fn new(graph_id: String, _resource_id: Option<String>) -> Result<Self> {
         let graph = alizarin_core::get_graph(&graph_id).ok_or_else(|| {
             napi::Error::from_reason(format!(
                 "Graph '{}' not registered. Call registerGraph() first.",
@@ -790,6 +800,7 @@ impl NapiResourceInstanceWrapper {
         })?;
 
         let model_access = GraphModelAccess::from_graph(&graph);
+        // TODO: use resource_id with new_for_resource_id once tile-source plumbing is committed
         let mut core = ResourceInstanceWrapperCore::new(graph_id);
         core.set_cached_indices(&model_access);
 

package/src/lib.rs

@@ -1,4 +1,5 @@
 mod instance_wrapper_napi;
+use instance_wrapper_napi::NapiRdmCache;
 
 use std::collections::HashMap;
 use std::sync::OnceLock;
@@ -166,6 +167,21 @@ impl NapiStaticGraph {
     pub fn register(&self) {
         alizarin_core::register_graph_owned(self.inner.clone());
     }
+
+    /// Set a descriptor template for computing resource name/description/slug.
+    ///
+    /// Template placeholders use `<Node Name>` syntax, e.g. `"<Headword>"`.
+    /// Descriptor types: "name", "description", "slug".
+    #[napi(js_name = "setDescriptorTemplate")]
+    pub fn set_descriptor_template(
+        &mut self,
+        descriptor_type: String,
+        string_template: String,
+    ) -> Result<()> {
+        self.inner
+            .set_descriptor_template(&descriptor_type, &string_template)
+            .map_err(napi::Error::from_reason)
+    }
 }
 
 // ============================================================================
@@ -281,9 +297,12 @@ impl NapiStaticResourceRegistry {
         graph: &NapiStaticGraph,
         node_identifier: String,
         flatten_localized: Option<bool>,
+        rdm_cache: Option<&NapiRdmCache>,
     ) -> Result<HashMap<String, Vec<String>>> {
         let ctx = SerializationContext {
             extension_registry: Some(extension_registry()),
+            external_resolver: rdm_cache
+                .map(|r| r.inner() as &dyn alizarin_core::type_serialization::ExternalResolver),
             ..SerializationContext::empty()
         };
         self.inner
@@ -397,6 +416,47 @@ impl NapiStaticResourceRegistry {
         serde_json::to_value(&stats)
             .map_err(|e| napi::Error::from_reason(format!("Serialization failed: {}", e)))
     }
+
+    /// Populate __cache on resources with summaries for referenced resources.
+    ///
+    /// Uses the graph to identify resource-instance nodes, then populates
+    /// cache entries for each referenced resource found in this registry.
+    ///
+    /// If `enrich_relationships` is true, also adds ontologyProperty to tile data.
+    /// If `recompute_descriptors` is true, recomputes resource name/description from
+    /// descriptor templates set on the graph.
+    ///
+    /// Returns `{ resources, unknownReferences, hasUnknown }`.
+    #[napi(js_name = "populateCachesFromJson")]
+    pub fn populate_caches_from_json(
+        &self,
+        resources_json: String,
+        graph: &NapiStaticGraph,
+        enrich_relationships: Option<bool>,
+        strict: Option<bool>,
+        recompute_descriptors: Option<bool>,
+    ) -> Result<serde_json::Value> {
+        let mut resources: Vec<StaticResource> = serde_json::from_str(&resources_json)
+            .map_err(|e| napi::Error::from_reason(format!("Failed to parse resources: {}", e)))?;
+
+        let result = self
+            .inner
+            .populate_caches(
+                &mut resources,
+                &graph.inner,
+                enrich_relationships.unwrap_or(true),
+                strict.unwrap_or(false),
+                recompute_descriptors.unwrap_or(false),
+            )
+            .map_err(napi::Error::from_reason)?;
+
+        let output = serde_json::json!({
+            "resources": resources,
+            "unknownReferences": result.unknown_references,
+            "hasUnknown": result.has_unknown_references(),
+        });
+        Ok(output)
+    }
 }
 
 // ============================================================================
@@ -459,15 +519,21 @@ pub fn build_business_data_from_csv(
     csv_data: String,
     graph_json: String,
     collections_json: String,
+    default_language: Option<String>,
+    strict_concepts: Option<bool>,
 ) -> Result<serde_json::Value> {
     let graph: StaticGraph = serde_json::from_str(&graph_json)
         .map_err(|e| napi::Error::from_reason(format!("Invalid graph JSON: {e}")))?;
     let collections: Vec<SkosCollection> = serde_json::from_str(&collections_json)
         .map_err(|e| napi::Error::from_reason(format!("Invalid collections JSON: {e}")))?;
 
-    let resources =
-        build_resources_from_business_csv(&csv_data, &graph, &collections, Default::default())
-            .map_err(csv_err)?;
+    let options = alizarin_core::csv_business_data_loader::BusinessDataCsvOptions {
+        default_language: default_language.unwrap_or_else(|| "en".to_string()),
+        strict_concepts: strict_concepts.unwrap_or(true),
+    };
+
+    let resources = build_resources_from_business_csv(&csv_data, &graph, &collections, options)
+        .map_err(csv_err)?;
 
     Ok(wrap_business_data(&resources))
 }
@@ -574,6 +640,37 @@ pub fn parse_skos_xml_to_collection(
     serde_json::to_value(&collection).map_err(|e| napi::Error::from_reason(e.to_string()))
 }
 
+/// Serialize a single SkosCollection to SKOS RDF/XML.
+#[napi(js_name = "collectionToSkosXml")]
+pub fn collection_to_skos_xml_napi(
+    collection_json: serde_json::Value,
+    base_uri: String,
+) -> Result<String> {
+    let collection: SkosCollection = serde_json::from_value(collection_json).map_err(|e| {
+        napi::Error::from_reason(format!("Failed to deserialize collection: {}", e))
+    })?;
+    Ok(alizarin_core::skos::collection_to_skos_xml(
+        &collection,
+        &base_uri,
+    ))
+}
+
+/// Serialize multiple SkosCollections to SKOS RDF/XML.
+#[napi(js_name = "collectionsToSkosXml")]
+pub fn collections_to_skos_xml_napi(
+    collections_json: serde_json::Value,
+    base_uri: String,
+) -> Result<String> {
+    let collections: Vec<SkosCollection> =
+        serde_json::from_value(collections_json).map_err(|e| {
+            napi::Error::from_reason(format!("Failed to deserialize collections: {}", e))
+        })?;
+    Ok(alizarin_core::skos::collections_to_skos_xml(
+        &collections,
+        &base_uri,
+    ))
+}
+
 // ============================================================================
 // Label resolution utilities
 // ============================================================================