@zukhruf/vectors 0.8.32 → 0.8.34

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
@@ -102,6 +102,24 @@ WHERE t.source = 'docs'
102
102
  ORDER BY r.distance;
103
103
  ```
104
104
 
105
+ ### Search in Postgres
106
+
107
+ Postgres has its own client package, [pgvector](https://github.com/pgvector/pgvector-node), whose `toSql` and `fromSql` gave this package its names. Use it for the SQL form, and this package for the vector and its math ([ADR 0001](./docs/adr/0001-the-scope-and-the-name-come-from-the-vector-types-of-pgvector-and-the-math-of-dotnet.md), amendment):
108
+
109
+ ```ts
110
+ import pgvector from 'pgvector';
111
+
112
+ import { UnitVector, Vector } from '@zukhruf/vectors';
113
+
114
+ const unit = UnitVector.normalize(Vector.from(embedding));
115
+ await client.query('INSERT INTO items (embedding) VALUES ($1)', [
116
+ pgvector.toSql(Array.from(unit.values)),
117
+ ]);
118
+ await client.query('SELECT id FROM items ORDER BY embedding <=> $1 LIMIT 10', [
119
+ pgvector.toSql(Array.from(Vector.from(query).values)),
120
+ ]);
121
+ ```
122
+
105
123
  ## API
106
124
 
107
125
  ```ts
@@ -171,11 +189,11 @@ function fromSql<T extends typeof Vector | typeof HalfVector>(
171
189
 
172
190
  ## Errors
173
191
 
174
- | Error | When | The caller's next step |
175
- | ------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------- |
176
- | `DimensionMismatchError` | Two vectors of one call have other dimensions. `expected` and `actual` | Use one model for both vectors |
177
- | `ZeroVectorError` | A vector with no length is normalized | Skip the vector, or fail its record |
178
- | `SqliteVecLoadedError` | `install` on a database that loaded sqlite-vec | Use the functions of sqlite-vec, which are already there |
192
+ | Error | When | The caller's next step |
193
+ | ---------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------- |
194
+ | `DimensionMismatchError` | Two vectors of one call have other dimensions. `expected` and `actual` | Use one model for both vectors |
195
+ | `ZeroVectorError` (a `RangeError`) | A vector with no length is normalized | Skip the vector, or fail its record |
196
+ | `SqliteVecLoadedError` | `install` on a database that loaded sqlite-vec | Use the functions of sqlite-vec, which are already there |
179
197
 
180
198
  ## SQL Server: what the probes found
181
199
 
@@ -202,7 +220,7 @@ Checked on 2026-11-18:
202
220
 
203
221
  | Package | Why it does not do the job |
204
222
  | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
205
- | `pgvector` 0.3.1 (MIT, no dependencies, 1 M a week) | Postgres only. It is the model for this package's names, and the candidate for Postgres later |
223
+ | `pgvector` 0.3.1 (MIT, no dependencies, 1 M a week) | Postgres only. It is the model for this package's names, and the package for Postgres (Search in Postgres) |
206
224
  | `sqlite-vec` 0.1.9 | It loads the extension (`getLoadablePath`, `load`) and gives no bytes and no functions for a database without it |
207
225
  | `@mastra/core`, `@langchain/core` | One store interface that hides each engine; no SQL Server vectors |
208
226
  | `@memberjunction/ai-vectors-sqlserver` | BUSL-1.1, and it works only inside MemberJunction |
@@ -220,11 +238,9 @@ The package is designed for its domain. Each program below moves onto it and dro
220
238
  | Context Compiler | through `@zukhruf/embeddings` | the same |
221
239
  | datahub | none | `sqlserver.toSql`, `sqlType` |
222
240
 
223
- The cache that embeds only changed text is not in this package ([ADR 0008](./docs/adr/0008-the-embedding-cache-decorates-the-model-and-lives-outside-this-package.md)).
241
+ The cache that embeds only new text is its own package, `@zukhruf/embedding-cache` ([ADR 0008](./docs/adr/0008-the-embedding-cache-decorates-the-model-and-lives-outside-this-package.md)).
224
242
 
225
243
  ## Later
226
244
 
227
- - Postgres: adopt `pgvector`, or a `/postgres` subpath, after SQLite and SQL Server are done.
228
- - `SparseVector`, with Postgres.
229
245
  - Hamming in plain SQLite, which needs the `vec_bit` subtype of sqlite-vec.
230
246
  - Native vectors over TDS, when tedious supports them (pull request #1841).
@@ -1,5 +1,8 @@
1
- /** A vector of length 0 has no direction, so it has no unit vector. */
2
- export declare class ZeroVectorError extends Error {
1
+ /**
2
+ * A vector of length 0 has no direction, so it has no unit vector. It is a
3
+ * RangeError, as the other value errors of the package are (ADR 0003).
4
+ */
5
+ export declare class ZeroVectorError extends RangeError {
3
6
  readonly name = "ZeroVectorError";
4
7
  constructor();
5
8
  }
@@ -1 +1 @@
1
- {"version":3,"file":"zero-vector-error.d.ts","sourceRoot":"","sources":["../src/zero-vector-error.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAqB;;CAK5C"}
1
+ {"version":3,"file":"zero-vector-error.d.ts","sourceRoot":"","sources":["../src/zero-vector-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,SAAkB,IAAI,qBAAqB;;CAK5C"}
@@ -1,5 +1,8 @@
1
- /** A vector of length 0 has no direction, so it has no unit vector. */
2
- export class ZeroVectorError extends Error {
1
+ /**
2
+ * A vector of length 0 has no direction, so it has no unit vector. It is a
3
+ * RangeError, as the other value errors of the package are (ADR 0003).
4
+ */
5
+ export class ZeroVectorError extends RangeError {
3
6
  name = 'ZeroVectorError';
4
7
  constructor() {
5
8
  super('A vector of length 0 has no unit vector');
@@ -1 +1 @@
1
- {"version":3,"file":"zero-vector-error.js","sourceRoot":"","sources":["../src/zero-vector-error.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACtB,IAAI,GAAG,iBAAiB,CAAC;IAE3C;QACE,KAAK,CAAC,yCAAyC,CAAC,CAAC;IACnD,CAAC;CACF"}
1
+ {"version":3,"file":"zero-vector-error.js","sourceRoot":"","sources":["../src/zero-vector-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,UAAU;IAC3B,IAAI,GAAG,iBAAiB,CAAC;IAE3C;QACE,KAAK,CAAC,yCAAyC,CAAC,CAAC;IACnD,CAAC;CACF"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zukhruf/vectors",
3
- "version": "0.8.32",
3
+ "version": "0.8.34",
4
4
  "description": "Vector types, their math, and the SQL form of each vector in SQLite, sqlite-vec and SQL Server, which a program composes into its own SQL. After the vector types of pgvector and the TensorPrimitives of .NET.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -55,8 +55,8 @@
55
55
  },
56
56
  "devDependencies": {
57
57
  "@types/mssql": "^12.3.0",
58
- "@zukhruf/sqlite-open": "^0.8.32",
59
- "@zukhruf/testing": "^0.8.32",
58
+ "@zukhruf/sqlite-open": "^0.8.34",
59
+ "@zukhruf/testing": "^0.8.34",
60
60
  "mssql": "^12.7.14",
61
61
  "sqlite-vec": "^0.1.9"
62
62
  }