quiverdb 0.10.1 → 0.10.2

package/README.md

@@ -71,6 +71,8 @@ bun run example.ts
 - `createElement(collection, data)` -- Create element, returns numeric ID
 - `updateElement(collection, id, data)` -- Update element by ID
 - `deleteElement(collection, id)` -- Delete element by ID
+- `updateElementByLabel(collection, label, data)` -- Update element by label
+- `deleteElementByLabel(collection, label)` -- Delete element by label
 
 ### Read (bulk)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quiverdb",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/create.ts

@@ -148,12 +148,51 @@ Database.prototype.updateElement = function (
   }
 };
 
+/** Label-addressed counterpart of updateElement. */
+Database.prototype.updateElementByLabel = function (
+  this: Database,
+  collection: string,
+  label: string,
+  data: ElementData,
+): void {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outElem = allocPtrOut();
+  check(lib.quiver_element_create(outElem.buf));
+  const elemPtr = readPtrOut(outElem);
+
+  try {
+    for (const [key, value] of Object.entries(data)) {
+      if (value === undefined) continue;
+      setElementField(lib, elemPtr, key, value);
+    }
+    const collBuf = toCString(collection);
+    const labelBuf = toCString(label);
+    check(lib.quiver_database_update_element_by_label(handle, collBuf.buf, labelBuf.buf, elemPtr));
+  } finally {
+    lib.quiver_element_destroy(elemPtr);
+  }
+};
+
 Database.prototype.deleteElement = function (this: Database, collection: string, id: number): void {
   const lib = getSymbols();
   const collBuf = toCString(collection);
   check(lib.quiver_database_delete_element(this._handle, collBuf.buf, BigInt(id)));
 };
 
+/** Label-addressed counterpart of deleteElement. */
+Database.prototype.deleteElementByLabel = function (
+  this: Database,
+  collection: string,
+  label: string,
+): void {
+  const lib = getSymbols();
+  const collBuf = toCString(collection);
+  const labelBuf = toCString(label);
+  check(lib.quiver_database_delete_element_by_label(this._handle, collBuf.buf, labelBuf.buf));
+};
+
 /**
  * Replace all of an element's rows in one *named* vector group, from column arrays keyed by name.
  *
@@ -180,6 +219,25 @@ Database.prototype.updateVectorGroup = function (
   );
 };
 
+/** Label-addressed counterpart of updateVectorGroup. */
+Database.prototype.updateVectorGroupByLabel = function (
+  this: Database,
+  collection: string,
+  group: string,
+  label: string,
+  data: GroupColumns,
+): void {
+  updateGroupColumns(
+    this._handle,
+    "updateVectorGroupByLabel",
+    getSymbols().quiver_database_update_vector_group_by_label,
+    collection,
+    group,
+    label,
+    data,
+  );
+};
+
 /** Set-group counterpart of updateVectorGroup. */
 Database.prototype.updateSetGroup = function (
   this: Database,
@@ -198,3 +256,22 @@ Database.prototype.updateSetGroup = function (
     data,
   );
 };
+
+/** Label-addressed counterpart of updateSetGroup. */
+Database.prototype.updateSetGroupByLabel = function (
+  this: Database,
+  collection: string,
+  group: string,
+  label: string,
+  data: GroupColumns,
+): void {
+  updateGroupColumns(
+    this._handle,
+    "updateSetGroupByLabel",
+    getSymbols().quiver_database_update_set_group_by_label,
+    collection,
+    group,
+    label,
+    data,
+  );
+};

package/src/database.ts

