openchemlib-search-wasm 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/LICENSE +275 -0
  2. package/README.md +172 -0
  3. package/lib/index.d.ts +42 -0
  4. package/lib/index.d.ts.map +1 -0
  5. package/lib/index.js +55 -0
  6. package/lib/index.js.map +1 -0
  7. package/lib/jpath.d.ts +28 -0
  8. package/lib/jpath.d.ts.map +1 -0
  9. package/lib/jpath.js +73 -0
  10. package/lib/jpath.js.map +1 -0
  11. package/lib/runSearch.d.ts +41 -0
  12. package/lib/runSearch.d.ts.map +1 -0
  13. package/lib/runSearch.js +50 -0
  14. package/lib/runSearch.js.map +1 -0
  15. package/lib/scan.d.ts +40 -0
  16. package/lib/scan.d.ts.map +1 -0
  17. package/lib/scan.js +103 -0
  18. package/lib/scan.js.map +1 -0
  19. package/lib/similaritySearch.d.ts +28 -0
  20. package/lib/similaritySearch.d.ts.map +1 -0
  21. package/lib/similaritySearch.js +86 -0
  22. package/lib/similaritySearch.js.map +1 -0
  23. package/lib/substructureSearch.d.ts +26 -0
  24. package/lib/substructureSearch.d.ts.map +1 -0
  25. package/lib/substructureSearch.js +81 -0
  26. package/lib/substructureSearch.js.map +1 -0
  27. package/lib/types.d.ts +169 -0
  28. package/lib/types.d.ts.map +1 -0
  29. package/lib/types.js +30 -0
  30. package/lib/types.js.map +1 -0
  31. package/lib/wasm/load.d.ts +10 -0
  32. package/lib/wasm/load.d.ts.map +1 -0
  33. package/lib/wasm/load.js +42 -0
  34. package/lib/wasm/load.js.map +1 -0
  35. package/package.json +80 -0
  36. package/src/index.ts +68 -0
  37. package/src/jpath.ts +77 -0
  38. package/src/runSearch.ts +99 -0
  39. package/src/scan.ts +141 -0
  40. package/src/similaritySearch.ts +104 -0
  41. package/src/substructureSearch.ts +97 -0
  42. package/src/types.ts +197 -0
  43. package/src/wasm/load.ts +50 -0
  44. package/wasm/data.d.ts +2 -0
  45. package/wasm/data.js +3 -0
  46. package/wasm/runtime.d.ts +25 -0
  47. package/wasm/runtime.js +30 -0
