npm - @alstate/sqlite - Versions diffs - 0.1.0 → 0.1.1 - Mend

@alstate/sqlite 0.1.0 → 0.1.1

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 (5) hide show

package/LICENSE +21 -21
package/README.md +53 -3
package/dist/migrations.js +61 -61
package/dist/sqlite-learning-store.js +72 -72
package/package.json +34 -34

package/LICENSE CHANGED Viewed

@@ -1,21 +1,21 @@
-MIT License
-Copyright (c) 2026 Alstate contributors
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+Copyright (c) 2026 Alstate contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -3,13 +3,63 @@
 Experimental SQLite persistence adapter for `@alstate/core`, implemented with
 Node.js `node:sqlite`.
+## Requirements and install
+Node.js 22.13 or later is required.
+```bash
+npm install @alstate/core @alstate/sqlite
+```
+Add a scheduling algorithm separately; `@alstate/fsrs` is the first-party
+choice.
+## Use
 ```ts
+import { LearningEngine } from "@alstate/core";
+import { FsrsAlgorithm } from "@alstate/fsrs";
 import { SqliteLearningStore } from "@alstate/sqlite";
-const store = new SqliteLearningStore("learning.db");
+const engine = await LearningEngine.create({
+  store: new SqliteLearningStore("data/learning.db"),
+  algorithm: new FsrsAlgorithm(),
+});
+try {
+  const item = await engine.add({ prompt: "2 + 2", answer: "4" });
+  await engine.review(item.id, "good");
+} finally {
+  engine.close();
+}
 ```
