Greatly expand the serializable types using superjson

Author: KrisBraun

.changeset/wet-jobs-divide.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: Support for more serializable types, especially Date

twister/src/common/serializable.ts

@@ -0,0 +1,54 @@
+/**
+ * Types supported by SuperJSON serialization.
+ *
+ * SuperJSON extends standard JSON serialization to support additional JavaScript types
+ * while maintaining type safety and preventing common serialization errors.
+ *
+ * Supported types:
+ * - Primitives: string, number, boolean, null, undefined
+ * - Complex types: Date, RegExp, Map, Set, Error, URL, BigInt
+ * - Collections: Arrays and objects (recursively)
+ *
+ * NOT supported (will throw validation errors):
+ * - Functions
+ * - Symbols
+ * - Circular references
+ * - Custom class instances (unless explicitly registered)
+ */
+export type Serializable =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Date
+  | RegExp
+  | Error
+  | URL
+  | bigint
+  | SerializableArray
+  | SerializableObject
+  | SerializableMap
+  | SerializableSet;
+
+/**
+ * Array of serializable values
+ */
+export interface SerializableArray extends Array<Serializable> {}
+
+/**
+ * Object with string keys and serializable values
+ */
+export interface SerializableObject {
+  [key: string]: Serializable;
+}
+
+/**
+ * Map with serializable keys and values
+ */
+export interface SerializableMap extends Map<Serializable, Serializable> {}
+
+/**
+ * Set with serializable values
+ */
+export interface SerializableSet extends Set<Serializable> {}

twister/src/index.ts

@@ -3,4 +3,5 @@ export * from "./plot";
 export * from "./tag";
 export * from "./tool";
 export * from "./tools";
+export * from "./common/serializable";
 export { getBuilderDocumentation } from "./creator-docs";

twister/src/plot.ts

@@ -91,6 +91,11 @@ export type Priority = {
   title: string;
   /** Whether this priority has been archived */
   archived: boolean;
+  /**
+   * Optional key for referencing this priority.
+   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).
+   */
+  key: string | null;
 };
 
 /**

twister/src/tool.ts

@@ -127,44 +127,52 @@ export abstract class Tool<TSelf> implements ITool {
    * @param args - Optional arguments to pass to the callback
    * @returns Promise resolving to the callback result
    */
