Proposal: Customizing createStore in SolidJS with User-Defined Signal and Equality Functions

[mizulu]

Overview

This proposal introduces two approaches for enabling user-defined signal creation and equality checks in createStore:

1. Factory-Based Approach → Simple and modular, with minimal changes to SolidJS. The store logic is scoped within a factory, allowing each factory call to have its own dependencies provided by JavaScript scoping. However, dependency inheritance is not preserved, meaning behavior is determined by the setter function's execution path, which is scoped.

2. Dependency-Attached Approach → Ensures dependencies are inherited across store nodes, preserving behavior even in nested structures. This allows multiple store configurations to coexist, with child nodes inheriting behavior from their parent.

Both solutions aim to give developers finer control over store updates, signal tracking, debugging, and equality checks, while maintaining flexibility in how state updates are handled.

Approach 1: Factory-Based Store Creation (Emphasizing Simplicity & Minimal Changes)

This approach modifies createStore using a factory function, allowing users to inject custom signal behavior and equality logic in a straightforward manner.

Example: Factory-Based Customization

const createStore = factoryCreateStore({
  createSignal: MyOwnCreateSignal, // Allows hooking into signal behavior
  createSignalEquals: customEqLogic,
});

function customEqLogic(a, b): boolean {
  if (a instanceof Date && b instanceof Date) {
    return a.getTime() === b.getTime(); // Compare dates by timestamp
  }
  return a === b;
}

Key Characteristics
✅ Easy to implement—Requires minimal changes to createStore.
✅ Encapsulated behavior—Custom signals and equality functions are scoped within the factory-generated store.
✅ Scoped via JavaScript—Each factory call has its own dependencies provided by JS scoping.
✅ Direct control over updates—Developers can define store-specific signal handling easily.

🚫 No dependency inheritance—Each store defines its own behavior, meaning parent-child store relationships do not inherit configurations.
🚫 Behavior is tied to setter function execution paths, which are scoped—Store updates depend on where the setter is applied, rather than inherited globally.

---

Approach 2: Attaching Dependencies to Store Nodes (Preserving Inheritance & Mixed Configurations)

A more integrated approach involves attaching dependencies directly to store nodes, similar to how $PROXY metadata is handled in SolidJS. This ensures dependency inheritance across nested structures and allows mixed store configurations.

Example: Dependency-Attached Store Configuration

const [store, setStore] = createStore(
  { a: { value: new Date(), more: { value: 321 } } },
  {
    deps: {
      createSignal: MyOwnCreateSignal, // Enables tracking reads/writes
      equals(a, b) {
        if (a instanceof Date && b instanceof Date) {
          return a.getTime() === b.getTime(); // Compare dates by timestamp
        }
        return a === b;
      },
    },
  }
);

Key Characteristics

✅ Dependency inheritance is preserved—Each node inherits configuration from its parent, ensuring consistent behavior across nested structures.
✅ Stores with mixed configurations can coexist—Custom behavior applies selectively based on parent dependency attachment. ✅ Signal hooks allow tracking—Users can monitor read/write operations, aiding debugging and performance optimization.

🚫 Requires deeper integration—Dependencies must propagate correctly across store nodes.
🚫 Behavior is inherited, meaning developers need to track how dependencies flow between store layers.

Proof of Concept

• Approach 1 - is simply taking the store implementation wrap it in the factory function
  and replace dependencies that are passed as arguments to the factory function.

• Approach 2 ( Inherited Dependencies ) with store implementation adaptations
  most of the changes is propagating the dependencies and make them accessible in the path that they are needed.

Playground Link ( Approach 2 )

[mizulu]

inspiration and feedback

1. prior cross discussion https://discord.com/channels/722131463138705510/1370511783705444405

2. The Date use case, as introduced by @hyperknot, highlights that the default store equality is determined by === reference or primitive value. This implies that it is not possible to set a key using a different Date() object with the same time. It was suggested that enabling equality through the .getTime() method could offer a more effective solution.

The custom comparator will allow users to have custom comparators that works with JS Date objects
or any other Object with special equality logic.

3. reconcile: support "merge" in objects #2475 (comment)

[mizulu]

Feedback from Ryan (SolidJS) @ryansolid Specifically Related to the Proposal

Ryan pointed out key technical challenges regarding the proposal to introduce custom equality functions and signal injection into createStore: ( from the discord discussion )

1. Lack of Ownership in Stores & Propagation Issues

• Stores are decentralized: Signals within stores are created lazily and independently, meaning there is no real ownership of store nodes.
• Equality overrides are difficult to propagate: Since stores do not follow a single path, it's unclear how custom equality functions would apply consistently.
• Would likely need a global equality function: Instead of per-node customization, a more feasible solution might be setting a global equality function, such as setGlobalStoreEquals(customEq).

2. Custom Signals Need Special Handling

• Internal store nodes need different treatment: Store signals differ from end-user signals, meaning custom signals would require special logic for tracking and serialization.
• Tracing reads could be inconsistent: If a custom signal is applied inconsistently due to different execution paths, it could lead to unexpected behavior in store updates.
• Needs proper forwarding through all nodes: If implemented, the store would have to ensure custom signals and comparators propagate correctly throughout nested structures.

3. Complexities with Mixed Dependencies in Store Nodes

• Custom dependencies must be accessible at all levels: If dependencies are attached to store nodes, SolidJS must ensure they remain accessible across nested structures.
• Stores with different configurations must coexist: While attaching dependencies at node creation allows different stores to have unique behaviors, the propagation mechanism must be carefully designed to prevent unintended overrides.

Ryan's Overall Perspective on the Proposal

• A global equality setting might be more practical than individual store-level custom comparators.
• The lack of ownership in stores makes propagation difficult, requiring careful design.
• Custom signals introduce additional complexity, especially with serialization and ensuring consistent behavior in SSR setups.

[hyperknot]

Thanks for the proposal and the discussion on Discord.

I have no knowledge about the internals of Solid, but I here is what I can imagine as an ultimate DX.

const dateEquals = (a, b) => {
  return a.getTime() === b.getTime();
};

const [state, setState] = createStore({
  date: new Date(),
  items: [],
  settings: {},
}, {
  comparator: {
    Date: dateEquals,
    array: reconcile,
    object: reconcile
  }
});

I mean just a wild idea, but one can dream! This would be a beautiful DX.

[mizulu]

👍

That is interesting

with this proposal, it will be possible to create your own "API" for create store

and might be possible to extend into update strategy
if I understand correctly what you mean by the

array: reconcile,
object: reconcile

while the main proposal is about dependencies injection
the same mechanism we use to propagate the dependencies
can also be used for configuration, which might allow changing the update strategy based on the object
type. array/object and merge vs reconcile

[hyperknot]

Yes, it'd be like an API for create store!

So my use case is I'm sending/getting a JSON from a Drizzle ORM. The types are exactly the same as on the Solid store.

So when I receive a JSON array, I have to run reconcile manually. Same for an object. For Date I need to do the comparison manually.

Such store would be able to "ingest" data coming from JSON, without any manual wrapper.

Developing a wrapper is also not complicated, but this "API" would be very elegant.