xitdb 0.3.0 → 0.5.0

package/README.md

@@ -1,10 +1,19 @@
-xitdb is an immutable database written in TypeScript.
+<p align="center">
+  xitdb is an immutable database written in TypeScript
+  <br/>
+  <br/>
+  <b>Choose your flavor:</b>
+  <a href="https://github.com/radarroark/xitdb">Zig</a> |
+  <a href="https://github.com/radarroark/xitdb-java">Java</a> |
+  <a href="https://github.com/codeboost/xitdb-clj">Clojure</a> |
+  <a href="https://github.com/radarroark/xitdb-ts">TypeScript</a>
+</p>
 
 * Each transaction efficiently creates a new "copy" of the database, and past copies can still be read from.
 * It supports writing to a file as well as purely in-memory use.
 * No query engine of any kind. You just write data structures (primarily an `ArrayList` and `HashMap`) that can be nested arbitrarily.
 * No dependencies besides the JavaScript standard library.
-* This project is a port of the [original Zig version](https://github.com/radarroark/xitdb) and the [Java version](https://github.com/radarroark/xitdb-java).
+* It is available [on npm](https://www.npmjs.com/package/xitdb).
 
 This database was originally made for the [xit version control system](https://github.com/radarroark/xit), but I bet it has a lot of potential for other projects. The combination of being immutable and having an API similar to in-memory data structures is pretty powerful. Consider using it [instead of SQLite](https://gist.github.com/radarroark/03a0724484e1111ef4c05d72a935c42c) for your TypeScript projects: it's simpler, it's pure TypeScript, and it creates no impedance mismatch with your program the way SQL databases do.
 
@@ -82,18 +91,18 @@ const moment = await ReadHashMap.create(momentCursor!);
 // the cursor to "foo" and then calling readBytes on it
 const fooCursor = await moment.getCursorByString('foo');
 const fooValue = await fooCursor!.readBytes(MAX_READ_BYTES);
-console.log(new TextDecoder().decode(fooValue)); // "foo"
+expect(new TextDecoder().decode(fooValue)).toBe('foo');
 
 // to get the "fruits" list, we get the cursor to it and
 // then pass it to the ReadArrayList constructor
 const fruitsCursor = await moment.getCursorByString('fruits');
 const fruits = new ReadArrayList(fruitsCursor!);
-console.log(await fruits.count()); // 3
+expect(await fruits.count()).toBe(3);
 
 // now we can get the first item from the fruits list and read it
 const appleCursor = await fruits.getCursor(0);
 const appleValue = await appleCursor!.readBytes(MAX_READ_BYTES);
-console.log(new TextDecoder().decode(appleValue)); // "apple"
+expect(new TextDecoder().decode(appleValue)).toBe('apple');
 ```
 
 ## Initializing a Database
@@ -142,7 +151,7 @@ Then, you can read it like this:
 ```typescript
 const randomNumberCursor = await moment.getCursorByString('random-number');
 const randomNumber = await randomNumberCursor!.readBytesObject(MAX_READ_BYTES);
-console.log(new TextDecoder().decode(randomNumber.formatTag!)); // "bi"
+expect(new TextDecoder().decode(randomNumber.formatTag!)).toBe('bi');
 const randomBigInt = randomNumber.value;
 ```
 
@@ -176,12 +185,12 @@ const moment = await ReadHashMap.create(momentCursor!);
 // the food list includes the fruits
 const foodCursor = await moment.getCursorByString('food');
 const food = new ReadArrayList(foodCursor!);
-console.log(await food.count()); // 6
+expect(await food.count()).toBe(6);
 
 // ...but the fruits list hasn't been changed
 const fruitsCursor = await moment.getCursorByString('fruits');
 const fruits = new ReadArrayList(fruitsCursor!);
-console.log(await fruits.count()); // 3
+expect(await fruits.count()).toBe(3);
 ```
 
 Before we continue, let's save the latest history index, so we can revert back to this moment of the database later:
@@ -217,12 +226,12 @@ const moment = await ReadHashMap.create(momentCursor!);
 // the cities list contains all four
 const citiesCursor = await moment.getCursorByString('cities');
 const cities = new ReadArrayList(citiesCursor!);
-console.log(await cities.count()); // 4
+expect(await cities.count()).toBe(4);
 
 // ..but so does big-cities! we did not intend to mutate this
 const bigCitiesCursor = await moment.getCursorByString('big-cities');
 const bigCities = new ReadArrayList(bigCitiesCursor!);
-console.log(await bigCities.count()); // 4
+expect(await bigCities.count()).toBe(4);
 ```
 
 The reason that `big-cities` was mutated is because all data in a given transaction is temporarily mutable. This is a very important optimization, but in this case, it's not what we want.
@@ -263,12 +272,12 @@ const moment = await ReadHashMap.create(momentCursor!);
 // the cities list contains all four
 const citiesCursor = await moment.getCursorByString('cities');
 const cities = new ReadArrayList(citiesCursor!);
-console.log(await cities.count()); // 4
+expect(await cities.count()).toBe(4);
 
 // and big-cities only contains the original two
 const bigCitiesCursor = await moment.getCursorByString('big-cities');
 const bigCities = new ReadArrayList(bigCitiesCursor!);
-console.log(await bigCities.count()); // 2
+expect(await bigCities.count()).toBe(2);
 ```
 
 ## Large Byte Arrays
@@ -291,10 +300,16 @@ To read a byte array incrementally, get a reader from a cursor:
 ```typescript
 const longTextCursor = await moment.getCursorByString('long-text');
 const cursorReader = await longTextCursor!.reader();
-const content = new Uint8Array(Number(await longTextCursor!.count()));
-await cursorReader.readFully(content);
-const lines = new TextDecoder().decode(content).split('\n').filter(l => l.length > 0);
-console.log(lines.length); // 50
+let lineCount = 0, line: number[] = [];
+const buf = new Uint8Array(1024);
+for (let n; (n = await cursorReader.read(buf)) > 0; ) {
+  for (let i = 0; i < n; i++) {
+    if (buf[i] === 0x0A) { lineCount++; line = []; }
+    else line.push(buf[i]);
+  }
+}
+if (line.length > 0) lineCount++;
+expect(lineCount).toBe(50);
 ```
 
 ## Iterators
@@ -305,13 +320,11 @@ All data structures support iteration. Here's an example of iterating over an `A
 const peopleCursor = await moment.getCursorByString('people');
 const people = new ReadArrayList(peopleCursor!);
 
-const peopleIter = people.iterator();
-await peopleIter.init();
+const peopleIter = await people.iterator();
 while (await peopleIter.hasNext()) {
   const personCursor = await peopleIter.next();
   const person = await ReadHashMap.create(personCursor!);
-  const personIter = person.iterator();
-  await personIter.init();
+  const personIter = await person.iterator();
   while (await personIter.hasNext()) {
     const kvPairCursor = await personIter.next();
     const kvPair = await kvPairCursor!.readKeyValuePair();
@@ -358,7 +371,7 @@ The size of the hash in bytes will be stored in the database's header. If you tr
 ```typescript
 await core.seek(0);
 const header = await Header.read(core);
-console.log(header.hashSize); // 20
+expect(header.hashSize).toBe(20);
 ```
 
 The hash size alone does not disambiguate hashing algorithms, though. In addition, xitdb reserves four bytes in the header that you can use to put the name of the algorithm. You must provide it in the `Hasher` constructor:
@@ -372,7 +385,7 @@ The hash id is only written to the database header when it is first initialized.
 ```typescript
 await core.seek(0);
 const header = await Header.read(core);
-console.log(Hasher.idToString(header.hashId)); // "sha1"
+expect(Hasher.idToString(header.hashId)).toBe("sha1");
 ```
 
 If you want to use SHA-256, I recommend using `sha2` as the hash id. You can then distinguish between SHA-256 and SHA-512 using the hash size, like this:

package/dist/index.js

@@ -332,14 +332,10 @@ class CursorIterator {
   index = 0;
   stack = [];
   nextCursorMaybe = null;
-  initialized = false;
   constructor(cursor) {
     this.cursor = cursor;
   }
   async init() {
-    if (this.initialized)
-      return;
-    this.initialized = true;
     switch (this.cursor.slotPtr.slot.tag) {
       case 0 /* NONE */:
         this.size = 0;
@@ -400,7 +396,6 @@ class CursorIterator {
     return [new IteratorLevel(position, indexBlock, 0)];
   }
   async hasNext() {
-    await this.init();
     switch (this.cursor.slotPtr.slot.tag) {
       case 0 /* NONE */:
         return false;
@@ -421,7 +416,6 @@ class CursorIterator {
     }
   }
   async next() {
-    await this.init();
     switch (this.cursor.slotPtr.slot.tag) {
       case 0 /* NONE */:
         return null;
@@ -695,8 +689,7 @@ var init_read_cursor = __esm(() => {
       }
     }
     async* [Symbol.asyncIterator]() {
-      const iterator = new CursorIterator(this);
-      await iterator.init();
+      const iterator = await this.iterator();
       while (await iterator.hasNext()) {
         const next = await iterator.next();
         if (next !== null) {
@@ -704,8 +697,10 @@ var init_read_cursor = __esm(() => {
         }
       }
     }
-    iterator() {
-      return new CursorIterator(this);
+    async iterator() {
+      const iterator = new CursorIterator(this);
+      await iterator.init();
+      return iterator;
     }
   };
 });
@@ -818,8 +813,7 @@ var init_write_cursor = __esm(() => {
       return new Writer(this, 0, new Slot(ptrPos, 6 /* BYTES */), startPosition, 0);
     }
     async* [Symbol.asyncIterator]() {
-      const iterator = new WriteCursorIterator(this);
-      await iterator.init();
+      const iterator = await this.iterator();
       while (await iterator.hasNext()) {
         const next = await iterator.next();
         if (next !== null) {
@@ -827,8 +821,10 @@ var init_write_cursor = __esm(() => {
         }
       }
     }
-    iterator() {
-      return new WriteCursorIterator(this);
+    async iterator() {
+      const iterator = new WriteCursorIterator(this);
+      await iterator.init();
+      return iterator;
     }
   };
   WriteCursorIterator = class WriteCursorIterator extends CursorIterator {
@@ -3197,7 +3193,7 @@ class ReadArrayList {
   async count() {
     return this.cursor.count();
   }
-  iterator() {
+  async iterator() {
     return this.cursor.iterator();
   }
   async* [Symbol.asyncIterator]() {
@@ -3221,7 +3217,7 @@ class WriteArrayList extends ReadArrayList {
     const newCursor = await cursor.writePath([new ArrayListInit]);
     return new WriteArrayList(newCursor);
   }
-  iterator() {
+  async iterator() {
     return this.cursor.iterator();
   }
   async* [Symbol.asyncIterator]() {
@@ -3280,7 +3276,7 @@ class ReadHashMap {
   slot() {
     return this.cursor.slot();
   }
-  iterator() {
+  async iterator() {
     return this.cursor.iterator();
   }
   async* [Symbol.asyncIterator]() {
@@ -3362,7 +3358,7 @@ class WriteHashMap extends ReadHashMap {
     map.cursor = newCursor;
     return map;
   }
-  iterator() {
+  async iterator() {
     return this.cursor.iterator();
   }
   async* [Symbol.asyncIterator]() {
@@ -3470,7 +3466,7 @@ class ReadHashSet {
   slot() {
     return this.cursor.slot();
   }
-  iterator() {
+  async iterator() {
     return this.cursor.iterator();
   }
   async* [Symbol.asyncIterator]() {
@@ -3514,7 +3510,7 @@ class WriteHashSet extends ReadHashSet {
     set.cursor = newCursor;
     return set;
   }
-  iterator() {
+  async iterator() {
     return this.cursor.iterator();
   }
   async* [Symbol.asyncIterator]() {
@@ -3591,7 +3587,7 @@ class ReadLinkedArrayList {
   async count() {
     return this.cursor.count();
   }
-  iterator() {
+  async iterator() {
     return this.cursor.iterator();
   }
   async* [Symbol.asyncIterator]() {
@@ -3615,7 +3611,7 @@ class WriteLinkedArrayList extends ReadLinkedArrayList {
     const newCursor = await cursor.writePath([new LinkedArrayListInit]);
     return new WriteLinkedArrayList(newCursor);
   }
-  iterator() {
+  async iterator() {
     return this.cursor.iterator();
   }
   async* [Symbol.asyncIterator]() {

package/dist/read-array-list.d.ts

@@ -6,7 +6,7 @@ export declare class ReadArrayList implements Slotted {
     constructor(cursor: ReadCursor);
     slot(): Slot;
     count(): Promise<number>;
-    iterator(): CursorIterator;
+    iterator(): Promise<CursorIterator>;
     [Symbol.asyncIterator](): AsyncIterator<ReadCursor>;
     getCursor(index: number): Promise<ReadCursor | null>;
     getSlot(index: number): Promise<Slot | null>;

package/dist/read-cursor.d.ts

@@ -25,7 +25,7 @@ export declare class ReadCursor implements Slotted {
     reader(): Promise<Reader>;
     count(): Promise<number>;
     [Symbol.asyncIterator](): AsyncIterator<ReadCursor>;
-    iterator(): CursorIterator;
+    iterator(): Promise<CursorIterator>;
 }
 export declare class Reader {
     parent: ReadCursor;
@@ -47,7 +47,6 @@ export declare class CursorIterator {
     index: number;
     private stack;
     private nextCursorMaybe;
-    private initialized;
     constructor(cursor: ReadCursor);
     init(): Promise<void>;
     private initStack;

package/dist/read-hash-map.d.ts

@@ -7,7 +7,7 @@ export declare class ReadHashMap implements Slotted {
     protected constructor();
     static create(cursor: ReadCursor): Promise<ReadHashMap>;
     slot(): Slot;
-    iterator(): CursorIterator;
+    iterator(): Promise<CursorIterator>;
     [Symbol.asyncIterator](): AsyncIterator<ReadCursor>;
     getCursorByString(key: string): Promise<ReadCursor | null>;
     getSlotByString(key: string): Promise<Slot | null>;

package/dist/read-hash-set.d.ts

@@ -7,7 +7,7 @@ export declare class ReadHashSet implements Slotted {
     protected constructor();
     static create(cursor: ReadCursor): Promise<ReadHashSet>;
     slot(): Slot;
-    iterator(): CursorIterator;
+    iterator(): Promise<CursorIterator>;
     [Symbol.asyncIterator](): AsyncIterator<ReadCursor>;
     getCursorByString(key: string): Promise<ReadCursor | null>;
     getSlotByString(key: string): Promise<Slot | null>;

package/dist/read-linked-array-list.d.ts

@@ -6,7 +6,7 @@ export declare class ReadLinkedArrayList implements Slotted {
     constructor(cursor: ReadCursor);
     slot(): Slot;
     count(): Promise<number>;
-    iterator(): CursorIterator;
+    iterator(): Promise<CursorIterator>;
     [Symbol.asyncIterator](): AsyncIterator<ReadCursor>;
     getCursor(index: number): Promise<ReadCursor | null>;
     getSlot(index: number): Promise<Slot | null>;

package/dist/write-array-list.d.ts

@@ -5,7 +5,7 @@ import type { WriteableData } from './writeable-data';
 export declare class WriteArrayList extends ReadArrayList {
     constructor(cursor: WriteCursor);
     static create(cursor: WriteCursor): Promise<WriteArrayList>;
-    iterator(): WriteCursorIterator;
+    iterator(): Promise<WriteCursorIterator>;
     [Symbol.asyncIterator](): AsyncIterator<WriteCursor>;
     put(index: number, data: WriteableData): Promise<void>;
     putCursor(index: number): Promise<WriteCursor>;

package/dist/write-cursor.d.ts

@@ -16,7 +16,7 @@ export declare class WriteCursor extends ReadCursor {
     readKeyValuePair(): Promise<WriteKeyValuePairCursor>;
     writer(): Promise<Writer>;
     [Symbol.asyncIterator](): AsyncIterator<WriteCursor>;
-    iterator(): WriteCursorIterator;
+    iterator(): Promise<WriteCursorIterator>;
 }
 export declare class Writer {
     parent: WriteCursor;

package/dist/write-hash-map.d.ts

@@ -5,7 +5,7 @@ import { Bytes } from './writeable-data';
 export declare class WriteHashMap extends ReadHashMap {
     protected constructor();
     static create(cursor: WriteCursor): Promise<WriteHashMap>;
-    iterator(): WriteCursorIterator;
+    iterator(): Promise<WriteCursorIterator>;
     [Symbol.asyncIterator](): AsyncIterator<WriteCursor>;
     putByString(key: string, data: WriteableData): Promise<void>;
     putCursorByString(key: string): Promise<WriteCursor>;

package/dist/write-hash-set.d.ts

@@ -5,7 +5,7 @@ import { Bytes } from './writeable-data';
 export declare class WriteHashSet extends ReadHashSet {
     protected constructor();
     static create(cursor: WriteCursor): Promise<WriteHashSet>;
-    iterator(): WriteCursorIterator;
+    iterator(): Promise<WriteCursorIterator>;
     [Symbol.asyncIterator](): AsyncIterator<WriteCursor>;
     putByString(key: string): Promise<void>;
     putCursorByString(key: string): Promise<WriteCursor>;

package/dist/write-linked-array-list.d.ts

@@ -5,7 +5,7 @@ import type { WriteableData } from './writeable-data';
 export declare class WriteLinkedArrayList extends ReadLinkedArrayList {
     constructor(cursor: WriteCursor);
     static create(cursor: WriteCursor): Promise<WriteLinkedArrayList>;
-    iterator(): WriteCursorIterator;
+    iterator(): Promise<WriteCursorIterator>;
     [Symbol.asyncIterator](): AsyncIterator<WriteCursor>;
     put(index: number, data: WriteableData): Promise<void>;
     putCursor(index: number): Promise<WriteCursor>;

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "xitdb",
-  "version": "0.3.0",
-  "description": "An immutable database for TypeScript",
+  "version": "0.5.0",
+  "description": "An immutable database",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/radarroark/xitdb-ts.git"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",