@frostpillar/frostpillar-storage-engine 0.1.0 → 0.1.1

package/dist/storage/datastore/mutationById.js

@@ -9,15 +9,14 @@ export const getPublicRecordById = (keyIndex, entryId) => {
     }
     return toPublicRecord(entryId, entry.key, entry.value);
 };
-const buildMergedPayload = (targetRecord, patch, entryKey, skipValidation) => {
-    const merged = { ...targetRecord.payload, ...patch };
+export const validateAndEstimateSize = (payload, entryKey, skipValidation, payloadLimits) => {
     if (skipValidation) {
         return {
-            payload: merged,
-            sizeBytes: estimateRecordSizeBytes(entryKey, merged),
+            payload,
+            sizeBytes: estimateRecordSizeBytes(entryKey, payload),
         };
     }
-    const validationResult = validateAndNormalizePayload(merged);
+    const validationResult = validateAndNormalizePayload(payload, payloadLimits);
     const keyBytes = estimateKeySizeBytes(entryKey);
     return {
         payload: validationResult.payload,
@@ -31,7 +30,8 @@ export const updateRecordById = (options) => {
     }
     const targetRecord = entry.value;
     const oldSize = targetRecord.sizeBytes;
-    const mergedResult = buildMergedPayload(targetRecord, options.patch, entry.key, options.skipPayloadValidation);
+    const merged = { ...targetRecord.payload, ...options.patch };
+    const mergedResult = validateAndEstimateSize(merged, entry.key, options.skipPayloadValidation, options.payloadLimits);
     const mergedPayload = mergedResult.payload;
     const newSize = mergedResult.sizeBytes;
     const encodedDelta = newSize - oldSize;
@@ -56,6 +56,36 @@ export const updateRecordById = (options) => {
         durabilitySignalBytes: Math.abs(encodedDelta),
     };
 };
+export const replaceRecordById = (options) => {
+    const entry = options.keyIndex.peekById(options.id);
+    if (entry === null) {
+        return { replaced: false, currentSizeBytes: options.currentSizeBytes, durabilitySignalBytes: 0 };
+    }
+    const oldSize = entry.value.sizeBytes;
+    const replacementResult = validateAndEstimateSize(options.payload, entry.key, options.skipPayloadValidation, options.payloadLimits);
+    const newSize = replacementResult.sizeBytes;
+    const encodedDelta = newSize - oldSize;
+    if (options.capacityState !== null &&
+        encodedDelta > 0 &&
+        options.currentSizeBytes + encodedDelta > options.capacityState.maxSizeBytes) {
+        throw new QuotaExceededError('replaceById exceeds configured capacity.maxSize boundary.');
+    }
+    const replacedRecord = {
+        payload: replacementResult.payload,
+        sizeBytes: newSize,
+    };
+    if (options.keyIndex.updateById(options.id, replacedRecord) === null) {
+        throw new IndexCorruptionError('Record index state is inconsistent during replaceById.');
+    }
+    // Underflow is not possible: encodedDelta = newSize - oldSize, and oldSize was
+    // accumulated into currentSizeBytes on insertion. Math.max is purely defensive
+    // against any future estimation inconsistency.
+    return {
+        replaced: true,
+        currentSizeBytes: Math.max(0, options.currentSizeBytes + encodedDelta),
+        durabilitySignalBytes: Math.abs(encodedDelta),
+    };
+};
 export const deleteRecordById = (options) => {
     const removedFromIndex = options.keyIndex.removeById(options.id);
     if (removedFromIndex === null) {
@@ -75,3 +105,26 @@ export const deleteRecordById = (options) => {
         durabilitySignalBytes: freedBytes,
     };
 };
+export const deleteRecordByIds = (options) => {
+    let deletedCount = 0;
+    let totalFreedBytes = 0;
+    let currentSizeBytes = options.currentSizeBytes;
+    for (const id of options.ids) {
+        const removedFromIndex = options.keyIndex.removeById(id);
+        if (removedFromIndex === null) {
+            continue;
+        }
+        const freedBytes = removedFromIndex.value.sizeBytes;
+        totalFreedBytes += freedBytes;
+        // Underflow is not possible: freedBytes was accumulated into currentSizeBytes
+        // on insertion and has not been modified since. Math.max is purely defensive
+        // against any future estimation inconsistency.
+        currentSizeBytes = Math.max(0, currentSizeBytes - freedBytes);
+        deletedCount += 1;
+    }
+    return {
+        deletedCount,
+        currentSizeBytes,
+        durabilitySignalBytes: totalFreedBytes,
+    };
+};

package/dist/types.d.ts

@@ -42,12 +42,21 @@ export interface AutoCommitConfig {
     frequency?: AutoCommitFrequencyInput;
     maxPendingBytes?: number;
 }
+export interface PayloadLimitsConfig {
+    maxDepth?: number;
+    maxKeyBytes?: number;
+    maxStringBytes?: number;
+    maxKeysPerObject?: number;
+    maxTotalKeys?: number;
+    maxTotalBytes?: number;
+}
 export interface DatastoreCommonConfig {
     key?: DatastoreKeyDefinition<unknown, unknown>;
     capacity?: CapacityConfig;
     autoCommit?: AutoCommitConfig;
     duplicateKeys?: DuplicateKeyPolicy;
     skipPayloadValidation?: boolean;
+    payloadLimits?: PayloadLimitsConfig;
 }
 export interface FileTargetByPathConfig {
     kind: 'path';

package/dist/validation/payload.d.ts

@@ -1,7 +1,22 @@
 import type { RecordPayload } from '../types.js';
+export declare const DEFAULT_MAX_PAYLOAD_DEPTH = 64;
+export declare const DEFAULT_MAX_PAYLOAD_KEY_BYTES = 1024;
+export declare const DEFAULT_MAX_PAYLOAD_STRING_BYTES = 65535;
+export declare const DEFAULT_MAX_PAYLOAD_KEYS_PER_OBJECT = 256;
+export declare const DEFAULT_MAX_PAYLOAD_KEYS_TOTAL = 4096;
+export declare const DEFAULT_MAX_PAYLOAD_TOTAL_BYTES = 1048576;
+export interface ResolvedPayloadLimits {
+    maxDepth: number;
+    maxKeyBytes: number;
+    maxStringBytes: number;
+    maxKeysPerObject: number;
+    maxTotalKeys: number;
+    maxTotalBytes: number;
+}
+export declare const DEFAULT_PAYLOAD_LIMITS: Readonly<ResolvedPayloadLimits>;
 export interface PayloadValidationResult {
     payload: RecordPayload;
     sizeBytes: number;
 }
 export declare const deepFreezePayload: (payload: RecordPayload) => RecordPayload;
-export declare const validateAndNormalizePayload: (payload: unknown) => PayloadValidationResult;
+export declare const validateAndNormalizePayload: (payload: unknown, limits?: ResolvedPayloadLimits) => PayloadValidationResult;

package/dist/validation/payload.js

@@ -1,11 +1,19 @@
 import { ValidationError } from '../errors/index.js';
 import { computeUtf8ByteLength, estimateJsonStringBytes } from '../storage/backend/encoding.js';
-const MAX_PAYLOAD_DEPTH = 64;
-const MAX_PAYLOAD_KEY_BYTES = 1024;
-const MAX_PAYLOAD_STRING_BYTES = 65535;
-const MAX_PAYLOAD_KEYS_PER_OBJECT = 256;
-const MAX_PAYLOAD_KEYS_TOTAL = 4096;
-const MAX_PAYLOAD_TOTAL_BYTES = 1048576;
+export const DEFAULT_MAX_PAYLOAD_DEPTH = 64;
+export const DEFAULT_MAX_PAYLOAD_KEY_BYTES = 1024;
+export const DEFAULT_MAX_PAYLOAD_STRING_BYTES = 65535;
+export const DEFAULT_MAX_PAYLOAD_KEYS_PER_OBJECT = 256;
+export const DEFAULT_MAX_PAYLOAD_KEYS_TOTAL = 4096;
+export const DEFAULT_MAX_PAYLOAD_TOTAL_BYTES = 1048576;
+export const DEFAULT_PAYLOAD_LIMITS = {
+    maxDepth: DEFAULT_MAX_PAYLOAD_DEPTH,
+    maxKeyBytes: DEFAULT_MAX_PAYLOAD_KEY_BYTES,
+    maxStringBytes: DEFAULT_MAX_PAYLOAD_STRING_BYTES,
+    maxKeysPerObject: DEFAULT_MAX_PAYLOAD_KEYS_PER_OBJECT,
+    maxTotalKeys: DEFAULT_MAX_PAYLOAD_KEYS_TOTAL,
+    maxTotalBytes: DEFAULT_MAX_PAYLOAD_TOTAL_BYTES,
+};
 // JSON-aware byte estimates for non-string primitives.
 const NULL_ESTIMATION_BYTES = 4; // "null"  = 4 bytes
 // JSON structural overhead constants for size estimation.
@@ -26,8 +34,8 @@ const isPlainObject = (value) => {
 };
 const addValidationBytes = (state, bytes) => {
     state.totalValidationBytes += bytes;
-    if (state.totalValidationBytes > MAX_PAYLOAD_TOTAL_BYTES) {
-        throw new ValidationError(`Payload aggregate validation bytes must be <= ${MAX_PAYLOAD_TOTAL_BYTES}.`);
+    if (state.totalValidationBytes > state.limits.maxTotalBytes) {
+        throw new ValidationError(`Payload aggregate validation bytes must be <= ${state.limits.maxTotalBytes}.`);
     }
 };
 const validatePayloadKey = (key, state) => {
@@ -38,12 +46,12 @@ const validatePayloadKey = (key, state) => {
         throw new ValidationError(`Payload key "${key}" is reserved and not allowed.`);
     }
     const keyBytes = computeUtf8ByteLength(key);
-    if (keyBytes > MAX_PAYLOAD_KEY_BYTES) {
-        throw new ValidationError(`Payload key UTF-8 byte length must be <= ${MAX_PAYLOAD_KEY_BYTES}.`);
+    if (keyBytes > state.limits.maxKeyBytes) {
+        throw new ValidationError(`Payload key UTF-8 byte length must be <= ${state.limits.maxKeyBytes}.`);
     }
     state.totalKeyCount += 1;
-    if (state.totalKeyCount > MAX_PAYLOAD_KEYS_TOTAL) {
-        throw new ValidationError(`Payload total key count must be <= ${MAX_PAYLOAD_KEYS_TOTAL}.`);
+    if (state.totalKeyCount > state.limits.maxTotalKeys) {
+        throw new ValidationError(`Payload total key count must be <= ${state.limits.maxTotalKeys}.`);
     }
     // Add key as JSON string (with escaping + quotes) plus colon.
     addValidationBytes(state, estimateJsonStringBytes(key) + JSON_KEY_COLON_OVERHEAD);
@@ -64,8 +72,8 @@ const validateAndCloneValue = (value, depth, state) => {
     }
     if (typeof value === 'string') {
         const stringBytes = computeUtf8ByteLength(value);
-        if (stringBytes > MAX_PAYLOAD_STRING_BYTES) {
-            throw new ValidationError(`Payload string UTF-8 byte length must be <= ${MAX_PAYLOAD_STRING_BYTES}.`);
+        if (stringBytes > state.limits.maxStringBytes) {
+            throw new ValidationError(`Payload string UTF-8 byte length must be <= ${state.limits.maxStringBytes}.`);
         }
         addValidationBytes(state, estimateJsonStringBytes(value));
         return value;
@@ -97,15 +105,15 @@ const validateAndCloneValue = (value, depth, state) => {
 };
 const validateAndClonePayloadObject = (payloadObject, depth, state) => {
     const objectLevel = depth + 1;
-    if (objectLevel > MAX_PAYLOAD_DEPTH) {
-        throw new ValidationError(`Payload nesting depth must be <= ${MAX_PAYLOAD_DEPTH}.`);
+    if (objectLevel > state.limits.maxDepth) {
+        throw new ValidationError(`Payload nesting depth must be <= ${state.limits.maxDepth}.`);
     }
     if (state.activePath.has(payloadObject)) {
         throw new ValidationError('Circular payload references are not supported.');
     }
     const entries = Object.entries(payloadObject);
-    if (entries.length > MAX_PAYLOAD_KEYS_PER_OBJECT) {
-        throw new ValidationError(`Payload object key count must be <= ${MAX_PAYLOAD_KEYS_PER_OBJECT}.`);
+    if (entries.length > state.limits.maxKeysPerObject) {
+        throw new ValidationError(`Payload object key count must be <= ${state.limits.maxKeysPerObject}.`);
     }
     state.activePath.add(payloadObject);
     // JSON structural overhead: 2 bytes for braces + (N-1) bytes for comma separators.
@@ -120,7 +128,7 @@ const validateAndClonePayloadObject = (payloadObject, depth, state) => {
     state.activePath.delete(payloadObject);
     return copied;
 };
-export const validateAndNormalizePayload = (payload) => {
+export const validateAndNormalizePayload = (payload, limits = DEFAULT_PAYLOAD_LIMITS) => {
     if (!isPlainObject(payload)) {
         throw new ValidationError('payload must be a non-null plain object.');
     }
@@ -128,6 +136,7 @@ export const validateAndNormalizePayload = (payload) => {
         activePath: new WeakSet(),
         totalKeyCount: 0,
         totalValidationBytes: 0,
+        limits,
     };
     const cloned = validateAndClonePayloadObject(payload, 0, state);
     const sizeBytes = state.totalValidationBytes + JSON_ROOT_WRAPPER_OVERHEAD;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frostpillar/frostpillar-storage-engine",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Chunk-based storage engine for browsers and Node.js that packs many small key-value entries into a single backing store.",
   "type": "module",
   "main": "./dist/index.js",