@@ -86,7 +86,9 @@ export class Database {
   // --- Element CRUD (implemented in create.ts) ---
   declare createElement: (collection: string, data: ElementData) => number;
   declare updateElement: (collection: string, id: number, data: ElementData) => void;
+  declare updateElementByLabel: (collection: string, label: string, data: ElementData) => void;
   declare deleteElement: (collection: string, id: number) => void;
+  declare deleteElementByLabel: (collection: string, label: string) => void;
 
   // --- Reads (implemented in read.ts) ---
   declare readScalarIntegers: (collection: string, attribute: string) => (number | null)[];
@@ -156,24 +158,48 @@ export class Database {
     id: number,
     data: TimeSeriesData,
   ) => void;
+  declare updateTimeSeriesGroupByLabel: (
+    collection: string,
+    group: string,
+    label: string,
+    data: TimeSeriesData,
+  ) => void;
   declare updateVectorGroup: (
     collection: string,
     group: string,
     id: number,
     data: GroupColumns,
   ) => void;
+  declare updateVectorGroupByLabel: (
+    collection: string,
+    group: string,
+    label: string,
+    data: GroupColumns,
+  ) => void;
   declare updateSetGroup: (
     collection: string,
     group: string,
     id: number,
     data: GroupColumns,
   ) => void;
+  declare updateSetGroupByLabel: (
+    collection: string,
+    group: string,
+    label: string,
+    data: GroupColumns,
+  ) => void;
   declare upsertTimeSeriesRow: (
     collection: string,
     group: string,
     id: number,
     row: Record<string, number | bigint | string>,
   ) => void;
+  declare upsertTimeSeriesRowByLabel: (
+    collection: string,
+    group: string,
+    label: string,
+    row: Record<string, number | bigint | string>,
+  ) => void;
   declare hasTimeSeriesFiles: (collection: string) => boolean;
   declare listTimeSeriesFilesColumns: (collection: string) => string[];
   declare readTimeSeriesFiles: (collection: string) => Record<string, string | null>;

package/src/group-columns.ts

@@ -15,13 +15,14 @@ export type GroupColumns = Record<string, (number | string | null)[]>;
 
 /**
  * The parallel-array signature every columnar group update C function shares
- * (quiver_database_update_{time_series,vector,set}_group).
+ * (quiver_database_update_{time_series,vector,set}_group and their _by_label forms). The 4th
+ * argument addresses the element: an id for the by-id forms, a NUL-terminated label otherwise.
  */
 type ColumnUpdateFn = (
   db: NativePointer,
   collection: Uint8Array,
   group: Uint8Array,
-  id: bigint,
+  key: bigint | Uint8Array,
   names: Uint8Array | null,
   types: Uint8Array | null,
   data: Uint8Array | null,
@@ -32,8 +33,8 @@ type ColumnUpdateFn = (
 
 /**
  * Marshal a column-oriented payload and forward it to one of the columnar group update C
- * functions. Shared by updateTimeSeriesGroup / updateVectorGroup / updateSetGroup: the three
- * differ only in which C entry point they call.
+ * functions. Shared by updateTimeSeriesGroup / updateVectorGroup / updateSetGroup and their
+ * _by_label counterparts: they differ only in which C entry point they call.
  *
  * Pass `{}` (no columns) to clear the group.
  */
@@ -43,15 +44,16 @@ export function updateGroupColumns(
   update: ColumnUpdateFn,
   collection: string,
   group: string,
-  id: number,
+  key: number | string,
   data: GroupColumns,
 ): void {
   const collBuf = toCString(collection);
   const grpBuf = toCString(group);
+  const keyArg = typeof key === "string" ? toCString(key).buf : BigInt(key);
   const entries = Object.entries(data);
 
   if (entries.length === 0) {
-    check(update(handle, collBuf.buf, grpBuf.buf, BigInt(id), null, null, null, null, 0n, 0n));
+    check(update(handle, collBuf.buf, grpBuf.buf, keyArg, null, null, null, null, 0n, 0n));
     return;
   }
 
@@ -149,7 +151,7 @@ export function updateGroupColumns(
       handle,
       collBuf.buf,
       grpBuf.buf,
-      BigInt(id),
+      keyArg,
       namesTable.buf,
       typesAlloc.buf,
       dataTable.buf,

package/src/loader.ts

@@ -58,7 +58,9 @@ const elementSymbols = {
 const crudSymbols = {
   quiver_database_create_element: { args: [P, BUF, P, P], returns: I32 },
   quiver_database_update_element: { args: [P, BUF, I64, P], returns: I32 },
+  quiver_database_update_element_by_label: { args: [P, BUF, BUF, P], returns: I32 },
   quiver_database_delete_element: { args: [P, BUF, I64], returns: I32 },
+  quiver_database_delete_element_by_label: { args: [P, BUF, BUF], returns: I32 },
 } as const;
 
 const readSymbols = {
@@ -131,18 +133,34 @@ const timeSeriesSymbols = {
     args: [P, BUF, BUF, I64, P, P, P, USIZE],
     returns: I32,
   },
+  quiver_database_upsert_time_series_row_by_label: {
+    args: [P, BUF, BUF, BUF, P, P, P, USIZE],
+    returns: I32,
+  },
   quiver_database_update_time_series_group: {
     args: [P, BUF, BUF, I64, P, P, P, P, USIZE, USIZE],
     returns: I32,
   },
+  quiver_database_update_time_series_group_by_label: {
+    args: [P, BUF, BUF, BUF, P, P, P, P, USIZE, USIZE],
+    returns: I32,
+  },
   quiver_database_update_vector_group: {
     args: [P, BUF, BUF, I64, P, P, P, P, USIZE, USIZE],
     returns: I32,
   },
+  quiver_database_update_vector_group_by_label: {
+    args: [P, BUF, BUF, BUF, P, P, P, P, USIZE, USIZE],
+    returns: I32,
+  },
   quiver_database_update_set_group: {
     args: [P, BUF, BUF, I64, P, P, P, P, USIZE, USIZE],
     returns: I32,
   },
+  quiver_database_update_set_group_by_label: {
+    args: [P, BUF, BUF, BUF, P, P, P, P, USIZE, USIZE],
+    returns: I32,
+  },
   quiver_database_free_time_series_data: { args: [P, P, P, P, USIZE, USIZE], returns: I32 },
   quiver_database_has_time_series_files: { args: [P, BUF, P], returns: I32 },
   quiver_database_list_time_series_files_columns: { args: [P, BUF, P, P], returns: I32 },

package/src/lua-api.ts

@@ -212,7 +212,9 @@ Rules worth knowing:
 \`\`\`lua
 local id = db:create_element(collection, element_table)   -- returns new integer id
 db:update_element(collection, id, element_table)
+db:update_element_by_label(collection, label, element_table)  -- same update, addressed by label
 db:delete_element(collection, id)
+db:delete_element_by_label(collection, label)             -- same delete, addressed by label
 \`\`\`
 
 The element table holds scalar attributes as \`key = value\`, and vector/set attributes as
@@ -238,6 +240,13 @@ Notes:
 - **\`update_element\` / \`delete_element\` require an existing id.** Targeting an id that does not
   exist throws \`Element not found: <id> in collection '<collection>'\` (no silent no-op). Use
   \`read_element_ids\` to get valid ids.
+- **\`update_element_by_label\` / \`delete_element_by_label\` require an existing label**, unique
+  *per collection*, not per database — one naming an element of another collection does not
+  resolve. A miss throws \`Element not found: label '<label>' in collection '<collection>'\` and
+  changes nothing. Passing \`label = "New name"\` in the element table renames the element, after
+  which only the new label resolves. Because the label form delegates to the id form, failures
+  that validate the *element* (an empty table, a type mismatch) report
+  \`Cannot update_element: ...\`.
 - **Empty arrays are skipped.** An attribute whose value is \`{}\` writes no vector/set (the element
   type can't be inferred from an empty array), so it is silently dropped.
 - **No \`nil\` scalar attributes.** In Lua a key set to \`nil\` is dropped from the table, so
@@ -295,6 +304,9 @@ db:update_vector_group("Child", "refs", id, { parent_ref = { 1, 2, 3 } })
 db:update_set_group("Child", "parents", id, { parent_ref = { 1, 2 } })
 
 db:update_vector_group("Child", "refs", id, {})   -- clears the group
+
+db:update_vector_group_by_label("Child", "refs", "Child 1", { parent_ref = { 1, 2 } })
+db:update_set_group_by_label("Child", "parents", "Child 1", { parent_ref = { 1, 2 } })
 \`\`\`
 
 Use these instead of routing a group's columns through \`update_element\` whenever a column name is
@@ -311,7 +323,8 @@ Rules:
   are rejected if passed.
 - **Foreign-key columns accept a label string** and resolve it to the referenced id, exactly as in
   \`create_element\` / \`update_element\`.
-- The element id must exist, same as \`update_element\` / \`delete_element\`.
+- The element id must exist, same as \`update_element\` / \`delete_element\`; the \`_by_label\` form
+  takes a label in its place, with \`update_element_by_label\`'s resolution and miss semantics.
 
 ---
 
@@ -372,6 +385,8 @@ db:update_time_series_group("Items", "data", id, {
 })
 
 db:update_time_series_group("Items", "data", id, {})   -- clears the group
+
+db:update_time_series_group_by_label("Items", "data", "Item 1", { date_time = { "2024-01-01T00:00:00" }, value = { 10.5 } })
 \`\`\`
 
 A read-modify-write looks like this:
@@ -401,6 +416,8 @@ column names). Each value of the top-level table must be an **array**, not a sca
   table {} to clear the group\`) — only a bare \`{}\` clears.
 - Integer values are accepted for REAL columns (converted on insert). Booleans, functions, and
   other unsupported Lua types throw \`column '...' has unsupported Lua type\`.
+- The element id must exist; the \`_by_label\` form takes a label in its place, with
+  \`update_element_by_label\`'s resolution and miss semantics. Every rule above applies to both.
 
 ### Append/upsert a single row (\`upsert_time_series_row\` — ROW-oriented, the one exception)
 
@@ -412,8 +429,16 @@ db:upsert_time_series_row("Items", "data", id, {
     date_time = "2024-01-04T00:00:00",
     value     = 40.0,
 })
+
+db:upsert_time_series_row_by_label("Items", "data", "Item 1", {
+    date_time = "2024-01-04T00:00:00",
+    value     = 40.0,
+})
 \`\`\`
 
+The element id must exist; the \`_by_label\` form takes a label in its place, with
+\`update_element_by_label\`'s resolution and miss semantics.
+
 ---
 
 ## Time series files

package/src/time-series.ts

@@ -18,7 +18,7 @@ import {
   toCString,
 } from "./ffi-helpers.ts";
 import { updateGroupColumns } from "./group-columns.ts";
-import { getSymbols } from "./loader.ts";
+import { getSymbols, type NativePointer } from "./loader.ts";
 import {
   type Allocation,
   DATA_TYPE_DATE_TIME,
@@ -200,16 +200,57 @@ Database.prototype.updateTimeSeriesGroup = function (
   );
 };
 
-Database.prototype.upsertTimeSeriesRow = function (
+/** Label-addressed counterpart of updateTimeSeriesGroup. */
+Database.prototype.updateTimeSeriesGroupByLabel = function (
   this: Database,
   collection: string,
   group: string,
-  id: number,
+  label: string,
+  data: TimeSeriesData,
+): void {
+  updateGroupColumns(
+    this._handle,
+    "updateTimeSeriesGroupByLabel",
+    getSymbols().quiver_database_update_time_series_group_by_label,
+    collection,
+    group,
+    label,
+    data,
+  );
+};
+
+/**
+ * The parallel-array signature both row-oriented time-series upsert C functions share
+ * (quiver_database_upsert_time_series_row and its _by_label form). `key` is an id for the by-id
+ * form, a NUL-terminated label otherwise.
+ */
+type UpsertRowFn = (
+  db: NativePointer,
+  collection: Uint8Array,
+  group: Uint8Array,
+  key: bigint | Uint8Array,
+  names: Uint8Array | null,
+  types: Uint8Array | null,
+  data: Uint8Array | null,
+  columnCount: bigint,
+) => number;
+
+/**
+ * Marshal a single row of scalars and forward it to one of the row-oriented time-series upsert
+ * C functions. Shared by upsertTimeSeriesRow / upsertTimeSeriesRowByLabel: they differ only in
+ * which C entry point they call and whether `key` is an id or a label.
+ */
+function upsertRowColumns(
+  handle: NativePointer,
+  upsert: UpsertRowFn,
+  collection: string,
+  group: string,
+  key: number | string,
   row: Record<string, number | bigint | string>,
 ): void {
-  const lib = getSymbols();
   const collBuf = toCString(collection);
   const grpBuf = toCString(group);
+  const keyArg = typeof key === "string" ? toCString(key).buf : BigInt(key);
   const entries = Object.entries(row);
   const columnCount = entries.length;
   const keepalive: Allocation[] = [];
@@ -248,17 +289,52 @@ Database.prototype.upsertTimeSeriesRow = function (
   keepalive.push(dataTable);
 
   check(
-    lib.quiver_database_upsert_time_series_row(
-      this._handle,
+    upsert(
+      handle,
       collBuf.buf,
       grpBuf.buf,
-      BigInt(id),
+      keyArg,
       namesTable.buf,
       typesAlloc.buf,
       dataTable.buf,
       BigInt(columnCount),
     ),
   );
+}
+
+Database.prototype.upsertTimeSeriesRow = function (
+  this: Database,
+  collection: string,
+  group: string,
+  id: number,
+  row: Record<string, number | bigint | string>,
+): void {
+  upsertRowColumns(
+    this._handle,
+    getSymbols().quiver_database_upsert_time_series_row,
+    collection,
+    group,
+    id,
+    row,
+  );
+};
+
+/** Label-addressed counterpart of upsertTimeSeriesRow. */
+Database.prototype.upsertTimeSeriesRowByLabel = function (
+  this: Database,
+  collection: string,
+  group: string,
+  label: string,
+  row: Record<string, number | bigint | string>,
+): void {
+  upsertRowColumns(
+    this._handle,
+    getSymbols().quiver_database_upsert_time_series_row_by_label,
+    collection,
+    group,
+    label,
+    row,
+  );
 };
 
 Database.prototype.hasTimeSeriesFiles = function (this: Database, collection: string): boolean {