package/lib/types.d.ts ADDED
@@ -0,0 +1,169 @@
1
+ /**
2
+ * The status of one entry of a `substructureSearch` result buffer.
3
+ *
4
+ * `unprocessed` is what a scan that stopped on `limit` or on `onStep` leaves behind.
5
+ */
6
+ export declare const SubstructureResult: Readonly<{
7
+ /** Not tested yet. */
8
+ unprocessed: 0;
9
+ /** The query is a substructure of this molecule. */
10
+ match: 1;
11
+ /** The query is not a substructure of this molecule. */
12
+ noMatch: 2;
13
+ /** The idcode could not be parsed; nothing was tested. */
14
+ unparsable: 3;
15
+ }>;
16
+ /**
17
+ * The similarity of one entry of a `similaritySearch` result buffer: `NaN` while the entry
18
+ * has not been compared yet, `-1` when its idcode could not be parsed, otherwise the Tanimoto
19
+ * coefficient in [0, 1]. `0` is a legitimate similarity, which is why the "not yet" sentinel is
20
+ * `NaN` and not `0`.
21
+ */
22
+ export declare const SimilarityResult: Readonly<{
23
+ /** Not compared yet. */
24
+ unprocessed: number;
25
+ /** The idcode could not be parsed; nothing was compared. */
26
+ unparsable: -1;
27
+ }>;
28
+ /** What a search fills: bytes for a substructure scan, floats for a similarity one. */
29
+ export type ResultBuffer = Uint8Array | Float32Array;
30
+ /**
31
+ * Which search to run. The names are the ones `openchemlib-utils` and `openchemlib-sqlite` already
32
+ * use for the same two searches.
33
+ */
34
+ export type SearchMode = 'substructure' | 'similarity';
35
+ /** What a search has done so far, reported to `onStep`. */
36
+ export interface SearchStep {
37
+ /**
38
+ * The buffer being filled, so a caller can render as the scan runs. It is the same buffer at
39
+ * every step, and the one the result carries.
40
+ */
41
+ result: ResultBuffer;
42
+ /** How many entries have been scanned. */
43
+ processed: number;
44
+ /** How many entries there are. */
45
+ total: number;
46
+ /** How many of the scanned entries matched. */
47
+ matched: number;
48
+ /** How many of them could not be parsed. */
49
+ unparsable: number;
50
+ /** Milliseconds since the search started. */
51
+ elapsed: number;
52
+ }
53
+ /** What both searches take. */
54
+ export interface SearchOptions {
55
+ /**
56
+ * Where the idcode sits in an entry, as a dot-separated jpath: `idCode`, `molecule.idCode`,
57
+ * `spectra.0.idCode`. Ignored when the entries are idcodes rather than objects.
58
+ * @default 'idCode'
59
+ */
60
+ jpath?: string;
61
+ /**
62
+ * Called after each step with what has been scanned so far. Return `false` to stop the search.
63
+ *
64
+ * It is synchronous and the scan does not yield: chunking for a responsive main thread is the
65
+ * caller's to do, by slicing the array across calls or running this in a worker.
66
+ */
67
+ onStep?: (step: SearchStep) => boolean | void;
68
+ /**
69
+ * How many entries one step covers. Only meaningful alongside `onStep` or `limit`; without
70
+ * either, the whole array is scanned in a single call.
71
+ * @default 4096 for a substructure search, 128 for a similarity one — both about 100 ms
72
+ */
73
+ stepSize?: number;
74
+ /**
75
+ * Whether to collect `matches` and `indexes`. Turn it off to fill `result` alone, which is what a
76
+ * worker writing into a shared buffer wants: on a corpus that matches often, collecting allocates
77
+ * one array slot per hit for nothing.
78
+ * @default true
79
+ */
80
+ collect?: boolean;
81
+ }
82
+ export interface SubstructureSearchOptions extends SearchOptions {
83
+ /**
84
+ * Stop once this many matches have been found. The scan stops at the end of the step that reached
85
+ * it, so `matches` can overshoot by less than one step before being cut back to `limit`.
86
+ * @default Number.MAX_SAFE_INTEGER
87
+ */
88
+ limit?: number;
89
+ }
90
+ export interface SimilaritySearchOptions extends SearchOptions {
91
+ /**
92
+ * The Tanimoto coefficient at or above which an entry counts as a match.
93
+ * @default 0
94
+ */
95
+ threshold?: number;
96
+ /**
97
+ * Keep only the `limit` most similar entries. Unlike a substructure search this cannot stop the
98
+ * scan early — a better match may still be coming — so it only decides how many are kept.
99
+ * @default Number.MAX_SAFE_INTEGER
100
+ */
101
+ limit?: number;
102
+ }
103
+ /** What every search returns, whatever it computed. */
104
+ export interface SearchResult<Entry> {
105
+ /**
106
+ * The entries that matched, in the order the search defines: input order for a substructure
107
+ * search, most similar first for a similarity one.
108
+ */
109
+ matches: Entry[];
110
+ /**
111
+ * Their positions in the input, aligned with `matches`. Cheaper than the entries to post back
112
+ * from a worker, whose caller already holds them.
113
+ */
114
+ indexes: number[];
115
+ /**
116
+ * How many of the scanned entries matched. Larger than `matches.length` when `limit` cut the
117
+ * list back, and the only count there is when `collect` is off.
118
+ */
119
+ matched: number;
120
+ /** How many idcodes could not be parsed. */
121
+ unparsable: number;
122
+ /** How many entries were scanned. Short of `total` when the search stopped early. */
123
+ processed: number;
124
+ /** How many entries there were. */
125
+ total: number;
126
+ /** How long the search took, in milliseconds. */
127
+ elapsed: number;
128
+ /** True when `limit` or `onStep` stopped the scan before the end. */
129
+ stopped: boolean;
130
+ }
131
+ /**
132
+ * `matches` and `indexes` are in **input order**, and `limit` therefore keeps the first matches
133
+ * rather than an arbitrary subset. A caller that has ordered its entries by a preference — cheapest
134
+ * first, lightest first — gets that preference back, which is what makes `limit` a first page
135
+ * rather than a sample.
136
+ */
137
+ export interface SubstructureSearchResult<Entry> extends SearchResult<Entry> {
138
+ /**
139
+ * One {@link SubstructureResult} code per entry, in input order. Entries past `processed` are
140
+ * left `unprocessed` when the search stopped early.
141
+ */
142
+ result: Uint8Array;
143
+ }
144
+ /** `matches` is ordered by descending similarity, so `limit` keeps the best. */
145
+ export interface SimilaritySearchResult<Entry> extends SearchResult<Entry> {
146
+ /**
147
+ * The Tanimoto coefficient of each entry of `matches`, in the same order — so the two arrays are
148
+ * read together. It is a separate array rather than a field on the entry because the entries are
149
+ * the caller's own objects: copying each one just to hang a number on it would allocate the whole
150
+ * result set a second time.
151
+ */
152
+ similarities: Float32Array;
153
+ /** One coefficient per entry, in input order, with the {@link SimilarityResult} sentinels. */
154
+ result: Float32Array;
155
+ }
156
+ /** The shape TeaVM exports from the WasmGC module. Both take a half-open `[from, to)` range. */
157
+ export interface OCLSearch {
158
+ Search: {
159
+ /** Returns how many molecules in the range contain the fragment. */
160
+ ssSearch: (idCodeQuery: string, idCodes: string[], result: Uint8Array, from: number, to: number) => number;
161
+ /** Returns how many molecules in the range were parsed and compared. */
162
+ similaritySearch: (idCodeQuery: string, idCodes: string[], result: Float32Array, from: number, to: number) => number;
163
+ /** Returns how many molecules in the range were parsed and fingerprinted. */
164
+ getIndexes: (idCodes: string[], result: Int32Array, from: number, to: number) => number;
165
+ };
166
+ }
167
+ /** How many 32-bit words one molecule's FragFp fingerprint occupies. */
168
+ export declare const INDEX_WORDS = 16;
169
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/lib/types.js ADDED
@@ -0,0 +1,30 @@
1
+ /**
2
+ * The status of one entry of a `substructureSearch` result buffer.
3
+ *
4
+ * `unprocessed` is what a scan that stopped on `limit` or on `onStep` leaves behind.
5
+ */
6
+ export const SubstructureResult = Object.freeze({
7
+ /** Not tested yet. */
8
+ unprocessed: 0,
9
+ /** The query is a substructure of this molecule. */
10
+ match: 1,
11
+ /** The query is not a substructure of this molecule. */
12
+ noMatch: 2,
13
+ /** The idcode could not be parsed; nothing was tested. */
14
+ unparsable: 3,
15
+ });
16
+ /**
17
+ * The similarity of one entry of a `similaritySearch` result buffer: `NaN` while the entry
18
+ * has not been compared yet, `-1` when its idcode could not be parsed, otherwise the Tanimoto
19
+ * coefficient in [0, 1]. `0` is a legitimate similarity, which is why the "not yet" sentinel is
20
+ * `NaN` and not `0`.
21
+ */
22
+ export const SimilarityResult = Object.freeze({
23
+ /** Not compared yet. */
24
+ unprocessed: Number.NaN,
25
+ /** The idcode could not be parsed; nothing was compared. */
26
+ unparsable: -1,
27
+ });
28
+ /** How many 32-bit words one molecule's FragFp fingerprint occupies. */
29
+ export const INDEX_WORDS = 16;
30
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9C,sBAAsB;IACtB,WAAW,EAAE,CAAC;IACd,oDAAoD;IACpD,KAAK,EAAE,CAAC;IACR,wDAAwD;IACxD,OAAO,EAAE,CAAC;IACV,0DAA0D;IAC1D,UAAU,EAAE,CAAC;CACd,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC,GAAG;IACvB,4DAA4D;IAC5D,UAAU,EAAE,CAAC,CAAC;CACf,CAAC,CAAC;AAwKH,wEAAwE;AACxE,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC"}
@@ -0,0 +1,10 @@
1
+ import type { OCLSearch } from '../types.ts';
2
+ /**
3
+ * Loads and instantiates the embedded OpenChemLib WasmGC module. The module is compiled once and
4
+ * cached; subsequent calls return the same instance. Decoding uses only Web Platform APIs (atob +
5
+ * DecompressionStream), so Node and the browser take the same path, with no filesystem and no
6
+ * fetch — which is what lets a worker instantiate it from the bundle it was loaded from.
7
+ * @returns The module's exports.
8
+ */
9
+ export declare function loadOCL(): Promise<OCLSearch>;
10
+ //# sourceMappingURL=load.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/wasm/load.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAa7C;;;;;;GAMG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC,CAG5C"}
@@ -0,0 +1,42 @@
1
+ import { wasmGzipBase64 } from '../../wasm/data.js';
2
+ import { load } from '../../wasm/runtime.js';
3
+ let modulePromise;
4
+ /**
5
+ * The ceiling on the module's linear memory. The runtime otherwise declares the largest maximum it
6
+ * can — 2 GiB — for every instantiation, and a page that scans in eight workers declares eight of
7
+ * them. The module's own `teavm.memoryRequirements` section asks for 33 pages and 17 KB of static
8
+ * data, and the memory has never been observed to grow past its 33-page initial, so this is three
9
+ * orders of magnitude of headroom over anything measured.
10
+ */
11
+ const MAX_LINEAR_MEMORY = 256 * 1024 * 1024;
12
+ /**
13
+ * Loads and instantiates the embedded OpenChemLib WasmGC module. The module is compiled once and
14
+ * cached; subsequent calls return the same instance. Decoding uses only Web Platform APIs (atob +
15
+ * DecompressionStream), so Node and the browser take the same path, with no filesystem and no
16
+ * fetch — which is what lets a worker instantiate it from the bundle it was loaded from.
17
+ * @returns The module's exports.
18
+ */
19
+ export function loadOCL() {
20
+ modulePromise ??= instantiate();
21
+ return modulePromise;
22
+ }
23
+ async function instantiate() {
24
+ const wasmBytes = await gunzip(base64ToBytes(wasmGzipBase64));
25
+ const teavm = await load(wasmBytes, { memory: { maxSize: MAX_LINEAR_MEMORY } });
26
+ return teavm.exports;
27
+ }
28
+ function base64ToBytes(base64) {
29
+ const binary = atob(base64);
30
+ const bytes = new Uint8Array(binary.length);
31
+ for (let i = 0; i < binary.length; i++) {
32
+ bytes[i] = binary.codePointAt(i) ?? 0;
33
+ }
34
+ return bytes;
35
+ }
36
+ async function gunzip(bytes) {
37
+ const stream = new Blob([bytes])
38
+ .stream()
39
+ .pipeThrough(new DecompressionStream('gzip'));
40
+ return new Uint8Array(await new Response(stream).arrayBuffer());
41
+ }
42
+ //# sourceMappingURL=load.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/wasm/load.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAG7C,IAAI,aAA6C,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,iBAAiB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,UAAU,OAAO;IACrB,aAAa,KAAK,WAAW,EAAE,CAAC;IAChC,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,KAAK,UAAU,WAAW;IACxB,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,CAAC,OAA+B,CAAC;AAC/C,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,MAAM,CACnB,KAA8B;IAE9B,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;SAC7B,MAAM,EAAE;SACR,WAAW,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,OAAO,IAAI,UAAU,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAClE,CAAC"}
package/package.json ADDED
@@ -0,0 +1,80 @@
1
+ {
2
+ "name": "openchemlib-search-wasm",
3
+ "version": "1.0.0",
4
+ "type": "module",
5
+ "description": "Batch substructure and similarity search over idcodes, with OpenChemLib compiled to WebAssembly",
6
+ "keywords": [
7
+ "chemistry",
8
+ "molecule",
9
+ "substructure",
10
+ "similarity",
11
+ "openchemlib",
12
+ "webassembly"
13
+ ],
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/cheminfo/openchemlib-search-wasm.git"
17
+ },
18
+ "bugs": {
19
+ "url": "https://github.com/cheminfo/openchemlib-search-wasm/issues"
20
+ },
21
+ "homepage": "https://github.com/cheminfo/openchemlib-search-wasm#readme",
22
+ "author": "Luc Patiny",
23
+ "engines": {
24
+ "node": ">=22"
25
+ },
26
+ "scripts": {
27
+ "benchmark": "node benchmark/substructureSearch.js",
28
+ "benchmark-scan": "node benchmark/scan.mjs",
29
+ "build": "npm run build-wasm && npm run build-embed",
30
+ "build-embed": "node build/embed-wasm.mjs",
31
+ "build-wasm": "node scripts/build-wasm.mjs",
32
+ "check-types": "tsc --noEmit",
33
+ "clean": "rimraf coverage lib",
34
+ "dataset": "node scripts/build-dataset.mjs",
35
+ "dev": "vite dev dev",
36
+ "eslint": "eslint .",
37
+ "eslint-fix": "eslint . --fix",
38
+ "prepack": "npm run tsc",
39
+ "prettier": "prettier --check .",
40
+ "prettier-write": "prettier --write .",
41
+ "test": "npm run test-only && npm run check-types && npm run eslint && npm run prettier",
42
+ "test-only": "vitest run --coverage",
43
+ "tsc": "npm run clean && npm run tsc-build",
44
+ "tsc-build": "tsc --project tsconfig.build.json"
45
+ },
46
+ "exports": {
47
+ ".": "./lib/index.js"
48
+ },
49
+ "imports": {
50
+ "#lib": "./src/index.ts"
51
+ },
52
+ "files": [
53
+ "lib",
54
+ "src",
55
+ "wasm"
56
+ ],
57
+ "license": "BSD-3-Clause",
58
+ "devDependencies": {
59
+ "@types/benchmark": "^2.1.5",
60
+ "@types/node": "^25.6.0",
61
+ "@types/react": "^19.2.2",
62
+ "@types/react-dom": "^19.2.2",
63
+ "@vitejs/plugin-react": "^5.1.0",
64
+ "@vitest/coverage-istanbul": "^4.1.11",
65
+ "@zakodium/tsconfig": "^1.0.5",
66
+ "benchmark": "^2.1.4",
67
+ "binaryen": "^132.0.0",
68
+ "eslint": "^9.39.4",
69
+ "eslint-config-cheminfo-typescript": "^22.1.0",
70
+ "globals": "^17.6.0",
71
+ "openchemlib": "^9.22.1",
72
+ "prettier": "^3.6.2",
73
+ "react": "^19.2.0",
74
+ "react-dom": "^19.2.0",
75
+ "rimraf": "^6.0.1",
76
+ "typescript": "^6.0.0",
77
+ "vite": "^8.2.2",
78
+ "vitest": "^4.1.11"
79
+ }
80
+ }
package/src/index.ts ADDED
@@ -0,0 +1,68 @@
1
+ import { buildIndexes } from './scan.ts';
2
+ import { INDEX_WORDS } from './types.ts';
3
+
4
+ export { substructureSearch } from './substructureSearch.ts';
5
+ export { similaritySearch } from './similaritySearch.ts';
6
+ export { INDEX_WORDS } from './types.ts';
7
+ export type {
8
+ ResultBuffer,
9
+ SearchMode,
10
+ SearchOptions,
11
+ SearchResult,
12
+ SearchStep,
13
+ SimilaritySearchOptions,
14
+ SimilaritySearchResult,
15
+ SubstructureSearchOptions,
16
+ SubstructureSearchResult,
17
+ } from './types.ts';
18
+ export { SimilarityResult, SubstructureResult } from './types.ts';
19
+
20
+ /**
21
+ * Builds the 512-bit FragFp fingerprint of one idcode, as sixteen 32-bit words.
22
+ *
23
+ * This is what a fingerprint table is made of, and building it is the expensive part of importing a
24
+ * library: about 897 µs per molecule, against 4484 µs for `openchemlib-js` — six minutes instead of
25
+ * thirty for 400,000 molecules. Calling this once per molecule costs the same as one batched call,
26
+ * so a row-at-a-time importer needs no restructuring to get that.
27
+ *
28
+ * The words are in the same order `openchemlib-js`'s `createIndex` produces, so they are
29
+ * interchangeable with an existing table, and a `BigInt64Array` view over the result is exactly the
30
+ * eight columns `openchemlib-sqlite` stores — no conversion, no copy:
31
+ *
32
+ * ```js
33
+ * const index = getIndex(idCode);
34
+ * const columns = new BigInt64Array(index.buffer, index.byteOffset, 8); // ss_index0..7
35
+ * insert.run(mw, entryId, ...columns);
36
+ * ```
37
+ * @param idCode - The molecule to fingerprint, as an idcode.
38
+ * @returns Sixteen words. An idcode that will not parse gives sixteen zeros, which no non-empty
39
+ * query is a subset of, so it can never be a false candidate.
40
+ */
41
+ export function getIndex(idCode: string): Int32Array {
42
+ const result = new Int32Array(INDEX_WORDS);
43
+ buildIndexes([idCode], result, 0, 1);
44
+ return result;
45
+ }
46
+
47
+ /**
48
+ * Builds the 512-bit FragFp fingerprint of every idcode, sixteen 32-bit words each.
49
+ *
50
+ * See {@link getIndex} for the one-molecule form, which costs the same per molecule: the 512 key
51
+ * fragments OpenChemLib matches against are parsed once and held for the module's lifetime, so
52
+ * there is nothing for a batch to amortise.
53
+ *
54
+ * The fingerprints are written into one buffer and returned as a view per molecule, so the array
55
+ * costs one allocation rather than one per molecule, and every view is still 8-byte aligned and can
56
+ * be read as the eight `BigInt64` columns {@link getIndex} shows.
57
+ * @param idCodes - The molecules to fingerprint, as idcodes.
58
+ * @returns One sixteen-word view per idcode, in order.
59
+ */
60
+ export function getIndexes(idCodes: string[]): Int32Array[] {
61
+ const all = new Int32Array(idCodes.length * INDEX_WORDS);
62
+ buildIndexes(idCodes, all, 0, idCodes.length);
63
+ const indexes = new Array<Int32Array>(idCodes.length);
64
+ for (let i = 0; i < idCodes.length; i++) {
65
+ indexes[i] = all.subarray(i * INDEX_WORDS, (i + 1) * INDEX_WORDS);
66
+ }
67
+ return indexes;
68
+ }
package/src/jpath.ts ADDED
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Reads the idcode every entry carries, following a jpath.
3
+ *
4
+ * The jpath is the dot-separated form the rest of the ecosystem uses (`get-jpaths`,
5
+ * `derived-props`): `idCode`, `molecule.idCode`, `spectra.0.idCode`. A numeric segment indexes an
6
+ * array, because `array['0']` and `array[0]` are the same property.
7
+ *
8
+ * The path is split once and walked with a plain loop per entry, so a scan of 400,000 entries costs
9
+ * one string split rather than 400,000 of them.
10
+ * @param entries - The entries to read.
11
+ * @param jpath - Where the idcode sits in each entry.
12
+ * @returns One idcode per entry, in order. An entry with no string at the jpath gives an empty
13
+ * string, which the scan reports as unparsable like any other idcode it cannot read.
14
+ * @throws {Error} If no entry at all has a string there, which means the jpath is wrong rather than
15
+ * the data.
16
+ */
17
+ export function readIdCodes(
18
+ entries: readonly unknown[],
19
+ jpath: string,
20
+ ): string[] {
21
+ const segments = jpath.split('.');
22
+ const idCodes = new Array<string>(entries.length);
23
+ let found = 0;
24
+
25
+ if (segments.length === 1) {
26
+ const key = segments[0] as string;
27
+ for (let i = 0; i < entries.length; i++) {
28
+ const value = (entries[i] as Record<string, unknown> | null)?.[key];
29
+ if (typeof value === 'string') {
30
+ idCodes[i] = value;
31
+ found++;
32
+ } else {
33
+ idCodes[i] = '';
34
+ }
35
+ }
36
+ } else {
37
+ for (let i = 0; i < entries.length; i++) {
38
+ let value: unknown = entries[i];
39
+ for (const segment of segments) {
40
+ if (value === null || value === undefined) break;
41
+ value = (value as Record<string, unknown>)[segment];
42
+ }
43
+ if (typeof value === 'string') {
44
+ idCodes[i] = value;
45
+ found++;
46
+ } else {
47
+ idCodes[i] = '';
48
+ }
49
+ }
50
+ }
51
+
52
+ if (found === 0 && entries.length > 0) {
53
+ throw new Error(
54
+ `no entry holds a string at jpath "${jpath}": pass the jpath option if the idcode is` +
55
+ ' somewhere else',
56
+ );
57
+ }
58
+ return idCodes;
59
+ }
60
+
61
+ /**
62
+ * Turns whatever the caller passed into the array of idcodes the scan reads.
63
+ *
64
+ * An array of idcodes is used as it is — that is the hot path a worker scanning a decoded chunk
65
+ * takes, and copying it would allocate one reference per molecule for nothing.
66
+ * @param entries - Idcodes, or entries carrying one at `jpath`.
67
+ * @param jpath - Where the idcode sits in an entry.
68
+ * @returns The idcodes to scan.
69
+ */
70
+ export function toIdCodes(
71
+ entries: readonly unknown[],
72
+ jpath: string,
73
+ ): string[] {
74
+ if (entries.length === 0) return [];
75
+ if (typeof entries[0] === 'string') return entries as unknown as string[];
76
+ return readIdCodes(entries, jpath);
77
+ }
@@ -0,0 +1,99 @@
1
+ import { checkQuery, scanRange } from './scan.ts';
2
+ import type { ResultBuffer, SearchMode, SearchStep } from './types.ts';
3
+
4
+ /**
5
+ * How many entries one step covers when the caller asked to hear about the scan but did not say how
6
+ * often. Sized from the measured cost of a molecule — ~22 µs to match a fragment, ~947 µs to build
7
+ * a fingerprint — so a step lands near 100 ms either way.
8
+ */
9
+ const DEFAULT_STEP = { substructure: 4096, similarity: 128 };
10
+
11
+ /** What a mode does with the entries a step just wrote. */
12
+ export interface StepTally {
13
+ /** Matches counted so far. */
14
+ matched: number;
15
+ /** Idcodes that could not be parsed. */
16
+ unparsable: number;
17
+ }
18
+
19
+ export interface RunSearchParams {
20
+ mode: SearchMode;
21
+ idCodeQuery: string;
22
+ idCodes: string[];
23
+ /** The buffer the scan fills, already reset to the mode's "not yet" value. */
24
+ result: ResultBuffer;
25
+ /** Updated as the scan goes, and read back into the returned counts. */
26
+ tally: StepTally;
27
+ /**
28
+ * Tallies `result[from .. to)` into `tally`, collecting whatever the mode collects.
29
+ * @returns True when the scan has everything it was asked for and should stop.
30
+ */
31
+ collectRange: (from: number, to: number) => boolean;
32
+ stepSize: number | undefined;
33
+ onStep: ((step: SearchStep) => boolean | void) | undefined;
34
+ /** True when the mode can stop before the end, so the scan must be cut into steps. */
35
+ stoppable: boolean;
36
+ }
37
+
38
+ /**
39
+ * Drives a scan, one step at a time, and reports it.
40
+ *
41
+ * A step is a single call into WebAssembly over a range of the array. Cutting the scan up is free —
42
+ * 800 chunked calls measure the same as one call over the whole corpus — so the only reason to do
43
+ * it is to hear about the scan or to stop it, and a search that wants neither runs as one call.
44
+ * @param params - The mode, the query, the buffer to fill and what to do with each step.
45
+ * @returns How far the scan got, how long it took and whether it stopped early.
46
+ */
47
+ export function runSearch(params: RunSearchParams): {
48
+ processed: number;
49
+ elapsed: number;
50
+ stopped: boolean;
51
+ } {
52
+ const {
53
+ mode,
54
+ idCodeQuery,
55
+ idCodes,
56
+ result,
57
+ tally,
58
+ collectRange,
59
+ onStep,
60
+ stepSize,
61
+ stoppable,
62
+ } = params;
63
+
64
+ checkQuery(mode, idCodeQuery);
65
+
66
+ const total = idCodes.length;
67
+ const stepped = onStep !== undefined || stoppable;
68
+ const step = Math.max(1, stepSize ?? (stepped ? DEFAULT_STEP[mode] : total));
69
+
70
+ const started = performance.now();
71
+ let processed = 0;
72
+ let stopped = false;
73
+
74
+ while (processed < total) {
75
+ const to = Math.min(processed + step, total);
76
+ scanRange(mode, idCodeQuery, idCodes, result, processed, to);
77
+ const enough = collectRange(processed, to);
78
+ processed = to;
79
+
80
+ if (enough) {
81
+ stopped = processed < total;
82
+ break;
83
+ }
84
+ const goOn = onStep?.({
85
+ result,
86
+ processed,
87
+ total,
88
+ matched: tally.matched,
89
+ unparsable: tally.unparsable,
90
+ elapsed: performance.now() - started,
91
+ });
92
+ if (goOn === false) {
93
+ stopped = processed < total;
94
+ break;
95
+ }
96
+ }
97
+
98
+ return { processed, elapsed: performance.now() - started, stopped };
99
+ }