-  protected async run(token: Callback, args?: any): Promise<any> {
-    return this.tools.callbacks.run(token, args);
+  protected async run(token: Callback, ...args: any[]): Promise<any> {
+    return this.tools.callbacks.run(token, ...args);
   }
 
   /**
    * Retrieves a value from persistent storage by key.
    *
-   * @template T - The expected type of the stored value
+   * Values are automatically deserialized using SuperJSON, which
+   * properly restores Date objects, Maps, Sets, and other complex types.
+   *
+   * @template T - The expected type of the stored value (must be Serializable)
    * @param key - The storage key to retrieve
    * @returns Promise resolving to the stored value or null
    */
-  protected async get<T>(key: string): Promise<T | null> {
+  protected async get<T extends import("./index").Serializable>(key: string): Promise<T | null> {
     return this.tools.store.get(key);
   }
 
   /**
    * Stores a value in persistent storage.
    *
-   * **Important**: Values must be JSON-serializable. Functions and Symbols cannot be stored.
-   *
-   * **Handling undefined values:**
-   * - Object keys with undefined values are automatically removed
-   * - Arrays with undefined elements will throw a validation error
-   * - Use null instead of undefined for array elements
+   * The value will be serialized using SuperJSON and stored persistently.
+   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,
+   * and other complex types that standard JSON doesn't support.
    *
+   * **Important**: Functions and Symbols cannot be stored.
    * **For function references**: Use callbacks instead of storing functions directly.
    *
    * @example
    * ```typescript
-   * // ✅ Object keys with undefined are automatically removed
+   * // ✅ Date objects are preserved
+   * await this.set("sync_state", {
+   *   lastSync: new Date(),
+   *   minDate: new Date(2024, 0, 1)
+   * });
+   *
+   * // ✅ undefined is now supported
    * await this.set("data", { name: "test", optional: undefined });
-   * // Stores: { name: "test" }
    *
-   * // ✅ Arrays: use null for optional values
-   * await this.set("items", [1, null, 3]);
+   * // ✅ Arrays with undefined are supported
+   * await this.set("items", [1, undefined, 3]);
+   * await this.set("items", [1, null, 3]); // Also works
    *
-   * // ❌ Arrays with undefined throw errors
-   * await this.set("items", [1, undefined, 3]); // Error!
+   * // ✅ Maps and Sets are supported
+   * await this.set("mapping", new Map([["key", "value"]]));
+   * await this.set("tags", new Set(["tag1", "tag2"]));
    *
    * // ❌ WRONG: Cannot store functions directly
    * await this.set("handler", this.myHandler);
@@ -178,12 +186,12 @@ export abstract class Tool<TSelf> implements ITool {
    * await this.run(token, args);
    * ```
    *
-   * @template T - The type of value being stored
+   * @template T - The type of value being stored (must be Serializable)
    * @param key - The storage key to use
-   * @param value - The value to store (must be JSON-serializable)
+   * @param value - The value to store (must be SuperJSON-serializable)
    * @returns Promise that resolves when the value is stored
    */
-  protected async set<T>(key: string, value: T): Promise<void> {
+  protected async set<T extends import("./index").Serializable>(key: string, value: T): Promise<void> {
     return this.tools.store.set(key, value);
   }
 

twister/src/tools/store.ts

@@ -1,4 +1,4 @@
-import { ITool } from "..";
+import { ITool, type Serializable } from "..";
 
 /**
  * Built-in tool for persistent key-value storage.
@@ -14,9 +14,20 @@ import { ITool } from "..";
  * **Storage Characteristics:**
  * - Persistent across worker restarts
  * - Isolated per twist/tool instance
- * - Supports any JSON-serializable data
+ * - Supports SuperJSON-serializable data (see below)
  * - Async operations for scalability
  *
+ * **Supported Data Types (via SuperJSON):**
+ * - Primitives: string, number, boolean, null, undefined
+ * - Complex types: Date, RegExp, Map, Set, Error, URL, BigInt
+ * - Collections: Arrays and objects (recursively)
+ *
+ * **NOT Supported (will throw validation errors):**
+ * - Functions (use callback tokens instead - see Callbacks tool)
+ * - Symbols
+ * - Circular references
+ * - Custom class instances
+ *
  * **Use Cases:**
  * - Storing authentication tokens
  * - Caching configuration data
@@ -51,42 +62,56 @@ export abstract class Store extends ITool {
    * Returns the stored value deserialized to the specified type,
    * or null if the key doesn't exist or the value is null.
    *
-   * @template T - The expected type of the stored value
+   * Values are automatically deserialized using SuperJSON, which
+   * properly restores Date objects, Maps, Sets, and other complex types.
+   *
+   * @template T - The expected type of the stored value (must be Serializable)
    * @param key - The storage key to retrieve
    * @returns Promise resolving to the stored value or null
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  abstract get<T>(key: string): Promise<T | null>;
+  abstract get<T extends Serializable>(key: string): Promise<T | null>;
 
   /**
    * Stores a value in persistent storage.
    *
-   * The value will be JSON-serialized and stored persistently.
+   * The value will be serialized using SuperJSON and stored persistently.
    * Any existing value at the same key will be overwritten.
    *
-   * **Handling undefined values:**
-   * - Object keys with undefined values are automatically removed
-   * - Arrays with undefined elements will throw a validation error
-   * - Use null instead of undefined for array elements
+   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,
+   * and other complex types that standard JSON doesn't support.
    *
-   * @template T - The type of value being stored
+   * @template T - The type of value being stored (must be Serializable)
    * @param key - The storage key to use
-   * @param value - The value to store (must be JSON-serializable)
+   * @param value - The value to store (must be SuperJSON-serializable)
    * @returns Promise that resolves when the value is stored
    *
    * @example
    * ```typescript
-   * // Object keys with undefined are removed
-   * await this.set('data', { name: 'test', optional: undefined });
-   * // Stores: { name: 'test' }
+   * // Date objects are preserved
+   * await this.set('sync_state', {
+   *   lastSync: new Date(),
+   *   minDate: new Date(2024, 0, 1)
+   * });
+   *
+   * // undefined is now supported
+   * await this.set('data', { name: 'test', optional: undefined }); // ✅ Works
+   *
+   * // Arrays with undefined are supported
+   * await this.set('items', [1, undefined, 3]); // ✅ Works
+   * await this.set('items', [1, null, 3]); // ✅ Also works
+   *
+   * // Maps and Sets are supported
+   * await this.set('mapping', new Map([['key', 'value']])); // ✅ Works
+   * await this.set('tags', new Set(['tag1', 'tag2'])); // ✅ Works
    *
-   * // Arrays with undefined throw errors - use null instead
-   * await this.set('items', [1, null, 3]); // ✅ Works
-   * await this.set('items', [1, undefined, 3]); // ❌ Throws error
+   * // Functions are NOT supported - use callback tokens instead
+   * const token = await this.callback(this.myFunction);
+   * await this.set('callback_ref', token); // ✅ Use callback token
    * ```
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  abstract set<T>(key: string, value: T): Promise<void>;
+  abstract set<T extends Serializable>(key: string, value: T): Promise<void>;
 
   /**
    * Removes a specific key from storage.

twister/src/twist.ts

@@ -114,24 +114,40 @@ export abstract class Twist<TSelf> {
   /**
    * Retrieves a value from persistent storage by key.
    *
-   * @template T - The expected type of the stored value
+   * Values are automatically deserialized using SuperJSON, which
+   * properly restores Date objects, Maps, Sets, and other complex types.
+   *
+   * @template T - The expected type of the stored value (must be Serializable)
    * @param key - The storage key to retrieve
    * @returns Promise resolving to the stored value or null
    */
-  protected async get<T>(key: string): Promise<T | null> {
+  protected async get<T extends import("./index").Serializable>(
+    key: string
+  ): Promise<T | null> {
     return this.tools.store.get(key);
   }
 
   /**
    * Stores a value in persistent storage.
    *
-   * **Important**: Values must be JSON-serializable. Functions, Symbols, and undefined values
-   * cannot be stored directly.
+   * The value will be serialized using SuperJSON and stored persistently.
+   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,
+   * and other complex types that standard JSON doesn't support.
    *
+   * **Important**: Functions and Symbols cannot be stored.
    * **For function references**: Use callbacks instead of storing functions directly.
    *
    * @example
    * ```typescript
+   * // ✅ Date objects are preserved
+   * await this.set("sync_state", {
+   *   lastSync: new Date(),
+   *   minDate: new Date(2024, 0, 1)
+   * });
+   *
+   * // ✅ undefined is now supported
+   * await this.set("data", { name: "test", optional: undefined });
+   *
    * // ❌ WRONG: Cannot store functions directly
    * await this.set("handler", this.myHandler);
    *
@@ -144,12 +160,15 @@ export abstract class Twist<TSelf> {
    * await this.run(token, args);
    * ```
    *
-   * @template T - The type of value being stored
+   * @template T - The type of value being stored (must be Serializable)
    * @param key - The storage key to use
-   * @param value - The value to store (must be JSON-serializable)
+   * @param value - The value to store (must be SuperJSON-serializable)
    * @returns Promise that resolves when the value is stored
    */
-  protected async set<T>(key: string, value: T): Promise<void> {
+  protected async set<T extends import("./index").Serializable>(
+    key: string,
+    value: T
+  ): Promise<void> {
     return this.tools.store.set(key, value);
   }