openchemlib-search-wasm 1.1.0 → 2.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.
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # openchemlib-search-wasm
2
2
 
3
- Batch substructure search, batch similarity search and FragFp fingerprints over arrays of
4
- OpenChemLib idcodes — with OpenChemLib compiled to WebAssembly.
3
+ Batch substructure search, batch similarity search, FragFp fingerprints and identity hashes over
4
+ arrays of OpenChemLib idcodes — with OpenChemLib compiled to WebAssembly.
5
5
 
6
6
  ## Install
7
7
 
@@ -30,9 +30,29 @@ similaritySearch<Entry>(idCodeQuery: string, entries: Entry[],
30
30
  getIndex(idCode: string): Int32Array;
31
31
  getIndexes(idCodes: string[]): Int32Array[];
32
32
 
33
- // the 64-bit hash a molecule keeps across its tautomers and stereoisomers
34
- getNoStereoTautomerHash(idCode: string, options?: TautomerHashOptions): bigint;
35
- getNoStereoTautomerHashes(idCodes: string[], options?: TautomerHashOptions): BigInt64Array;
33
+ // the 64-bit hash a molecule keeps across its stereoisomers
34
+ getNoStereoHash(idCode: string, options?: HashOptions): bigint;
35
+ getNoStereoHashes(idCodes: string[], options?: HashOptions): BigInt64Array;
36
+
37
+ // the same, across its tautomers as well
38
+ getNoStereoTautomerHash(idCode: string, options?: HashOptions): bigint;
39
+ getNoStereoTautomerHashes(idCodes: string[], options?: HashOptions): BigInt64Array;
40
+
41
+ // the same two canonical forms as idcodes, for a column that stores the form itself
42
+ getNoStereoIdCode(idCode: string, options?: HashOptions): string;
43
+ getNoStereoIdCodes(idCodes: string[], options?: HashOptions): string[];
44
+ getNoStereoTautomerIdCode(idCode: string, options?: HashOptions): string;
45
+ getNoStereoTautomerIdCodes(idCodes: string[], options?: HashOptions): string[];
46
+
47
+ // a hash as the 16 hex digits that cross an API, and back
48
+ hashToHex(hash: bigint): string;
49
+ hexToHash(hex: string): bigint;
50
+
51
+ // the hash of a canonical idcode you already hold, without canonizing again
52
+ strongHash(idCode: string): bigint;
53
+
54
+ // where OpenChemLib's own diagnostics go; nothing is printed by default
55
+ setLogHandler(handler: LogHandler | null): void;
36
56
  ```
37
57
 
38
58
  **Give it your objects and it gives them back.** An entry is an idcode or anything carrying one — a
@@ -140,36 +160,198 @@ const index = getIndex(idCode);
140
160
  const columns = new BigInt64Array(index.buffer, index.byteOffset, 8);
141
161
  ```
142
162
 
163
+ **Pass `byteOffset` and the length, as above.** `getIndexes` returns its views over one shared
164
+ buffer — offsets 0, 64, 128 and so on — so `new BigInt64Array(index.buffer)` is 8 columns only for
165
+ the first molecule and silently reads the first molecule's words for every other one. It is wrong in
166
+ a way nothing reports: the row is written, the index is built, and the screen then misses real hits.
167
+ `getIndex` on its own always sits at offset 0, which is exactly what makes the mistake survive
168
+ testing on one molecule.
169
+
143
170
  This is the expensive half of importing a library, and where the biggest speedup is.
144
171
 
145
- ## Tautomer hashes
172
+ ## Identity hashes
173
+
174
+ Two hashes, for the two things "the same compound" usually means. Both are OpenChemLib's own —
175
+ `CanonizerUtil.getNoStereoHash` and `CanonizerUtil.getNoStereoTautomerHash` — so both are the value
176
+ any other OpenChemLib build computes, and the tests check the fixture molecules against
177
+ `openchemlib` to prove it.
146
178
 
147
- `getNoStereoTautomerHash` is OpenChemLib's `CanonizerUtil.getNoStereoTautomerHash`: the molecule
148
- stripped of stereo information, reduced to its generic tautomer, canonized, and that idcode run
149
- through OpenChemLib's 64-bit hash. Every tautomer of a structure and every stereoisomer of it give
150
- the same value, so it is the column to key on when "the same compound" means the same constitution
151
- rather than the same drawing.
179
+ | | drops | keeps apart |
180
+ | ------------------------- | ---------------------------- | ------------- |
181
+ | `getNoStereoHash` | stereochemistry | the tautomers |
182
+ | `getNoStereoTautomerHash` | stereochemistry, tautomerism | — |
183
+
184
+ `getNoStereoHash` strips the molecule of stereo information, canonizes it, and runs that idcode
185
+ through OpenChemLib's 64-bit hash. Both enantiomers of a centre, and both isomers of a double bond,
186
+ give the same value — the one to key on when a record's stereochemistry is unreliable but the bonds
187
+ it was drawn with are not.
188
+
189
+ `getNoStereoTautomerHash` reduces the molecule to its generic tautomer first, so the keto and the
190
+ enol form of a compound land on the same key as well — the one to key on when "the same compound"
191
+ means the same constitution rather than the same drawing.
152
192
 
153
193
  ```js
154
- import { getNoStereoTautomerHash } from 'openchemlib-search-wasm';
194
+ import {
195
+ getNoStereoHash,
196
+ getNoStereoTautomerHash,
197
+ } from 'openchemlib-search-wasm';
198
+
199
+ // both enantiomers of 2-chlorobutane
200
+ getNoStereoHash('gJPHADILuTb@') === getNoStereoHash('gJPHADILuTd@'); // true
155
201
 
156
202
  // pentan-3-one drawn as the keto and as the enol form
203
+ getNoStereoHash('gGQ@@drmT@@') === getNoStereoHash('gGQ@@drsT@@'); // false
157
204
  getNoStereoTautomerHash('gGQ@@drmT@@') ===
158
205
  getNoStereoTautomerHash('gGQ@@drsT@@'); // true
159
206
  ```
160
207
 
161
- It is a signed 64-bit integer, which is exactly what an SQLite `INTEGER` column stores and indexes,
162
- so a `BigInt64Array` of hashes goes straight into one. An idcode that will not parse, or a molecule
163
- OpenChemLib cannot canonize, gets `NO_HASH` (`0n`).
208
+ Both are signed 64-bit integers, which is exactly what an SQLite `INTEGER` column stores and
209
+ indexes, so a `BigInt64Array` of hashes goes straight into one. An idcode that will not parse, or a
210
+ molecule OpenChemLib cannot canonize, gets `NO_HASH` (`0n`).
211
+
212
+ Both take `{ largestFragmentOnly: true }` to strip everything but the largest fragment and
213
+ neutralize it first, so a salt hashes as its parent structure.
214
+
215
+ ### The canonical form itself
216
+
217
+ Each hash is OpenChemLib's 64-bit StrongHasher over a canonical idcode, and that idcode is available
218
+ too — `getNoStereoIdCode` and `getNoStereoTautomerIdCode`, with `…IdCodes` batch forms. They are the
219
+ exact strings the hashes hash, computed by the same code, so the two can never disagree.
220
+
221
+ Prefer the hash for a column that is only ever compared: 8 bytes that an integer index handles,
222
+ against around 25 characters for a no-stereo idcode and roughly twice that for a tautomer one. Reach
223
+ for the idcode when you need the canonical form itself — to show it, to hand it to another
224
+ OpenChemLib, or because a 1-in-2^64 collision is not acceptable for what the column decides.
225
+
226
+ **A tautomer idcode is a key, not a structure.** Parsing one back gives a molecule with every
227
+ tautomeric bond normalized and pi-electron counts in its atom labels, not the compound.
228
+
229
+ ### Stereochemistry and coordinates
230
+
231
+ These functions canonize with the canonizer told to disregard stereochemistry, rather than by
232
+ stripping stereo from the molecule and canonizing that. The distinction matters because the module
233
+ parses idcodes without inventing coordinates: `stripStereoInformation()` turns an implicit
234
+ double-bond configuration into a cross bond, there is no stereo bond to turn without coordinates, and
235
+ the canonizer then assigns a configuration instead of dropping one. Measured over 400 real idcodes,
236
+ the stripping route disagreed with the answer a caller holding a molecule gets on 6 of them — turning
237
+ an unconfigured double bond into E, and flipping a Z one. So a compound drawn without its
238
+ double-bond stereo keyed differently from the same compound drawn with it, which is the one thing
239
+ these keys exist to prevent.
240
+
241
+ Disregarding stereo in the canonizer agrees with the coordinate-bearing answer on all 400 and costs
242
+ nothing. Inventing coordinates would also agree, and costs 19 times the parse.
243
+
244
+ **This changed the hashes in 2.0.0.** A column of `getNoStereoHash` or `getNoStereoTautomerHash`
245
+ values written by 1.x has to be rebuilt; around 1.5% of them were wrong, and which ones depends on
246
+ whether the molecule had an unconfigured stereogenic double bond.
247
+
248
+ ### Bounding the tautomer tail
249
+
250
+ The cost of a tautomer key is set by how many tautomers the molecule has, not by its size, and the
251
+ spread is enormous: over a drug-like fixture the median molecule takes 0.12 ms and one in a hundred
252
+ takes most of a second. `maxTautomers` is the ceiling OpenChemLib stops at, and lowering it bounds
253
+ that tail. `tautomerCounts` says which molecules ran into it — the only signal that a key came from
254
+ a truncated enumeration, and so may not be canonical:
255
+
256
+ ```js
257
+ const tautomerCounts = new Int32Array(idCodes.length);
258
+ const maxTautomers = 1000;
259
+ const keys = getNoStereoTautomerIdCodes(idCodes, {
260
+ maxTautomers,
261
+ tautomerCounts,
262
+ });
263
+
264
+ // keys[i] is not canonical where this holds — record it next to the key
265
+ const truncated = (i) => tautomerCounts[i] >= maxTautomers;
266
+ ```
267
+
268
+ Measured over 200 fixture idcodes:
269
+
270
+ | `maxTautomers` | median | p99 | slowest | whole batch | truncated |
271
+ | ---------------: | ------: | -----: | ------: | ----------: | --------: |
272
+ | 100000 (default) | 0.12 ms | 807 ms | 969 ms | 1824 ms | 2 |
273
+ | 10000 | 0.06 ms | 46 ms | 63 ms | 135 ms | 2 |
274
+ | 1000 | 0.06 ms | 3 ms | 4 ms | 33 ms | 2 |
275
+ | 100 | 0.06 ms | 1 ms | 1 ms | 17 ms | 8 |
276
+
277
+ At 1000 the slowest molecule is 242x cheaper and the batch 55x, and the same two molecules are
278
+ truncated as at the default — so the ceiling costs nothing on this fixture beyond what the default
279
+ already gave up on. Where it lands for your library is an empirical question: lower it, and count.
280
+
281
+ ### Getting both the key and its hash
282
+
283
+ `strongHash` is OpenChemLib's 64-bit hasher, and every `CanonizerUtil` hash is defined as that hasher
284
+ over a canonical idcode. So a caller that wants both forms asks for the idcode and hashes it, rather
285
+ than calling two functions that each canonize:
286
+
287
+ ```js
288
+ const idCode = getNoStereoTautomerIdCode(entry);
289
+ const hash = strongHash(idCode); // identical to getNoStereoTautomerHash(entry)
290
+ ```
291
+
292
+ That matters because canonizing a generic tautomer is the most expensive thing here: asking for both
293
+ separately costs 9% more on the median molecule and 48% more averaged over a library. It is also how
294
+ a database backfills a hash column from idcodes it already stores, with no chemistry at all.
295
+
296
+ ### What they cost
297
+
298
+ On ordinary drug-like molecules the no-stereo hash costs about 52 µs and the tautomer one about
299
+ 145 µs. Want both columns? Call both — the two share the idcode parse and the stereo strip, but that
300
+ shared work is worth under 20 µs and is not worth an API to save.
301
+
302
+ The tautomer cost is nothing like uniform, though, and that changes the picture entirely on a real
303
+ library. It is driven by how many tautomeric sites a molecule has, and a molecule with a great many
304
+ can take the better part of a second before OpenChemLib abandons the enumeration. Roughly one in ten
305
+ of the test fixture is such a molecule, and they drag the mean to 29.6 ms — at which point the
306
+ no-stereo hash is 0.2% of the tautomer one.
307
+
308
+ Two things follow. Hash a library **in a worker**, never on the main thread. And if you only need
309
+ identity up to stereochemistry, `getNoStereoHash` is the one to reach for: it is the hash whose cost
310
+ you can predict.
311
+
312
+ ### Getting a hash out of a process
313
+
314
+ A hash is a signed 64-bit integer. `JSON.stringify` throws on a `BigInt`, and a JSON number could
315
+ not carry one anyway, so a hash that leaves the process goes as the 16 hex digits of its pattern:
316
+
317
+ ```js
318
+ import { hashToHex, hexToHash } from 'openchemlib-search-wasm';
319
+
320
+ hashToHex(getNoStereoTautomerHash(idCode)); // 'eb14b9bc9ab4dd52', always 16 characters
321
+ hexToHash('eb14b9bc9ab4dd52'); // -1507375755561738926n
322
+ ```
323
+
324
+ `hash.toString(16)` is not the same thing: it writes `-1` for `-1n`, where the pattern is
325
+ `ffffffffffffffff`, and it pads nothing.
326
+
327
+ Store the hash in an integer column — 8 bytes, and the column indexes as an integer — and let the
328
+ database format it on the way out. SQLite's `printf('%016x', hash)` produces exactly the same
329
+ string, which also keeps a 64-bit value from ever being read into a JavaScript number:
330
+
331
+ ```sql
332
+ SELECT printf('%016x', no_stereo_tautomer_hash) AS hash FROM molecules WHERE id = ?;
333
+ ```
334
+
335
+ ## Diagnostics
336
+
337
+ **Nothing here writes to your console.** The generated TeaVM runtime maps Java's standard output
338
+ onto `console.log`, which is the stream a server writing structured logs is already using. Anything
339
+ OpenChemLib printed would interleave unparsable lines into that log, so Java's two streams are
340
+ routed to a sink that drops them, and a host that wants them says where:
341
+
342
+ ```js
343
+ import { setLogHandler } from 'openchemlib-search-wasm';
344
+
345
+ setLogHandler((message, stream) => logger.debug({ stream }, message));
346
+ setLogHandler(null); // back to discarding
347
+ ```
164
348
 
165
- Pass `{ largestFragmentOnly: true }` to strip everything but the largest fragment and neutralize it
166
- first, so a salt hashes as its parent structure.
349
+ The handler applies whether or not the module has been instantiated, so it can be set at startup or
350
+ around a single call. It is per module instance, which means per worker.
167
351
 
168
- The hash is the same value any other OpenChemLib build computes — the tests check all 250 fixture
169
- molecules against `openchemlib` — and costs around 130 µs against 520 µs there. That cost is driven
170
- by how many tautomeric sites a molecule has and is nothing like uniform: a molecule with a great
171
- many can take the better part of a second before OpenChemLib abandons the enumeration, so hash a
172
- library in a worker rather than on the main thread.
352
+ OpenChemLib's one message, `Tautomer count exceeds maximum`, is switched off at its source rather
353
+ than merely dropped here: it built its text with a full extra canonization of the molecule, once per
354
+ molecule it gave up on. `tautomerCounts` says the same thing without the work.
173
355
 
174
356
  ## What you actually win
175
357
 
package/lib/hex.d.ts ADDED
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Formats a hash as the 16 lowercase hex digits of its 64-bit pattern.
3
+ *
4
+ * A hash is a signed 64-bit integer, which `JSON.stringify` refuses outright — and a JSON number
5
+ * could not carry it anyway, since 64 bits does not fit a double. Hex is what crosses an API: it is
6
+ * always 16 characters whatever the value, it compares and sorts as a string, and it survives a
7
+ * round trip through anything that handles text.
8
+ *
9
+ * `hash.toString(16)` is not this: it writes `-1` for `-1n`, where the pattern is
10
+ * `ffffffffffffffff`, and it pads nothing.
11
+ *
12
+ * A database that stores the hash in an integer column can format it on the way out instead, and
13
+ * SQLite's `printf('%016x', hash)` produces exactly this string.
14
+ *
15
+ * ```js
16
+ * hashToHex(getNoStereoTautomerHash(idCode)); // 'eb14b9bc9ab4dd52'
17
+ * ```
18
+ * @param hash - The hash to format.
19
+ * @returns Its 16 hex digits, lowercase and zero-padded.
20
+ */
21
+ export declare function hashToHex(hash: bigint): string;
22
+ /**
23
+ * Reads back what {@link hashToHex} wrote, so a hash that arrived as text can be compared against
24
+ * one that was computed, or bound to an integer column.
25
+ * @param hex - The 16 hex digits, in either case.
26
+ * @returns The signed 64-bit hash.
27
+ * @throws {SyntaxError} When the string is not 16 hex digits — a truncated or `0x`-prefixed hash
28
+ * would otherwise read as a different, valid-looking value.
29
+ */
30
+ export declare function hexToHash(hex: string): bigint;
31
+ //# sourceMappingURL=hex.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hex.d.ts","sourceRoot":"","sources":["../src/hex.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK7C"}
package/lib/hex.js ADDED
@@ -0,0 +1,41 @@
1
+ /** How many hex digits a 64-bit hash always writes. */
2
+ const HASH_HEX_DIGITS = 16;
3
+ const HASH_HEX = /^[0-9a-f]{16}$/i;
4
+ /**
5
+ * Formats a hash as the 16 lowercase hex digits of its 64-bit pattern.
6
+ *
7
+ * A hash is a signed 64-bit integer, which `JSON.stringify` refuses outright — and a JSON number
8
+ * could not carry it anyway, since 64 bits does not fit a double. Hex is what crosses an API: it is
9
+ * always 16 characters whatever the value, it compares and sorts as a string, and it survives a
10
+ * round trip through anything that handles text.
11
+ *
12
+ * `hash.toString(16)` is not this: it writes `-1` for `-1n`, where the pattern is
13
+ * `ffffffffffffffff`, and it pads nothing.
14
+ *
15
+ * A database that stores the hash in an integer column can format it on the way out instead, and
16
+ * SQLite's `printf('%016x', hash)` produces exactly this string.
17
+ *
18
+ * ```js
19
+ * hashToHex(getNoStereoTautomerHash(idCode)); // 'eb14b9bc9ab4dd52'
20
+ * ```
21
+ * @param hash - The hash to format.
22
+ * @returns Its 16 hex digits, lowercase and zero-padded.
23
+ */
24
+ export function hashToHex(hash) {
25
+ return BigInt.asUintN(64, hash).toString(16).padStart(HASH_HEX_DIGITS, '0');
26
+ }
27
+ /**
28
+ * Reads back what {@link hashToHex} wrote, so a hash that arrived as text can be compared against
29
+ * one that was computed, or bound to an integer column.
30
+ * @param hex - The 16 hex digits, in either case.
31
+ * @returns The signed 64-bit hash.
32
+ * @throws {SyntaxError} When the string is not 16 hex digits — a truncated or `0x`-prefixed hash
33
+ * would otherwise read as a different, valid-looking value.
34
+ */
35
+ export function hexToHash(hex) {
36
+ if (!HASH_HEX.test(hex)) {
37
+ throw new SyntaxError(`not a 16-digit hex hash: ${JSON.stringify(hex)}`);
38
+ }
39
+ return BigInt.asIntN(64, BigInt(`0x${hex}`));
40
+ }
41
+ //# sourceMappingURL=hex.js.map
package/lib/hex.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hex.js","sourceRoot":"","sources":["../src/hex.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B,MAAM,QAAQ,GAAG,iBAAiB,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,WAAW,CAAC,4BAA4B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC;AAC/C,CAAC"}
package/lib/index.d.ts CHANGED
@@ -1,8 +1,12 @@
1
- import type { TautomerHashOptions } from './types.ts';
1
+ import type { HashOptions } from './types.ts';
2
2
  export { substructureSearch } from './substructureSearch.ts';
3
+ export { setLogHandler } from './wasm/log.ts';
4
+ export { hashToHex, hexToHash } from './hex.ts';
5
+ export { strongHash } from './strongHash.ts';
3
6
  export { similaritySearch } from './similaritySearch.ts';
4
- export { INDEX_WORDS, NO_HASH } from './types.ts';
5
- export type { ResultBuffer, SearchMode, SearchOptions, SearchResult, SearchStep, SimilaritySearchOptions, SimilaritySearchResult, SubstructureSearchOptions, SubstructureSearchResult, TautomerHashOptions, } from './types.ts';
7
+ export { DEFAULT_MAX_TAUTOMERS, INDEX_WORDS, NO_HASH, NO_ID_CODE, } from './types.ts';
8
+ export type { LogHandler, LogStream } from './wasm/log.ts';
9
+ export type { HashOptions, ResultBuffer, SearchMode, SearchOptions, SearchResult, SearchStep, SimilaritySearchOptions, SimilaritySearchResult, SubstructureSearchOptions, SubstructureSearchResult, TautomerHashOptions, } from './types.ts';
6
10
  export { SimilarityResult, SubstructureResult } from './types.ts';
7
11
  /**
8
12
  * Builds the 512-bit FragFp fingerprint of one idcode, as sixteen 32-bit words.
@@ -57,11 +61,11 @@ export declare function getIndexes(idCodes: string[]): Int32Array[];
57
61
  * insert.run(entryId, getNoStereoTautomerHash(idCode));
58
62
  * ```
59
63
  * @param idCode - The molecule to hash, as an idcode.
60
- * @param options - See {@link TautomerHashOptions}.
64
+ * @param options - See {@link HashOptions}.
61
65
  * @returns Its hash, or `NO_HASH` (`0n`) for an idcode that will not parse or a molecule
62
66
  * OpenChemLib cannot canonize.
63
67
  */
64
- export declare function getNoStereoTautomerHash(idCode: string, options?: TautomerHashOptions): bigint;
68
+ export declare function getNoStereoTautomerHash(idCode: string, options?: HashOptions): bigint;
65
69
  /**
66
70
  * Hashes every idcode to its no-stereo tautomer hash, one 64-bit value each.
67
71
  *
@@ -75,9 +79,99 @@ export declare function getNoStereoTautomerHash(idCode: string, options?: Tautom
75
79
  * The hashes come back in one `BigInt64Array` rather than one value per molecule, so a table of
76
80
  * them costs a single allocation and can be written straight into a column.
77
81
  * @param idCodes - The molecules to hash, as idcodes.
78
- * @param options - See {@link TautomerHashOptions}.
82
+ * @param options - See {@link HashOptions}.
79
83
  * @returns One hash per idcode, in order, with `NO_HASH` (`0n`) for each one that could not be
80
84
  * hashed.
81
85
  */
82
- export declare function getNoStereoTautomerHashes(idCodes: string[], options?: TautomerHashOptions): BigInt64Array;
86
+ export declare function getNoStereoTautomerHashes(idCodes: string[], options?: HashOptions): BigInt64Array;
87
+ /**
88
+ * Hashes one idcode to the 64-bit value OpenChemLib identifies a molecule by up to stereochemistry.
89
+ *
90
+ * Every stereoisomer of a structure gives the same hash, and nothing else does: unlike
91
+ * {@link getNoStereoTautomerHash} the tautomers stay apart, so the keto and the enol form of a
92
+ * compound key differently. That makes it the narrower of the two identity columns — the one to use
93
+ * when a record's stereo centres are unreliable but the bonds it was drawn with are not.
94
+ *
95
+ * It is OpenChemLib's own `CanonizerUtil.getNoStereoHash`, so the value matches what any other
96
+ * OpenChemLib build computes, and it is a signed 64-bit integer — what an SQLite `INTEGER` column
97
+ * stores and indexes directly:
98
+ *
99
+ * ```js
100
+ * insert.run(entryId, getNoStereoHash(idCode));
101
+ * ```
102
+ * @param idCode - The molecule to hash, as an idcode.
103
+ * @param options - See {@link HashOptions}.
104
+ * @returns Its hash, or `NO_HASH` (`0n`) for an idcode that will not parse or a molecule
105
+ * OpenChemLib cannot canonize.
106
+ */
107
+ export declare function getNoStereoHash(idCode: string, options?: HashOptions): bigint;
108
+ /**
109
+ * Hashes every idcode to its no-stereo hash, one 64-bit value each.
110
+ *
111
+ * See {@link getNoStereoHash} for what the hash identifies. It costs a fraction of
112
+ * {@link getNoStereoTautomerHashes} because it canonizes the molecule itself instead of enumerating
113
+ * its tautomers, and its cost is even across a library rather than driven by how tautomeric each
114
+ * molecule happens to be.
115
+ *
116
+ * The hashes come back in one `BigInt64Array` rather than one value per molecule, so a table of
117
+ * them costs a single allocation and can be written straight into a column.
118
+ * @param idCodes - The molecules to hash, as idcodes.
119
+ * @param options - See {@link HashOptions}.
120
+ * @returns One hash per idcode, in order, with `NO_HASH` (`0n`) for each one that could not be
121
+ * hashed.
122
+ */
123
+ export declare function getNoStereoHashes(idCodes: string[], options?: HashOptions): BigInt64Array;
124
+ /**
125
+ * Canonizes one idcode to the form OpenChemLib identifies a molecule by up to stereochemistry.
126
+ *
127
+ * This is the string {@link getNoStereoHash} hashes, for a database that stores the canonical form
128
+ * itself. Prefer the hash where the column is only ever compared: it is a signed 64-bit integer, so
129
+ * it stores and indexes in 8 bytes where these idcodes average around 25 characters.
130
+ *
131
+ * ```js
132
+ * getNoStereoIdCode(idCode); // 'gGX`BDdwMT@@'
133
+ * ```
134
+ * @param idCode - The molecule to canonize, as an idcode.
135
+ * @param options - See {@link HashOptions}.
136
+ * @returns Its canonical no-stereo idcode, or `NO_ID_CODE` (`''`) for an idcode that will not parse
137
+ * or a molecule OpenChemLib cannot canonize.
138
+ */
139
+ export declare function getNoStereoIdCode(idCode: string, options?: HashOptions): string;
140
+ /**
141
+ * Canonizes every idcode to the form OpenChemLib identifies a molecule by up to stereochemistry.
142
+ *
143
+ * See {@link getNoStereoIdCode} for what the form identifies.
144
+ * @param idCodes - The molecules to canonize, as idcodes.
145
+ * @param options - See {@link HashOptions}.
146
+ * @returns One idcode per input, in order, with `NO_ID_CODE` (`''`) for each one that could not be
147
+ * canonized.
148
+ */
149
+ export declare function getNoStereoIdCodes(idCodes: string[], options?: HashOptions): string[];
150
+ /**
151
+ * Canonizes one idcode to the form OpenChemLib identifies a molecule by up to tautomerism and
152
+ * stereochemistry.
153
+ *
154
+ * This is the string {@link getNoStereoTautomerHash} hashes. It is the generic tautomer's idcode, so
155
+ * it is longer than the molecule's own — around twice it for a molecule with tautomeric sites — and
156
+ * it is not a structure: parsing it back gives a molecule with every tautomeric bond normalized, not
157
+ * the compound. Use it as a key, never as something to draw.
158
+ * @param idCode - The molecule to canonize, as an idcode.
159
+ * @param options - See {@link HashOptions}.
160
+ * @returns Its canonical no-stereo generic-tautomer idcode, or `NO_ID_CODE` (`''`) for an idcode that
161
+ * will not parse or a molecule OpenChemLib cannot canonize.
162
+ */
163
+ export declare function getNoStereoTautomerIdCode(idCode: string, options?: HashOptions): string;
164
+ /**
165
+ * Canonizes every idcode to the form OpenChemLib identifies a molecule by up to tautomerism and
166
+ * stereochemistry.
167
+ *
168
+ * See {@link getNoStereoTautomerIdCode} for what the form identifies, and
169
+ * {@link getNoStereoTautomerHashes} for what it costs — the canonization is the expensive part, not
170
+ * the hashing, so these cost what those do.
171
+ * @param idCodes - The molecules to canonize, as idcodes.
172
+ * @param options - See {@link HashOptions}.
173
+ * @returns One idcode per input, in order, with `NO_ID_CODE` (`''`) for each one that could not be
174
+ * canonized.
175
+ */
176
+ export declare function getNoStereoTautomerIdCodes(idCodes: string[], options?: HashOptions): string[];
83
177
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAClD,YAAY,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAInD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAQ1D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAKR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,mBAAwB,GAChC,aAAa,CAWf"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,OAAO,EACP,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAInD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAQ1D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB,MAAM,CAiBR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,WAAgB,GACxB,aAAa,CAiBf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB,MAAM,CAKR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,WAAgB,GACxB,aAAa,CAKf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB,MAAM,CAKR;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,WAAgB,GACxB,MAAM,EAAE,CAKV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB,MAAM,CAiBR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,WAAgB,GACxB,MAAM,EAAE,CAiBV"}
package/lib/index.js CHANGED
@@ -1,8 +1,11 @@
1
- import { buildIndexes, buildNoStereoTautomerHashes } from "./scan.js";
2
- import { INDEX_WORDS } from "./types.js";
1
+ import { buildIndexes, buildNoStereoHashes, buildNoStereoIdCodes, buildNoStereoTautomerHashes, buildNoStereoTautomerIdCodes, } from "./scan.js";
2
+ import { DEFAULT_MAX_TAUTOMERS, INDEX_WORDS, NO_ID_CODE } from "./types.js";
3
3
  export { substructureSearch } from "./substructureSearch.js";
