@kent-tokyo/chematic 1.0.13 → 1.0.14

package/README.md

@@ -4,6 +4,10 @@ WebAssembly bindings for [chematic](https://github.com/kent-tokyo/chematic), a p
 
 Published to npm as [`@kent-tokyo/chematic`](https://www.npmjs.com/package/@kent-tokyo/chematic).
 
+The current workspace line is 1.0.14. The binding keeps bounded parsing,
+typed failures, and opt-in `embed_pipeline_v2_json`; 3D/MMFF94 behavior remains
+Experimental and is not a claim of full RDKit parity.
+
 ## Installation
 
 ```sh
@@ -100,6 +104,11 @@ console.log(mol.labute_asa());                   // Labute approx. surface area
 const charges = JSON.parse(gasteiger_charges_json(mol));
 console.log(charges); // [-0.08, 0.12, -0.43, ...]
 
+// Explicit RDKit-compatibility descriptor profile (kept separate from the
+// historical native get_descriptors_json() profile)
+const rdkitDescriptors = JSON.parse(get_rdkit_descriptors_json(mol));
+console.log(rdkitDescriptors.aromatic_ring_count);
+
 // VSA descriptor bins
 const slogpVsa = JSON.parse(slogp_vsa_json(mol));
 const smrVsa   = JSON.parse(smr_vsa_json(mol));
@@ -168,6 +177,17 @@ portable across native and `wasm32-unknown-unknown`
 precision across every JS engine, only that the value is finite, non-negative,
 and enforced correctly on all of them.
 
+`nearest_neighbors_json` keeps its historical chematic-native ECFP4 profile.
+For the separately named RDKit-compatible Morgan profile, use
+`rdkit_nearest_neighbors_json(querySmiles, dbSmilesJson, k)`. It returns the
+same `{index, tanimoto}` shape and reports preprocessing failures without
+silently falling back to native ECFP4.
+
+For repeated queries, construct `new RdkitSearchIndex(dbSmilesJson)` once and
+call `index.search_json(querySmiles, k)`. The prepared index is intended for
+chunked libraries up to the WASM batch limit and applies the same fail-closed
+RDKit-compatible profile without rebuilding database fingerprints per query.
+
 ## V3000 SGROUP syntax view
 
 `v3000_sgroups_json(block)` exposes bounded, typed SGROUP syntax without

package/chematic_wasm.d.ts

@@ -409,6 +409,10 @@ export class MolHandle {
      * Most basic pKa in the molecule, or NaN if no basic site.
      */
     pka_base_value(): number;
+    /**
+     * Atom indices of potential tetrahedral stereocenters.
+     */
+    potential_stereocenter_indices(): Uint32Array;
     /**
      * Quantitative Estimate of Drug-likeness (QED); range [0, 1].
      */
@@ -462,6 +466,47 @@ export class MolHandle {
     zagreb_index_m1(): number;
 }
 
+/**
+ * Reusable prepared index for the RDKit-compatible Morgan profile.
+ *
+ * Build one index per input chunk (the WASM batch limit is 1,024 molecules),
+ * then call [`RdkitSearchIndex::search_json`] for multiple queries without
+ * reparsing or refingerprinting the database.
+ */
+export class RdkitSearchIndex {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Whether the prepared index contains no molecules.
+     */
+    is_empty(): boolean;
+    /**
+     * Number of molecules in this chunk.
+     */
+    len(): number;
+    /**
+     * Build an index from a JSON array of SMILES strings.
+     */
+    constructor(db_smiles_json: string);
+    /**
+     * Search the prepared index with a query SMILES.
+     */
+    search_json(query_smiles: string, k: number): string;
+    /**
+     * Search without the historical six-decimal JSON score truncation.
+     *
+     * This opt-in endpoint is for exact parity measurements. Callers that
+     * need the stable historical wire format should continue using
+     * RdkitSearchIndex::search_json.
+     */
+    search_json_precise(query_smiles: string, k: number): string;
+    /**
+     * Search with an inclusive Tanimoto threshold and precise JSON scores.
+     * A threshold of `0.0` includes zero-score candidates.
+     */
+    search_json_threshold_precise(query_smiles: string, threshold: number, k: number): string;
+}
+
 /**
  * Return a copy of the molecule with all implicit hydrogens converted to explicit H atoms.
  */
@@ -1190,6 +1235,17 @@ export function get_descriptors_json(mol: MolHandle): string;
  */
 export function get_dihedral_json(smiles: string, a: number, b: number, c: number, d: number): any;
 
+/**
+ * RDKit-compatibility descriptor profile as JSON.
+ *
+ * This is deliberately separate from [`get_descriptors_json`]: the latter is
+ * the historical native profile, while this profile uses the opt-in RDKit
+ * molecular-weight, HBA, and aromatic-ring implementations.  Keeping the
+ * boundary explicit prevents a compatibility correction from silently
+ * changing the browser's native descriptor contract.
+ */
+export function get_rdkit_descriptors_json(mol: MolHandle): string;
+
 /**
  * Compute GETAWAY descriptors (GEometry, Topology and Atom-Weights AssemblY) from 3D coords.
  *
@@ -2186,6 +2242,17 @@ export function rdkit_ecfp_config_chiral_detail_json(mol: MolHandle, radius: num
  */
 export function rdkit_ecfp_config_detail_json(mol: MolHandle, radius: number, nbits: number): string;
 
+/**
+ * Find the k nearest neighbours using the RDKit-compatible Morgan/ECFP4
+ * profile. This is intentionally separate from [`nearest_neighbors_json`],
+ * whose historical contract uses chematic's native ECFP4 profile.
+ *
+ * Returns JSON with the original database indices and six-decimal Tanimoto
+ * scores. Any RDKit-profile preprocessing failure is returned as an error;
+ * this API never falls back to the native profile.
+ */
+export function rdkit_nearest_neighbors_json(query_smiles: string, db_smiles_json: string, k: number): string;
+
 /**
  * Compute the RDKit-compatible Daylight-like path fingerprint as a bit-packed
  * byte vector (256 bytes = 2048 bits). This is the WASM counterpart of the
@@ -2850,6 +2917,7 @@ export interface InitOutput {
     readonly __wbg_depictoptions_free: (a: number, b: number) => void;
     readonly __wbg_mhfplshhandle_free: (a: number, b: number) => void;
     readonly __wbg_molhandle_free: (a: number, b: number) => void;
+    readonly __wbg_rdkitsearchindex_free: (a: number, b: number) => void;
     readonly add_hydrogens: (a: number) => number;
     readonly admet_profile_json: (a: number, b: number) => [number, number];
     readonly atom_pair_bitvec: (a: number) => [number, number];
@@ -2951,6 +3019,7 @@ export interface InitOutput {
     readonly get_bond_length_json: (a: number, b: number, c: number, d: number) => number;
     readonly get_descriptors_json: (a: number) => [number, number];
     readonly get_dihedral_json: (a: number, b: number, c: number, d: number, e: number, f: number) => any;
+    readonly get_rdkit_descriptors_json: (a: number) => [number, number];
     readonly getaway_descriptors_json: (a: number) => [number, number];
     readonly hdf_json: (a: number, b: number, c: number, d: bigint) => [number, number];
     readonly identify_functional_groups: (a: number) => [number, number];
@@ -3082,6 +3151,7 @@ export interface InitOutput {
     readonly molhandle_pains_passes: (a: number) => number;
     readonly molhandle_pka_acid_value: (a: number) => number;
     readonly molhandle_pka_base_value: (a: number) => number;
+    readonly molhandle_potential_stereocenter_indices: (a: number) => [number, number];
     readonly molhandle_qed: (a: number) => number;
     readonly molhandle_randic_index: (a: number) => number;
     readonly molhandle_reos_passes: (a: number) => number;
@@ -3133,9 +3203,16 @@ export interface InitOutput {
     readonly rdkit_ecfp_config_chiral_bitvec: (a: number, b: number, c: number) => [number, number, number, number];
     readonly rdkit_ecfp_config_chiral_detail_json: (a: number, b: number, c: number) => [number, number, number, number];
     readonly rdkit_ecfp_config_detail_json: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly rdkit_nearest_neighbors_json: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly rdkit_path_bitvec: (a: number) => [number, number];
     readonly rdkit_rdk_bitvec: (a: number) => [number, number];
     readonly rdkit_torsion_bitvec: (a: number) => [number, number];
+    readonly rdkitsearchindex_is_empty: (a: number) => number;
+    readonly rdkitsearchindex_len: (a: number) => number;
+    readonly rdkitsearchindex_new: (a: number, b: number) => [number, number, number];
+    readonly rdkitsearchindex_search_json: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly rdkitsearchindex_search_json_precise: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly rdkitsearchindex_search_json_threshold_precise: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly reaction_document_json_v1: (a: number, b: number) => [number, number, number, number];
     readonly reaction_document_to_rxn_v1: (a: number, b: number) => [number, number, number, number];
     readonly reaction_smarts_match: (a: number, b: number, c: number, d: number) => [number, number, number];

package/chematic_wasm.js

@@ -961,6 +961,16 @@ export class MolHandle {
         const ret = wasm.molhandle_pka_base_value(this.__wbg_ptr);
         return ret;
     }
+    /**
+     * Atom indices of potential tetrahedral stereocenters.
+     * @returns {Uint32Array}
+     */
+    potential_stereocenter_indices() {
+        const ret = wasm.molhandle_potential_stereocenter_indices(this.__wbg_ptr);
+        var v1 = getArrayU32FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
     /**
      * Quantitative Estimate of Drug-likeness (QED); range [0, 1].
      * @returns {number}
@@ -1079,6 +1089,124 @@ export class MolHandle {
 }
 if (Symbol.dispose) MolHandle.prototype[Symbol.dispose] = MolHandle.prototype.free;
 
+/**
+ * Reusable prepared index for the RDKit-compatible Morgan profile.
+ *
+ * Build one index per input chunk (the WASM batch limit is 1,024 molecules),
+ * then call [`RdkitSearchIndex::search_json`] for multiple queries without
+ * reparsing or refingerprinting the database.
+ */
+export class RdkitSearchIndex {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        RdkitSearchIndexFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_rdkitsearchindex_free(ptr, 0);
+    }
+    /**
+     * Whether the prepared index contains no molecules.
+     * @returns {boolean}
+     */
+    is_empty() {
+        const ret = wasm.rdkitsearchindex_is_empty(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Number of molecules in this chunk.
+     * @returns {number}
+     */
+    len() {
+        const ret = wasm.rdkitsearchindex_len(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Build an index from a JSON array of SMILES strings.
+     * @param {string} db_smiles_json
+     */
+    constructor(db_smiles_json) {
+        const ptr0 = passStringToWasm0(db_smiles_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.rdkitsearchindex_new(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0];
+        RdkitSearchIndexFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Search the prepared index with a query SMILES.
+     * @param {string} query_smiles
+     * @param {number} k
+     * @returns {string}
+     */
+    search_json(query_smiles, k) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ptr0 = passStringToWasm0(query_smiles, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.rdkitsearchindex_search_json(this.__wbg_ptr, ptr0, len0, k);
+            deferred2_0 = ret[0];
+            deferred2_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Search without the historical six-decimal JSON score truncation.
+     *
+     * This opt-in endpoint is for exact parity measurements. Callers that
+     * need the stable historical wire format should continue using
+     * RdkitSearchIndex::search_json.
+     * @param {string} query_smiles
+     * @param {number} k
+     * @returns {string}
+     */
+    search_json_precise(query_smiles, k) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ptr0 = passStringToWasm0(query_smiles, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.rdkitsearchindex_search_json_precise(this.__wbg_ptr, ptr0, len0, k);
+            deferred2_0 = ret[0];
+            deferred2_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Search with an inclusive Tanimoto threshold and precise JSON scores.
+     * A threshold of `0.0` includes zero-score candidates.
+     * @param {string} query_smiles
+     * @param {number} threshold
+     * @param {number} k
+     * @returns {string}
+     */
+    search_json_threshold_precise(query_smiles, threshold, k) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ptr0 = passStringToWasm0(query_smiles, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.rdkitsearchindex_search_json_threshold_precise(this.__wbg_ptr, ptr0, len0, threshold, k);
+            deferred2_0 = ret[0];
+            deferred2_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) RdkitSearchIndex.prototype[Symbol.dispose] = RdkitSearchIndex.prototype.free;
+
 /**
  * Return a copy of the molecule with all implicit hydrogens converted to explicit H atoms.
  * @param {MolHandle} mol
@@ -2998,6 +3126,31 @@ export function get_dihedral_json(smiles, a, b, c, d) {
     return ret;
 }
 
+/**
+ * RDKit-compatibility descriptor profile as JSON.
+ *
+ * This is deliberately separate from [`get_descriptors_json`]: the latter is
+ * the historical native profile, while this profile uses the opt-in RDKit
+ * molecular-weight, HBA, and aromatic-ring implementations.  Keeping the
+ * boundary explicit prevents a compatibility correction from silently
+ * changing the browser's native descriptor contract.
+ * @param {MolHandle} mol
+ * @returns {string}
+ */
+export function get_rdkit_descriptors_json(mol) {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        _assertClass(mol, MolHandle);
+        const ret = wasm.get_rdkit_descriptors_json(mol.__wbg_ptr);
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
 /**
  * Compute GETAWAY descriptors (GEometry, Topology and Atom-Weights AssemblY) from 3D coords.
  *
@@ -5594,6 +5747,36 @@ export function rdkit_ecfp_config_detail_json(mol, radius, nbits) {
     }
 }
 
+/**
+ * Find the k nearest neighbours using the RDKit-compatible Morgan/ECFP4
+ * profile. This is intentionally separate from [`nearest_neighbors_json`],
+ * whose historical contract uses chematic's native ECFP4 profile.
+ *
+ * Returns JSON with the original database indices and six-decimal Tanimoto
+ * scores. Any RDKit-profile preprocessing failure is returned as an error;
+ * this API never falls back to the native profile.
+ * @param {string} query_smiles
+ * @param {string} db_smiles_json
+ * @param {number} k
+ * @returns {string}
+ */
+export function rdkit_nearest_neighbors_json(query_smiles, db_smiles_json, k) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(query_smiles, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(db_smiles_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.rdkit_nearest_neighbors_json(ptr0, len0, ptr1, len1, k);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Compute the RDKit-compatible Daylight-like path fingerprint as a bit-packed
  * byte vector (256 bytes = 2048 bits). This is the WASM counterpart of the
@@ -7707,6 +7890,9 @@ const MhfpLshHandleFinalization = (typeof FinalizationRegistry === 'undefined')
 const MolHandleFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_molhandle_free(ptr, 1));
+const RdkitSearchIndexFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_rdkitsearchindex_free(ptr, 1));
 
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();

package/package.json

@@ -5,7 +5,7 @@
     "Kentaro Tanabe (kent-tokyo) <kent-tokyo@users.noreply.github.com>"
   ],
   "description": "WebAssembly bindings for chematic — use chematic from JavaScript/TypeScript",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",