fix: DataStoreData allow interfaces without index signature

Author: Sv443

.changeset/wide-seals-worry.md

@@ -0,0 +1,5 @@
+---
+"@sv443-network/coreutils": patch
+---
+
+Made the type `DataStoreData` much less constrained. This way it won't require an index signature anymore.

docs.md

@@ -854,13 +854,12 @@ The old data is a copy of the cached object, so you can mutate it directly, use
 
 ### `type DataStoreData`
 ```ts
-type DataStoreData<TData extends SerializableVal = SerializableVal> = Record<string, SerializableVal | TData>;
+type DataStoreData = object;
 ```
 
 A type that represents the data stored in a DataStore instance.  
-It is a record of string keys to values that can be serialized to JSON via `JSON.stringify()`.  
-This means that the values can be primitive types (string, number, boolean, null), arrays or objects that only contain serializable values.  
-Refer to the [`SerializableVal` type](#type-serializableval) for more information.
+It uses `object` instead of an index signature so that interfaces without an explicit index signature can also be used as `TData`.  
+Make sure to only use JSON-serializable types here, otherwise unexpected behavior may occur.
 
 <br><br>
 

lib/DataStore.ts

@@ -50,7 +50,7 @@ export type DataStoreOptions<TData extends DataStoreData> = Prettify<
      *   
      * - ⚠️ Don't reuse the same engine instance for multiple DataStores, unless it explicitly supports it!
      */
-    engine: (() => DataStoreEngine<TData>) | DataStoreEngine<TData>;
+    engine: (() => DataStoreEngine) | DataStoreEngine;
     /**
      * A dictionary of functions that can be used to migrate data from older versions to newer ones.  
      * The keys of the dictionary should be the format version that the functions can migrate to, from the previous whole integer value.  
@@ -111,8 +111,12 @@ export type DataStoreOptions<TData extends DataStoreData> = Prettify<
   )
 >;
 
-/** Generic type that represents the serializable data structure saved in a {@linkcode DataStore} instance. */
-export type DataStoreData<TData extends SerializableVal = SerializableVal> = Record<string, SerializableVal | TData>;
+/**
+ * Generic type that represents the serializable data structure saved in a {@linkcode DataStore} instance.  
+ * - ⚠️ Uses `object` instead of an index signature so that interfaces without an explicit index signature can be used as `TData`.  
+ *   Make sure to only use JSON-serializable types here, otherwise unexpected behavior may occur!
+ */
+export type DataStoreData = object;
 
 //#region class
 
@@ -141,7 +145,7 @@ export class DataStore<TData extends DataStoreData> {
   public readonly decodeData: DataStoreOptions<TData>["decodeData"];
   public readonly compressionFormat: Exclude<DataStoreOptions<TData>["compressionFormat"], undefined> = "deflate-raw";
   public readonly memoryCache: boolean = true;
-  public readonly engine: DataStoreEngine<TData>;
+  public readonly engine: DataStoreEngine;
   public options: DataStoreOptions<TData>;
 
   /**
@@ -284,7 +288,7 @@ export class DataStore<TData extends DataStoreData> {
       }
 
       // deserialize the data if needed
-      let parsed = await this.engine.deserializeData(storedData, isEncoded);
+      let parsed = await this.engine.deserializeData(storedData, isEncoded) as TData;
 
       // run migrations if needed
       if(storedFmtVer < this.formatVersion && this.migrations)
@@ -444,7 +448,7 @@ export class DataStore<TData extends DataStoreData> {
       if(data === undefined || isNaN(fmtVer))
         return;
 
-      const parsed = await this.engine.deserializeData(data, isEncoded);
+      const parsed = await this.engine.deserializeData(data, isEncoded) as TData;
       await Promise.allSettled([
         this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(parsed)),
         this.engine.setValue(`__ds-${this.id}-ver`, fmtVer),

lib/DataStoreEngine.ts

@@ -11,9 +11,9 @@ import type { Prettify, SerializableVal } from "./types.ts";
 //#region >> DataStoreEngine
 
 /** Contains the only properties of {@linkcode DataStoreOptions} that are relevant to the {@linkcode DataStoreEngine} class. */
-export type DataStoreEngineDSOptions<TData extends DataStoreData> = Prettify<Pick<DataStoreOptions<TData>, "decodeData" | "encodeData" | "id">>;
+export type DataStoreEngineDSOptions<TData extends DataStoreData = DataStoreData> = Prettify<Pick<DataStoreOptions<TData>, "decodeData" | "encodeData" | "id">>;
 
-export interface DataStoreEngine<TData extends DataStoreData> { // eslint-disable-line @typescript-eslint/no-unused-vars
+export interface DataStoreEngine<TData extends DataStoreData = DataStoreData> { // eslint-disable-line @typescript-eslint/no-unused-vars
   /** Deletes all data in persistent storage, including the data container itself (e.g. a file or a database) */
   deleteStorage?(): Promise<void>;
 }
@@ -22,7 +22,7 @@ export interface DataStoreEngine<TData extends DataStoreData> { // eslint-disabl
  * Base class for creating {@linkcode DataStore} storage engines.  
  * This acts as an interchangeable API for writing and reading persistent JSON-serializable data in various environments.
  */
-export abstract class DataStoreEngine<TData extends DataStoreData> {
+export abstract class DataStoreEngine<TData extends DataStoreData = DataStoreData> {
   protected dataStoreOptions!: DataStoreEngineDSOptions<TData>; // setDataStoreOptions() is called from inside the DataStore constructor to set this value
 
   constructor(options?: DataStoreEngineDSOptions<TData>) {
@@ -118,7 +118,7 @@ export type BrowserStorageEngineOptions = {
  * - ⚠️ Requires a DOM environment
  * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance
  */
-export class BrowserStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
+export class BrowserStorageEngine<TData extends DataStoreData = DataStoreData> extends DataStoreEngine<TData> {
   protected options: BrowserStorageEngineOptions & Required<Pick<BrowserStorageEngineOptions, "type">>;
 
   /**
@@ -188,7 +188,7 @@ export type FileStorageEngineOptions = {
  * - ⚠️ Requires Node.js or Deno with Node compatibility (v1.31+)  
  * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance
  */
-export class FileStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
+export class FileStorageEngine<TData extends DataStoreData = DataStoreData> extends DataStoreEngine<TData> {
   protected options: FileStorageEngineOptions & Required<Pick<FileStorageEngineOptions, "filePath">>;
   private fileAccessQueue: Promise<void> = Promise.resolve();
 

lib/test/DataStore.spec.ts

@@ -349,4 +349,35 @@ describe("DataStore", () => {
       store.getData();
     }).toThrow();
   });
+
+  it("No type error when using interface without index signature", async () => {
+    interface MyData {
+      a: number;
+      b: number;
+    }
+
+    const defaultData: MyData = { a: 1, b: 2 };
+
+    const store = new DataStore({
+      id: "test-interface-without-index-signature",
+      defaultData,
+      formatVersion: 1,
+      engine: new BrowserStorageEngine({ type: "localStorage" }),
+    });
+
+    await store.loadData();
+
+    expect(store.getData().a).toBe(1);
+    expect(store.getData().b).toBe(2);
+
+    await store.setData({ ...store.getData(), a: 42 });
+
+    await store.loadData();
+
+    expect(store.getData().a).toBe(42);
+    expect(store.getData().b).toBe(2);
+
+    // restore initial state:
+    await store.deleteData();
+  });
 });