4
+ export { setLogHandler } from "./wasm/log.js";
5
+ export { hashToHex, hexToHash } from "./hex.js";
6
+ export { strongHash } from "./strongHash.js";
4
7
  export { similaritySearch } from "./similaritySearch.js";
5
- export { INDEX_WORDS, NO_HASH } from "./types.js";
8
+ export { DEFAULT_MAX_TAUTOMERS, INDEX_WORDS, NO_HASH, NO_ID_CODE, } from "./types.js";
6
9
  export { SimilarityResult, SubstructureResult } from "./types.js";
7
10
  /**
8
11
  * Builds the 512-bit FragFp fingerprint of one idcode, as sixteen 32-bit words.
@@ -69,14 +72,14 @@ export function getIndexes(idCodes) {
69
72
  * insert.run(entryId, getNoStereoTautomerHash(idCode));
70
73
  * ```
71
74
  * @param idCode - The molecule to hash, as an idcode.
72
- * @param options - See {@link TautomerHashOptions}.
75
+ * @param options - See {@link HashOptions}.
73
76
  * @returns Its hash, or `NO_HASH` (`0n`) for an idcode that will not parse or a molecule
74
77
  * OpenChemLib cannot canonize.
75
78
  */
76
79
  export function getNoStereoTautomerHash(idCode, options = {}) {
77
- const { largestFragmentOnly = false } = options;
80
+ const { largestFragmentOnly = false, tautomerCounts, maxTautomers = DEFAULT_MAX_TAUTOMERS, } = options;
78
81
  const result = new BigInt64Array(1);
79
- buildNoStereoTautomerHashes([idCode], result, largestFragmentOnly, 0, 1);
82
+ buildNoStereoTautomerHashes([idCode], result, largestFragmentOnly, 0, 1, tautomerCounts, maxTautomers);
80
83
  return result[0];
81
84
  }
