@frostpillar/frostpillar-storage-engine 0.1.0 → 0.1.1

package/README-JA.md

@@ -207,16 +207,29 @@ const db = new Datastore({
 
 #### ペイロードバリデーション
 
-ペイロードは `put()`、`putMany()`、`updateById()` の呼び出しごとにバリデーションされます。以下の制限が適用されます：
+ペイロードは `put()`、`putMany()`、`updateById()`、`replaceById()` の呼び出しごとにバリデーションされます。以下のデフォルト制限が適用されます：
 
-| 制約 | 上限 |
-|------|------|
-| ペイロード合計バイト数 | 1,048,576（1 MB） |
-| 最大ネスト深度 | 64 オブジェクトレベル |
-| キー合計数 | 4,096 |
-| オブジェクトあたりの最大キー数 | 256 |
-| キーの最大サイズ | 1,024 バイト（UTF-8） |
-| 文字列値の最大サイズ | 65,535 バイト（UTF-8） |
+| 制約 | デフォルト | 設定キー |
+|------|-----------|----------|
+| ペイロード合計バイト数 | 1,048,576（1 MB） | `maxTotalBytes` |
+| 最大ネスト深度 | 64 オブジェクトレベル | `maxDepth` |
+| キー合計数 | 4,096 | `maxTotalKeys` |
+| オブジェクトあたりの最大キー数 | 256 | `maxKeysPerObject` |
+| キーの最大サイズ | 1,024 バイト（UTF-8） | `maxKeyBytes` |
+| 文字列値の最大サイズ | 65,535 バイト（UTF-8） | `maxStringBytes` |
+
+これらの制限は `payloadLimits` でデータストアごとにカスタマイズできます：
+
+```ts
+const db = new Datastore({
+  payloadLimits: {
+    maxDepth: 8,
+    maxTotalBytes: 4096,
+  },
+});
+```
+
+各フィールドは独立してオプションです。省略されたフィールドはデフォルト値を使用します。各値は正の安全な整数である必要があり、そうでない場合は `ConfigurationError` で構築が失敗します。
 
 追加ルール：
 - ペイロードはプレーンオブジェクトである必要があります（トップレベルで配列、関数、`BigInt` は不可）。
@@ -231,7 +244,7 @@ const db = new Datastore({
 const db = new Datastore({ skipPayloadValidation: true });
 ```
 
-> **警告:** バリデーションのスキップは、すべてのペイロード安全チェックを無効化します。入力が正しい形式であることが確実な場合のみ使用してください。
+> **警告:** バリデーションのスキップは、すべてのペイロード安全チェックを無効化し、`payloadLimits` も無視されます。入力が正しい形式であることが確実な場合のみ使用してください。
 
 ---
 
@@ -316,6 +329,12 @@ const exists = await db.has('k1');
 const updated = await db.updateById(id, { name: 'Alice V2' });
 ```
 
+**`replaceById(id, payload)`** — `_id` で指定したレコードの payload を完全に置換します。`updateById` とは異なり、新しい payload に存在しない既存フィールドは削除されます。見つかった場合は `true`、見つからなかった場合は `false` を返します。`key` や `_id` は変更されません。
+
+```ts
+const replaced = await db.replaceById(id, { name: 'Alice V3', score: 100 });
+```
+
 #### 削除
 
 **`delete(key)`** — 指定キーのすべてのレコードを削除します。削除件数を返します。
@@ -336,6 +355,12 @@ const removed = await db.deleteById(id);
 const count = await db.deleteMany(['k1', 'k2']);
 ```
 
+**`deleteByIds(ids)`** — `_id` の配列でレコードを削除します。実際に削除された件数を返します（存在しない id はスキップされます）。
+
+```ts
+const count = await db.deleteByIds([id1, id2, id3]);
+```
+
 **`clear()`** — 全レコードを削除します。
 
 ```ts
@@ -1090,11 +1115,12 @@ try {
 
 ### ID ベース操作
 
-| メソッド                | パラメータ                | 戻り値                         | 説明                 |
-| ----------------------- | ------------------------- | ------------------------------ | -------------------- |
-| `getById(id)`           | `EntryId`                 | `Promise<KeyedRecord \| null>` | レコード ID で取得   |
-| `updateById(id, patch)` | `EntryId`、payload パッチ | `Promise<boolean>`             | shallow merge で更新 |
-| `deleteById(id)`        | `EntryId`                 | `Promise<boolean>`             | レコード ID で削除   |
+| メソッド                       | パラメータ                | 戻り値                         | 説明                   |
+| ------------------------------ | ------------------------- | ------------------------------ | ---------------------- |
+| `getById(id)`                  | `EntryId`                 | `Promise<KeyedRecord \| null>` | レコード ID で取得     |
+| `updateById(id, patch)`        | `EntryId`、payload パッチ | `Promise<boolean>`             | shallow merge で更新   |
+| `replaceById(id, payload)`     | `EntryId`、完全な payload | `Promise<boolean>`             | payload を完全置換     |
+| `deleteById(id)`               | `EntryId`                 | `Promise<boolean>`             | レコード ID で削除     |
 
 ### バルク操作
 
@@ -1105,6 +1131,7 @@ try {
 | `getMany(keys)`        | キー配列           | `Promise<KeyedRecord[]>` | 複数キーのレコード       |
 | `putMany(records)`     | レコード配列       | `Promise<void>`          | 複数レコードを挿入       |
 | `deleteMany(keys)`     | キー配列           | `Promise<number>`        | 複数キーのレコードを削除 |
+| `deleteByIds(ids)`     | `EntryId` 配列     | `Promise<number>`        | レコード ID 群で削除     |
 | `clear()`              | —                  | `Promise<void>`          | 全レコードを削除         |
 
 ### メタデータ

package/README.md

@@ -207,16 +207,29 @@ const db = new Datastore({
 
 #### Payload Validation
 
-Payloads are validated on every `put()`, `putMany()`, and `updateById()` call. The following limits apply:
+Payloads are validated on every `put()`, `putMany()`, `updateById()`, and `replaceById()` call. The following default limits apply:
 
-| Constraint | Limit |
-|------------|-------|
-| Total payload bytes | 1,048,576 (1 MB) |
-| Max nesting depth | 64 object levels |
-| Max total keys | 4,096 |
-| Max keys per object | 256 |
-| Max key size | 1,024 bytes (UTF-8) |
-| Max string value | 65,535 bytes (UTF-8) |
+| Constraint | Default | Config key |
+|------------|---------|------------|
+| Total payload bytes | 1,048,576 (1 MB) | `maxTotalBytes` |
+| Max nesting depth | 64 object levels | `maxDepth` |
+| Max total keys | 4,096 | `maxTotalKeys` |
+| Max keys per object | 256 | `maxKeysPerObject` |
+| Max key size | 1,024 bytes (UTF-8) | `maxKeyBytes` |
+| Max string value | 65,535 bytes (UTF-8) | `maxStringBytes` |
+
+These limits can be customized per-datastore via `payloadLimits`:
+
+```ts
+const db = new Datastore({
+  payloadLimits: {
+    maxDepth: 8,
+    maxTotalBytes: 4096,
+  },
+});
+```
+
+Each field is independently optional; omitted fields use the default value. Each value must be a positive safe integer, otherwise construction fails with `ConfigurationError`.
 
 Additional rules:
 - Payload must be a plain object (no arrays, functions, or `BigInt` at top level).
@@ -231,7 +244,7 @@ For trusted input where you control the shape, you can skip validation:
 const db = new Datastore({ skipPayloadValidation: true });
 ```
 
-> **Warning:** Skipping validation disables all payload safety checks. Only use this when you are certain the input is well-formed.
+> **Warning:** Skipping validation disables all payload safety checks and ignores `payloadLimits`. Only use this when you are certain the input is well-formed.
 
 ---
 
@@ -316,6 +329,12 @@ All record-returning APIs include the `_id` field in the result.
 const updated = await db.updateById(id, { name: 'Alice V2' });
 ```
 
+**`replaceById(id, payload)`** — fully replace the payload of a record by `_id`. Unlike `updateById`, existing fields not present in the new payload are removed. Returns `true` if found, `false` otherwise. Does not change `key` or `_id`.
+
+```ts
+const replaced = await db.replaceById(id, { name: 'Alice V3', score: 100 });
+```
+
 #### Delete
 
 **`delete(key)`** — remove all records with `key`. Returns the number of records removed.
@@ -336,6 +355,12 @@ const removed = await db.deleteById(id);
 const count = await db.deleteMany(['k1', 'k2']);
 ```
 
+**`deleteByIds(ids)`** — remove records by their `_id` values. Returns total deleted (non-existent ids are skipped).
+
+```ts
+const count = await db.deleteByIds([id1, id2, id3]);
+```
+
 **`clear()`** — remove all records.
 
 ```ts
@@ -1090,11 +1115,12 @@ If both a deferred backend initialization failure and a backend close failure oc
 
 ### ID-Based Operations
 
-| Method                  | Parameters               | Returns                        | Description          |
-| ----------------------- | ------------------------ | ------------------------------ | -------------------- |
-| `getById(id)`           | `EntryId`                | `Promise<KeyedRecord \| null>` | Get by record ID     |
-| `updateById(id, patch)` | `EntryId`, payload patch | `Promise<boolean>`             | Shallow-merge update |
-| `deleteById(id)`        | `EntryId`                | `Promise<boolean>`             | Delete by record ID  |
+| Method                     | Parameters               | Returns                        | Description            |
+| -------------------------- | ------------------------ | ------------------------------ | ---------------------- |
+| `getById(id)`              | `EntryId`                | `Promise<KeyedRecord \| null>` | Get by record ID       |
+| `updateById(id, patch)`    | `EntryId`, payload patch | `Promise<boolean>`             | Shallow-merge update   |
+| `replaceById(id, payload)` | `EntryId`, full payload  | `Promise<boolean>`             | Full payload replace   |
+| `deleteById(id)`           | `EntryId`                | `Promise<boolean>`             | Delete by record ID    |
 
 ### Bulk Operations
 
@@ -1105,6 +1131,7 @@ If both a deferred backend initialization failure and a backend close failure oc
 | `getMany(keys)`        | key array          | `Promise<KeyedRecord[]>` | Records for multiple keys   |
 | `putMany(records)`     | record array       | `Promise<void>`          | Insert multiple records     |
 | `deleteMany(keys)`     | key array          | `Promise<number>`        | Delete across multiple keys |
+| `deleteByIds(ids)`     | `EntryId` array    | `Promise<number>`        | Delete by record IDs        |
 | `clear()`              | —                  | `Promise<void>`          | Remove all records          |
 
 ### Metadata

package/dist/drivers/file.cjs

@@ -254,6 +254,34 @@ var createCloseAggregateError = (flushError, drainError) => {
   return fallbackError;
 };
 
+// src/storage/backend/encoding.ts
+var computeUtf8ByteLengthJs = (value) => {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 127) {
+      bytes += 1;
+    } else if (code <= 2047) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      bytes += 3;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
+var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
+
 // src/storage/config/config.shared.ts
 var BYTE_SIZE_MULTIPLIER = {
   B: 1,
@@ -576,34 +604,6 @@ var releaseFileLock = (backend) => {
 var import_node_fs3 = require("node:fs");
 var import_node_path3 = require("node:path");
 
-// src/storage/backend/encoding.ts
-var computeUtf8ByteLengthJs = (value) => {
-  let bytes = 0;
-  for (let i = 0; i < value.length; i++) {
-    const code = value.charCodeAt(i);
-    if (code <= 127) {
-      bytes += 1;
-    } else if (code <= 2047) {
-      bytes += 2;
-    } else if (code >= 55296 && code <= 56319) {
-      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
-      if (next >= 56320 && next <= 57343) {
-        bytes += 4;
-        i++;
-      } else {
-        bytes += 3;
-      }
-    } else if (code >= 56320 && code <= 57343) {
-      bytes += 3;
-    } else {
-      bytes += 3;
-    }
-  }
-  return bytes;
-};
-var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
-var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
-
 // src/storage/btree/recordKeyIndexBTree.ts
 var import_frostpillar_btree = require("@frostpillar/frostpillar-btree");
 var clampComparatorResult = (compared) => {

package/dist/drivers/indexedDB.cjs

@@ -49,6 +49,34 @@ var toErrorInstance = (error, fallbackMessage) => {
   return new Error(fallbackMessage, { cause: error });
 };
 
+// src/storage/backend/encoding.ts
+var computeUtf8ByteLengthJs = (value) => {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 127) {
+      bytes += 1;
+    } else if (code <= 2047) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      bytes += 3;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
+var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
+
 // src/storage/config/config.shared.ts
 var BYTE_SIZE_MULTIPLIER = {
   B: 1,
@@ -339,34 +367,6 @@ var parseNonNegativeSafeInteger = (value, fieldName, backendName) => {
   return value;
 };
 
-// src/storage/backend/encoding.ts
-var computeUtf8ByteLengthJs = (value) => {
-  let bytes = 0;
-  for (let i = 0; i < value.length; i++) {
-    const code = value.charCodeAt(i);
-    if (code <= 127) {
-      bytes += 1;
-    } else if (code <= 2047) {
-      bytes += 2;
-    } else if (code >= 55296 && code <= 56319) {
-      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
-      if (next >= 56320 && next <= 57343) {
-        bytes += 4;
-        i++;
-      } else {
-        bytes += 3;
-      }
-    } else if (code >= 56320 && code <= 57343) {
-      bytes += 3;
-    } else {
-      bytes += 3;
-    }
-  }
-  return bytes;
-};
-var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
-var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
-
 // src/storage/drivers/IndexedDB/indexedDBBackend.ts
 var IDB_MAGIC = "FPIDB_META";
 var IDB_VERSION_VALUE = 2;

package/dist/drivers/localStorage.cjs

@@ -240,6 +240,34 @@ var createCloseAggregateError = (flushError, drainError) => {
   return fallbackError;
 };
 
+// src/storage/backend/encoding.ts
+var computeUtf8ByteLengthJs = (value) => {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 127) {
+      bytes += 1;
+    } else if (code <= 2047) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      bytes += 3;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
+var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
+
 // src/storage/config/config.shared.ts
 var BYTE_SIZE_MULTIPLIER = {
   B: 1,
@@ -376,34 +404,6 @@ var isQuotaBrowserError = (error) => {
   return error.name === "QuotaExceededError" || error.name === "NS_ERROR_DOM_QUOTA_REACHED";
 };
 
-// src/storage/backend/encoding.ts
-var computeUtf8ByteLengthJs = (value) => {
-  let bytes = 0;
-  for (let i = 0; i < value.length; i++) {
-    const code = value.charCodeAt(i);
-    if (code <= 127) {
-      bytes += 1;
-    } else if (code <= 2047) {
-      bytes += 2;
-    } else if (code >= 55296 && code <= 56319) {
-      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
-      if (next >= 56320 && next <= 57343) {
-        bytes += 4;
-        i++;
-      } else {
-        bytes += 3;
-      }
-    } else if (code >= 56320 && code <= 57343) {
-      bytes += 3;
-    } else {
-      bytes += 3;
-    }
-  }
-  return bytes;
-};
-var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
-var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
-
 // src/storage/drivers/localStorage/localStorageBackend.ts
 var LS_MAGIC = "FPLS_META";
 var LS_VERSION = 2;

package/dist/drivers/opfs.cjs

@@ -60,6 +60,34 @@ var toErrorInstance = (error, fallbackMessage) => {
   return new Error(fallbackMessage, { cause: error });
 };
 
+// src/storage/backend/encoding.ts
+var computeUtf8ByteLengthJs = (value) => {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 127) {
+      bytes += 1;
+    } else if (code <= 2047) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      bytes += 3;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
+var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
+
 // src/storage/config/config.shared.ts
 var BYTE_SIZE_MULTIPLIER = {
   B: 1,
@@ -321,34 +349,6 @@ var parseNonNegativeSafeInteger = (value, fieldName, backendName) => {
   return value;
 };
 
-// src/storage/backend/encoding.ts
-var computeUtf8ByteLengthJs = (value) => {
-  let bytes = 0;
-  for (let i = 0; i < value.length; i++) {
-    const code = value.charCodeAt(i);
-    if (code <= 127) {
-      bytes += 1;
-    } else if (code <= 2047) {
-      bytes += 2;
-    } else if (code >= 55296 && code <= 56319) {
-      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
-      if (next >= 56320 && next <= 57343) {
-        bytes += 4;
-        i++;
-      } else {
-        bytes += 3;
-      }
-    } else if (code >= 56320 && code <= 57343) {
-      bytes += 3;
-    } else {
-      bytes += 3;
-    }
-  }
-  return bytes;
-};
-var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
-var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
-
 // src/storage/drivers/opfs/opfsBackend.ts
 var OPFS_MAGIC = "FPOPFS_META";
 var OPFS_VERSION_VALUE = 2;

package/dist/drivers/syncStorage.cjs

@@ -51,6 +51,34 @@ var toErrorInstance = (error, fallbackMessage) => {
   return new Error(fallbackMessage, { cause: error });
 };
 
+// src/storage/backend/encoding.ts
+var computeUtf8ByteLengthJs = (value) => {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 127) {
+      bytes += 1;
+    } else if (code <= 2047) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      bytes += 3;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
+var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
+
 // src/storage/config/config.shared.ts
 var BYTE_SIZE_MULTIPLIER = {
   B: 1,
@@ -589,34 +617,6 @@ var validateSyncStorageCommitQuota = (state, generation, chunks, manifest, resol
   }
 };
 
-// src/storage/backend/encoding.ts
-var computeUtf8ByteLengthJs = (value) => {
-  let bytes = 0;
-  for (let i = 0; i < value.length; i++) {
-    const code = value.charCodeAt(i);
-    if (code <= 127) {
-      bytes += 1;
-    } else if (code <= 2047) {
-      bytes += 2;
-    } else if (code >= 55296 && code <= 56319) {
-      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
-      if (next >= 56320 && next <= 57343) {
-        bytes += 4;
-        i++;
-      } else {
-        bytes += 3;
-      }
-    } else if (code >= 56320 && code <= 57343) {
-      bytes += 3;
-    } else {
-      bytes += 3;
-    }
-  }
-  return bytes;
-};
-var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
-var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
-
 // src/storage/drivers/syncStorage/syncStorageBackend.ts
 var SYNC_STORAGE_MAGIC = "FPSYNC_META";
 var SYNC_STORAGE_VERSION = 2;