-Requires Node.js 22.13 or later. The adapter applies schema migrations on open,
-uses transactions for composite writes and rejects stale review revisions.
+The constructor defaults to an in-memory database when no path is supplied:
+```ts
+const store = new SqliteLearningStore(); // ":memory:"
+```
+For a file path, missing parent directories are created automatically. The
+adapter opens or creates the database, enables foreign keys, applies pending
+schema migrations and sets a 5-second busy timeout.
+## Behavior
+- item creation and initial-state creation share one transaction;
+- state update and review insertion share one transaction;
+- reviews compare and increment a state revision, rejecting stale writers with
+  `ConcurrentReviewError`;
+- operations are scoped to the registered algorithm;
+- deleting an item cascades to state and review history;
+- items are ordered by ID, due items by due time then ID, and history newest
+  first;
+- timestamps are persisted as ISO 8601 strings and returned as `Date` objects.
+`engine.close()` closes its store. Do not reuse the connection afterward.
+- [SQLite and FSRS adapter guide](https://github.com/laiqfun/alstate/blob/main/docs/adapters.md)
+- [SQLite data model](https://github.com/laiqfun/alstate/blob/main/docs/data-model.md)
+- [Core API reference](https://github.com/laiqfun/alstate/blob/main/docs/api-reference.md)
 MIT

package/dist/migrations.js CHANGED Viewed

@@ -2,80 +2,80 @@ const migrations = [
     {
         version: 1,
         name: "learning_engine_schema",
-        sql: `
-      CREATE TABLE engine_items (
-        id INTEGER PRIMARY KEY,
-        data_json TEXT NOT NULL CHECK (json_valid(data_json))
-      ) STRICT;
-      CREATE TABLE engine_algorithms (
-        id INTEGER PRIMARY KEY,
-        name TEXT NOT NULL UNIQUE CHECK (length(trim(name)) > 0),
-        description TEXT,
-        version TEXT NOT NULL CHECK (length(trim(version)) > 0),
-        config_json TEXT NOT NULL CHECK (json_valid(config_json))
-      ) STRICT;
-      CREATE TABLE engine_states (
-        id INTEGER PRIMARY KEY,
-        learning_item_id INTEGER NOT NULL,
-        algorithm_id INTEGER NOT NULL,
-        due_at TEXT NOT NULL,
-        state_json TEXT NOT NULL CHECK (json_valid(state_json)),
-        UNIQUE (learning_item_id, algorithm_id),
-        FOREIGN KEY (learning_item_id)
-          REFERENCES engine_items (id) ON DELETE CASCADE,
-        FOREIGN KEY (algorithm_id)
-          REFERENCES engine_algorithms (id) ON DELETE RESTRICT
-      ) STRICT;
-      CREATE INDEX engine_states_due_idx
-        ON engine_states (algorithm_id, due_at, learning_item_id);
-      CREATE TABLE engine_reviews (
-        id INTEGER PRIMARY KEY,
-        learning_item_id INTEGER NOT NULL,
-        algorithm_id INTEGER NOT NULL,
-        rating TEXT NOT NULL CHECK (length(trim(rating)) > 0),
-        review_json TEXT NOT NULL CHECK (json_valid(review_json)),
-        response_time_ms INTEGER CHECK (
-          response_time_ms IS NULL OR response_time_ms >= 0
-        ),
-        reviewed_at TEXT NOT NULL,
-        FOREIGN KEY (learning_item_id)
-          REFERENCES engine_items (id) ON DELETE CASCADE,
-        FOREIGN KEY (algorithm_id)
-          REFERENCES engine_algorithms (id) ON DELETE RESTRICT
-      ) STRICT;
-      CREATE INDEX engine_reviews_item_time_idx
-        ON engine_reviews (learning_item_id, reviewed_at DESC, id DESC);
+        sql: `
+      CREATE TABLE engine_items (
+        id INTEGER PRIMARY KEY,
+        data_json TEXT NOT NULL CHECK (json_valid(data_json))
+      ) STRICT;
+      CREATE TABLE engine_algorithms (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL UNIQUE CHECK (length(trim(name)) > 0),
+        description TEXT,
+        version TEXT NOT NULL CHECK (length(trim(version)) > 0),
+        config_json TEXT NOT NULL CHECK (json_valid(config_json))
+      ) STRICT;
+      CREATE TABLE engine_states (
+        id INTEGER PRIMARY KEY,
+        learning_item_id INTEGER NOT NULL,
+        algorithm_id INTEGER NOT NULL,
+        due_at TEXT NOT NULL,
+        state_json TEXT NOT NULL CHECK (json_valid(state_json)),
+        UNIQUE (learning_item_id, algorithm_id),
+        FOREIGN KEY (learning_item_id)
+          REFERENCES engine_items (id) ON DELETE CASCADE,
+        FOREIGN KEY (algorithm_id)
+          REFERENCES engine_algorithms (id) ON DELETE RESTRICT
+      ) STRICT;
+      CREATE INDEX engine_states_due_idx
+        ON engine_states (algorithm_id, due_at, learning_item_id);
+      CREATE TABLE engine_reviews (
+        id INTEGER PRIMARY KEY,
+        learning_item_id INTEGER NOT NULL,
+        algorithm_id INTEGER NOT NULL,
+        rating TEXT NOT NULL CHECK (length(trim(rating)) > 0),
+        review_json TEXT NOT NULL CHECK (json_valid(review_json)),
+        response_time_ms INTEGER CHECK (
+          response_time_ms IS NULL OR response_time_ms >= 0
+        ),
+        reviewed_at TEXT NOT NULL,
+        FOREIGN KEY (learning_item_id)
+          REFERENCES engine_items (id) ON DELETE CASCADE,
+        FOREIGN KEY (algorithm_id)
+          REFERENCES engine_algorithms (id) ON DELETE RESTRICT
+      ) STRICT;
+      CREATE INDEX engine_reviews_item_time_idx
+        ON engine_reviews (learning_item_id, reviewed_at DESC, id DESC);
     `,
     },
     {
         version: 2,
         name: "optimistic_review_concurrency",
-        sql: `
-      ALTER TABLE engine_states
-        ADD COLUMN revision INTEGER NOT NULL DEFAULT 0
-        CHECK (revision >= 0);
+        sql: `
+      ALTER TABLE engine_states
+        ADD COLUMN revision INTEGER NOT NULL DEFAULT 0
+        CHECK (revision >= 0);
     `,
     },
 ];
 export function migrateDatabase(database) {
-    database.exec(`
-    CREATE TABLE IF NOT EXISTS engine_schema_migrations (
-      version INTEGER PRIMARY KEY,
-      name TEXT NOT NULL UNIQUE,
-      applied_at TEXT NOT NULL
-    ) STRICT;
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS engine_schema_migrations (
+      version INTEGER PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE,
+      applied_at TEXT NOT NULL
+    ) STRICT;
   `);
     const applied = new Set(database
         .prepare("SELECT version FROM engine_schema_migrations")
         .all().map((row) => row.version));
-    const record = database.prepare(`
-    INSERT INTO engine_schema_migrations (version, name, applied_at)
-    VALUES (?, ?, ?)
+    const record = database.prepare(`
+    INSERT INTO engine_schema_migrations (version, name, applied_at)
+    VALUES (?, ?, ?)
   `);
     for (const migration of migrations) {
         if (applied.has(migration.version)) {

package/dist/sqlite-learning-store.js CHANGED Viewed

@@ -21,10 +21,10 @@ export class SqliteLearningStore {
         requireNonBlank(registration.name, "algorithm name");
         requireNonBlank(registration.version, "algorithm version");
         const existing = this.#database
-            .prepare(`
-        SELECT id, name, version, description, config_json
-        FROM engine_algorithms
-        WHERE name = ?
+            .prepare(`
+        SELECT id, name, version, description, config_json
+        FROM engine_algorithms
+        WHERE name = ?
       `)
             .get(registration.name);
         if (existing !== undefined) {
@@ -37,10 +37,10 @@ export class SqliteLearningStore {
             return stored;
         }
         const result = this.#database
-            .prepare(`
-        INSERT INTO engine_algorithms
-          (name, version, description, config_json)
-        VALUES (?, ?, ?, ?)
+            .prepare(`
+        INSERT INTO engine_algorithms
+          (name, version, description, config_json)
+        VALUES (?, ?, ?, ?)
       `)
             .run(registration.name, registration.version, registration.description ?? null, JSON.stringify(registration.configuration));
         return Object.freeze({
@@ -55,10 +55,10 @@ export class SqliteLearningStore {
                 .run(JSON.stringify(input.data));
             const id = learningItemId(toSafeInteger(itemResult.lastInsertRowid));
             this.#database
-                .prepare(`
-          INSERT INTO engine_states
-            (learning_item_id, algorithm_id, due_at, state_json)
-          VALUES (?, ?, ?, ?)
+                .prepare(`
+          INSERT INTO engine_states
+            (learning_item_id, algorithm_id, due_at, state_json)
+          VALUES (?, ?, ?, ?)
         `)
                 .run(id, input.algorithmId, isoDate(input.dueAt, "initial due time"), JSON.stringify(input.stateData));
             return freezeItem({ id, data: input.data });
@@ -66,11 +66,11 @@ export class SqliteLearningStore {
     }
     async findItem(id, registeredAlgorithmId) {
         const row = this.#database
-            .prepare(`
-        SELECT item.id, item.data_json
-        FROM engine_items item
-        JOIN engine_states state ON state.learning_item_id = item.id
-        WHERE item.id = ? AND state.algorithm_id = ?
+            .prepare(`
+        SELECT item.id, item.data_json
+        FROM engine_items item
+        JOIN engine_states state ON state.learning_item_id = item.id
+        WHERE item.id = ? AND state.algorithm_id = ?
       `)
             .get(id, registeredAlgorithmId);
         return row === undefined ? null : mapItem(row);
@@ -78,12 +78,12 @@ export class SqliteLearningStore {
     async listItems(registeredAlgorithmId, query = {}) {
         validatePage(query);
         const parameters = [registeredAlgorithmId];
-        let sql = `
-      SELECT item.id, item.data_json
-      FROM engine_items item
-      JOIN engine_states state ON state.learning_item_id = item.id
-      WHERE state.algorithm_id = ?
-      ORDER BY item.id
+        let sql = `
+      SELECT item.id, item.data_json
+      FROM engine_items item
+      JOIN engine_states state ON state.learning_item_id = item.id
+      WHERE state.algorithm_id = ?
+      ORDER BY item.id
     `;
         if (query.limit !== undefined) {
             sql += " LIMIT ?";
@@ -101,13 +101,13 @@ export class SqliteLearningStore {
     }
     async updateItem(id, registeredAlgorithmId, data) {
         const result = this.#database
-            .prepare(`
-        UPDATE engine_items SET data_json = ?
-        WHERE id = ? AND EXISTS (
-          SELECT 1 FROM engine_states state
-          WHERE state.learning_item_id = engine_items.id
-            AND state.algorithm_id = ?
-        )
+            .prepare(`
+        UPDATE engine_items SET data_json = ?
+        WHERE id = ? AND EXISTS (
+          SELECT 1 FROM engine_states state
+          WHERE state.learning_item_id = engine_items.id
+            AND state.algorithm_id = ?
+        )
       `)
             .run(JSON.stringify(data), id, registeredAlgorithmId);
         return toSafeInteger(result.changes) === 0
@@ -116,23 +116,23 @@ export class SqliteLearningStore {
     }
     async deleteItem(id, registeredAlgorithmId) {
         const result = this.#database
-            .prepare(`
-        DELETE FROM engine_items
-        WHERE id = ? AND EXISTS (
-          SELECT 1 FROM engine_states state
-          WHERE state.learning_item_id = engine_items.id
-            AND state.algorithm_id = ?
-        )
+            .prepare(`
+        DELETE FROM engine_items
+        WHERE id = ? AND EXISTS (
+          SELECT 1 FROM engine_states state
+          WHERE state.learning_item_id = engine_items.id
+            AND state.algorithm_id = ?
+        )
       `)
             .run(id, registeredAlgorithmId);
         return toSafeInteger(result.changes) > 0;
     }
     async findState(itemId, registeredAlgorithmId) {
         const row = this.#database
-            .prepare(`
-        SELECT id, learning_item_id, algorithm_id, revision, due_at, state_json
-        FROM engine_states
-        WHERE learning_item_id = ? AND algorithm_id = ?
+            .prepare(`
+        SELECT id, learning_item_id, algorithm_id, revision, due_at, state_json
+        FROM engine_states
+        WHERE learning_item_id = ? AND algorithm_id = ?
       `)
             .get(itemId, registeredAlgorithmId);
         return row === undefined ? null : mapState(row);
@@ -143,19 +143,19 @@ export class SqliteLearningStore {
             input.algorithmId,
             isoDate(input.dueAtOrBefore, "due query time"),
         ];
-        let sql = `
-      SELECT
-        item.id AS item_id,
-        item.data_json,
-        state.id AS state_id,
-        state.algorithm_id,
-        state.revision,
-        state.due_at,
-        state.state_json
-      FROM engine_states state
-      JOIN engine_items item ON item.id = state.learning_item_id
-      WHERE state.algorithm_id = ? AND state.due_at <= ?
-      ORDER BY state.due_at, item.id
+        let sql = `
+      SELECT
+        item.id AS item_id,
+        item.data_json,
+        state.id AS state_id,
+        state.algorithm_id,
+        state.revision,
+        state.due_at,
+        state.state_json
+      FROM engine_states state
+      JOIN engine_items item ON item.id = state.learning_item_id
+      WHERE state.algorithm_id = ? AND state.due_at <= ?
+      ORDER BY state.due_at, item.id
     `;
         if (input.limit !== undefined) {
             sql += " LIMIT ?";
@@ -184,10 +184,10 @@ export class SqliteLearningStore {
                 throw new TypeError("Review identity must match the state being updated.");
             }
             const update = this.#database
-                .prepare(`
-          UPDATE engine_states
-          SET due_at = ?, state_json = ?, revision = revision + 1
-          WHERE id = ? AND revision = ?
+                .prepare(`
+          UPDATE engine_states
+          SET due_at = ?, state_json = ?, revision = revision + 1
+          WHERE id = ? AND revision = ?
         `)
                 .run(isoDate(input.state.dueAt, "next due time"), JSON.stringify(input.state.data), input.state.state.id, input.state.state.revision);
             if (toSafeInteger(update.changes) !== 1) {
@@ -196,13 +196,13 @@ export class SqliteLearningStore {
             const review = input.review;
             validateResponseTime(review.responseTimeMs);
             const result = this.#database
-                .prepare(`
-          INSERT INTO engine_reviews
-            (
-              learning_item_id, algorithm_id, rating, review_json,
-              response_time_ms, reviewed_at
-            )
-          VALUES (?, ?, ?, ?, ?, ?)
+                .prepare(`
+          INSERT INTO engine_reviews
+            (
+              learning_item_id, algorithm_id, rating, review_json,
+              response_time_ms, reviewed_at
+            )
+          VALUES (?, ?, ?, ?, ?, ?)
         `)
                 .run(review.learningItemId, review.algorithmId, requireNonBlank(review.rating, "rating"), JSON.stringify(review.data), review.responseTimeMs ?? null, isoDate(review.reviewedAt, "review time"));
             return freezeReview({
@@ -214,13 +214,13 @@ export class SqliteLearningStore {
     async listReviews(itemId, registeredAlgorithmId, query = {}) {
         validatePage(query);
         const parameters = [itemId, registeredAlgorithmId];
-        let sql = `
-      SELECT
-        id, learning_item_id, algorithm_id, rating, review_json,
-        response_time_ms, reviewed_at
-      FROM engine_reviews
-      WHERE learning_item_id = ? AND algorithm_id = ?
-      ORDER BY reviewed_at DESC, id DESC
+        let sql = `
+      SELECT
+        id, learning_item_id, algorithm_id, rating, review_json,
+        response_time_ms, reviewed_at
+      FROM engine_reviews
+      WHERE learning_item_id = ? AND algorithm_id = ?
+      ORDER BY reviewed_at DESC, id DESC
     `;
         if (query.limit !== undefined) {
             sql += " LIMIT ?";

package/package.json CHANGED Viewed

@@ -1,34 +1,34 @@
-{
-  "name": "@alstate/sqlite",
-  "version": "0.1.0",
-  "description": "SQLite persistence adapter for Alstate.",
-  "keywords": ["learning", "scheduling", "sqlite", "spaced-repetition"],
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": ["dist", "README.md", "LICENSE"],
-  "sideEffects": false,
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "clean": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true }); require('node:fs').rmSync('.test-dist', { recursive: true, force: true })\"",
-    "test": "tsc --project tsconfig.test.json && node --test \".test-dist/test/**/*.test.js\"",
-    "typecheck": "tsc --project tsconfig.json --noEmit"
-  },
-  "dependencies": { "@alstate/core": "0.1.0" },
-  "engines": { "node": ">=22.13.0" },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/laiqfun/alstate.git",
-    "directory": "packages/sqlite"
-  },
-  "homepage": "https://github.com/laiqfun/alstate#readme",
-  "bugs": { "url": "https://github.com/laiqfun/alstate/issues" },
-  "publishConfig": { "access": "public" }
-}
+{
+  "name": "@alstate/sqlite",
+  "version": "0.1.1",
+  "description": "SQLite persistence adapter for Alstate.",
+  "keywords": ["learning", "scheduling", "sqlite", "spaced-repetition"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "clean": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true }); require('node:fs').rmSync('.test-dist', { recursive: true, force: true })\"",
+    "test": "tsc --project tsconfig.test.json && node --test \".test-dist/test/**/*.test.js\"",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  },
+  "dependencies": { "@alstate/core": "0.1.1" },
+  "engines": { "node": ">=22.13.0" },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laiqfun/alstate.git",
+    "directory": "packages/sqlite"
+  },
+  "homepage": "https://github.com/laiqfun/alstate#readme",
+  "bugs": { "url": "https://github.com/laiqfun/alstate/issues" },
+  "publishConfig": { "access": "public" }
+}