82
85
  /**
@@ -92,14 +95,134 @@ export function getNoStereoTautomerHash(idCode, options = {}) {
92
95
  * The hashes come back in one `BigInt64Array` rather than one value per molecule, so a table of
93
96
  * them costs a single allocation and can be written straight into a column.
94
97
  * @param idCodes - The molecules to hash, as idcodes.
95
- * @param options - See {@link TautomerHashOptions}.
98
+ * @param options - See {@link HashOptions}.
96
99
  * @returns One hash per idcode, in order, with `NO_HASH` (`0n`) for each one that could not be
97
100
  * hashed.
98
101
  */
99
102
  export function getNoStereoTautomerHashes(idCodes, options = {}) {
103
+ const { largestFragmentOnly = false, tautomerCounts, maxTautomers = DEFAULT_MAX_TAUTOMERS, } = options;
104
+ const result = new BigInt64Array(idCodes.length);
105
+ buildNoStereoTautomerHashes(idCodes, result, largestFragmentOnly, 0, idCodes.length, tautomerCounts, maxTautomers);
106
+ return result;
107
+ }
108
+ /**
109
+ * Hashes one idcode to the 64-bit value OpenChemLib identifies a molecule by up to stereochemistry.
110
+ *
111
+ * Every stereoisomer of a structure gives the same hash, and nothing else does: unlike
112
+ * {@link getNoStereoTautomerHash} the tautomers stay apart, so the keto and the enol form of a
113
+ * compound key differently. That makes it the narrower of the two identity columns — the one to use
114
+ * when a record's stereo centres are unreliable but the bonds it was drawn with are not.
115
+ *
116
+ * It is OpenChemLib's own `CanonizerUtil.getNoStereoHash`, so the value matches what any other
117
+ * OpenChemLib build computes, and it is a signed 64-bit integer — what an SQLite `INTEGER` column
118
+ * stores and indexes directly:
119
+ *
120
+ * ```js
121
+ * insert.run(entryId, getNoStereoHash(idCode));
122
+ * ```
123
+ * @param idCode - The molecule to hash, as an idcode.
124
+ * @param options - See {@link HashOptions}.
125
+ * @returns Its hash, or `NO_HASH` (`0n`) for an idcode that will not parse or a molecule
126
+ * OpenChemLib cannot canonize.
127
+ */
128
+ export function getNoStereoHash(idCode, options = {}) {
129
+ const { largestFragmentOnly = false } = options;
130
+ const result = new BigInt64Array(1);
131
+ buildNoStereoHashes([idCode], result, largestFragmentOnly, 0, 1);
132
+ return result[0];
133
+ }
134
+ /**
135
+ * Hashes every idcode to its no-stereo hash, one 64-bit value each.
136
+ *
137
+ * See {@link getNoStereoHash} for what the hash identifies. It costs a fraction of
138
+ * {@link getNoStereoTautomerHashes} because it canonizes the molecule itself instead of enumerating
139
+ * its tautomers, and its cost is even across a library rather than driven by how tautomeric each
140
+ * molecule happens to be.
141
+ *
142
+ * The hashes come back in one `BigInt64Array` rather than one value per molecule, so a table of
143
+ * them costs a single allocation and can be written straight into a column.
144
+ * @param idCodes - The molecules to hash, as idcodes.
145
+ * @param options - See {@link HashOptions}.
146
+ * @returns One hash per idcode, in order, with `NO_HASH` (`0n`) for each one that could not be
147
+ * hashed.
148
+ */
149
+ export function getNoStereoHashes(idCodes, options = {}) {
100
150
  const { largestFragmentOnly = false } = options;
101
151
  const result = new BigInt64Array(idCodes.length);
102
- buildNoStereoTautomerHashes(idCodes, result, largestFragmentOnly, 0, idCodes.length);
152
+ buildNoStereoHashes(idCodes, result, largestFragmentOnly, 0, idCodes.length);
153
+ return result;
154
+ }
155
+ /**
156
+ * Canonizes one idcode to the form OpenChemLib identifies a molecule by up to stereochemistry.
157
+ *
158
+ * This is the string {@link getNoStereoHash} hashes, for a database that stores the canonical form
159
+ * itself. Prefer the hash where the column is only ever compared: it is a signed 64-bit integer, so
160
+ * it stores and indexes in 8 bytes where these idcodes average around 25 characters.
161
+ *
162
+ * ```js
163
+ * getNoStereoIdCode(idCode); // 'gGX`BDdwMT@@'
164
+ * ```
165
+ * @param idCode - The molecule to canonize, as an idcode.
166
+ * @param options - See {@link HashOptions}.
167
+ * @returns Its canonical no-stereo idcode, or `NO_ID_CODE` (`''`) for an idcode that will not parse
168
+ * or a molecule OpenChemLib cannot canonize.
169
+ */
170
+ export function getNoStereoIdCode(idCode, options = {}) {
171
+ const { largestFragmentOnly = false } = options;
172
+ const result = [NO_ID_CODE];
173
+ buildNoStereoIdCodes([idCode], result, largestFragmentOnly, 0, 1);
174
+ return result[0];
175
+ }
176
+ /**
177
+ * Canonizes every idcode to the form OpenChemLib identifies a molecule by up to stereochemistry.
178
+ *
179
+ * See {@link getNoStereoIdCode} for what the form identifies.
180
+ * @param idCodes - The molecules to canonize, as idcodes.
181
+ * @param options - See {@link HashOptions}.
182
+ * @returns One idcode per input, in order, with `NO_ID_CODE` (`''`) for each one that could not be
183
+ * canonized.
184
+ */
185
+ export function getNoStereoIdCodes(idCodes, options = {}) {
186
+ const { largestFragmentOnly = false } = options;
187
+ const result = new Array(idCodes.length).fill(NO_ID_CODE);
188
+ buildNoStereoIdCodes(idCodes, result, largestFragmentOnly, 0, idCodes.length);
189
+ return result;
190
+ }
191
+ /**
192
+ * Canonizes one idcode to the form OpenChemLib identifies a molecule by up to tautomerism and
193
+ * stereochemistry.
194
+ *
195
+ * This is the string {@link getNoStereoTautomerHash} hashes. It is the generic tautomer's idcode, so
196
+ * it is longer than the molecule's own — around twice it for a molecule with tautomeric sites — and
197
+ * it is not a structure: parsing it back gives a molecule with every tautomeric bond normalized, not
198
+ * the compound. Use it as a key, never as something to draw.
199
+ * @param idCode - The molecule to canonize, as an idcode.
200
+ * @param options - See {@link HashOptions}.
201
+ * @returns Its canonical no-stereo generic-tautomer idcode, or `NO_ID_CODE` (`''`) for an idcode that
202
+ * will not parse or a molecule OpenChemLib cannot canonize.
203
+ */
204
+ export function getNoStereoTautomerIdCode(idCode, options = {}) {
205
+ const { largestFragmentOnly = false, tautomerCounts, maxTautomers = DEFAULT_MAX_TAUTOMERS, } = options;
206
+ const result = [NO_ID_CODE];
207
+ buildNoStereoTautomerIdCodes([idCode], result, largestFragmentOnly, 0, 1, tautomerCounts, maxTautomers);
208
+ return result[0];
209
+ }
210
+ /**
211
+ * Canonizes every idcode to the form OpenChemLib identifies a molecule by up to tautomerism and
212
+ * stereochemistry.
213
+ *
214
+ * See {@link getNoStereoTautomerIdCode} for what the form identifies, and
215
+ * {@link getNoStereoTautomerHashes} for what it costs — the canonization is the expensive part, not
216
+ * the hashing, so these cost what those do.
217
+ * @param idCodes - The molecules to canonize, as idcodes.
218
+ * @param options - See {@link HashOptions}.
219
+ * @returns One idcode per input, in order, with `NO_ID_CODE` (`''`) for each one that could not be
220
+ * canonized.
221
+ */
222
+ export function getNoStereoTautomerIdCodes(idCodes, options = {}) {
223
+ const { largestFragmentOnly = false, tautomerCounts, maxTautomers = DEFAULT_MAX_TAUTOMERS, } = options;
224
+ const result = new Array(idCodes.length).fill(NO_ID_CODE);
225
+ buildNoStereoTautomerIdCodes(idCodes, result, largestFragmentOnly, 0, idCodes.length, tautomerCounts, maxTautomers);
103
226
  return result;
104
227
  }
105
228
  //# sourceMappingURL=index.js.map