chore: change Serializer$ API

- only object configuration
- use function for allowing scope injection
- fix force()

Author: wmertens

packages/docs/src/routes/api/qwik/api.json

@@ -2242,8 +2242,8 @@
         }
       ],
       "kind": "Variable",
-      "content": "Creates a signal which holds a custom serializable value. It requires that the value implements the `CustomSerializable` type, which means having a function under the `[SerializeSymbol]` property that returns a serializable value when called.\n\nThe `fn` you pass is called with the result of the serialization (in the browser, only when the value is needed), or `undefined` when not yet initialized. If you refer to other signals, `fn` will be called when those change just like computed signals, and then the argument will be the previous output, not the serialized result.\n\nThis is useful when using third party libraries that use custom objects that are not serializable.\n\nNote that the `fn` is called lazily, so it won't impact container resume.\n\n\n```typescript\nuseSerializer$: typeof createSerializer$\n```\n\n\n\n```tsx\nclass MyCustomSerializable {\n  constructor(public n: number) {}\n  inc() {\n    this.n++;\n  }\n}\nconst Cmp = component$(() => {\n  const custom = useSerializer$({\n    deserialize: (data) => new MyCustomSerializable(data),\n    serialize: (data) => data.n,\n    initial: 2,\n  });\n  return <div onClick$={() => custom.value.inc()}>{custom.value.n}</div>;\n});\n```\n\n\nWhen using a Signal as the data to create the object, you may not need `serialize`<!-- -->. Furthermore, when the signal is updated, the serializer will be updated as well, and the current object will be passed as the second argument.\n\n```tsx\nconst Cmp = component$(() => {\n  const n = useSignal(2);\n  const custom = useSerializer$((_data, current) => {\n    if (current) {\n      current.n = n.value;\n      return current;\n    }\n    return new MyCustomSerializable(n.value);\n});\n  return <div onClick$={() => n.value++}>{custom.value.n}</div>;\n});\n```\n(note that in this example, the `{custom.value.n}` is not reactive, so the div text will not update)",
-      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-serialized.ts",
+      "content": "Creates a signal which holds a custom serializable value. It requires that the value implements the `CustomSerializable` type, which means having a function under the `[SerializeSymbol]` property that returns a serializable value when called.\n\nThe `fn` you pass is called with the result of the serialization (in the browser, only when the value is needed), or `undefined` when not yet initialized. If you refer to other signals, `fn` will be called when those change just like computed signals, and then the argument will be the previous output, not the serialized result.\n\nThis is useful when using third party libraries that use custom objects that are not serializable.\n\nNote that the `fn` is called lazily, so it won't impact container resume.\n\n\n```typescript\nuseSerializer$: typeof createSerializer$\n```\n\n\n\n```tsx\nclass MyCustomSerializable {\n  constructor(public n: number) {}\n  inc() {\n    this.n++;\n  }\n}\nconst Cmp = component$(() => {\n  const custom = useSerializer$({\n    deserialize: (data) => new MyCustomSerializable(data),\n    serialize: (data) => data.n,\n    initial: 2,\n  });\n  return <div onClick$={() => custom.value.inc()}>{custom.value.n}</div>;\n});\n```\n\n\nWhen using a Signal as the data to create the object, you need to pass the configuration as a function, and you can then also provide the `update` function to update the object when the signal changes.\n\nBy returning an object from `update`<!-- -->, you signal that the listeners have to be notified. You can mutate the current object but you should return it so that it will trigger listeners.\n\n```tsx\nconst Cmp = component$(() => {\n  const n = useSignal(2);\n  const custom = useSerializer$(() =>\n    ({\n      deserialize: () => new MyCustomSerializable(n.value),\n      update: (current) => {\n        current.n = n.value;\n        return current;\n      }\n    })\n  );\n  return <div onClick$={() => n.value++}>{custom.value.n}</div>;\n});\n```",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-serializer.ts",
       "mdFile": "core.useserializer_.md"
     },
     {

packages/docs/src/routes/api/qwik/index.md

@@ -8936,25 +8936,25 @@ const Cmp = component$(() => {
 });
 ```
 
-When using a Signal as the data to create the object, you may not need `serialize`. Furthermore, when the signal is updated, the serializer will be updated as well, and the current object will be passed as the second argument.
+When using a Signal as the data to create the object, you need to pass the configuration as a function, and you can then also provide the `update` function to update the object when the signal changes.
+
+By returning an object from `update`, you signal that the listeners have to be notified. You can mutate the current object but you should return it so that it will trigger listeners.
 
 ```tsx
 const Cmp = component$(() => {
   const n = useSignal(2);
-  const custom = useSerializer$((_data, current) => {
-    if (current) {
+  const custom = useSerializer$(() => ({
+    deserialize: () => new MyCustomSerializable(n.value),
+    update: (current) => {
       current.n = n.value;
       return current;
-    }
-    return new MyCustomSerializable(n.value);
-  });
+    },
+  }));
   return <div onClick$={() => n.value++}>{custom.value.n}</div>;
 });
 ```
 
-(note that in this example, the `{custom.value.n}` is not reactive, so the div text will not update)
-
-[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-serialized.ts)
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-serializer.ts)
 
 ## useServerData
 

packages/qwik/src/core/index.ts

@@ -111,7 +111,7 @@ export type { ContextId } from './use/use-context';
 export type { UseStoreOptions } from './use/use-store.public';
 export type { ComputedFn } from './use/use-computed';
 export { useComputedQrl } from './use/use-computed';
-export { useSerializerQrl, useSerializer$ } from './use/use-serialized';
+export { useSerializerQrl, useSerializer$ } from './use/use-serializer';
 export type { OnVisibleTaskOptions, VisibleTaskStrategy } from './use/use-visible-task';
 export { useVisibleTaskQrl } from './use/use-visible-task';
 export type { TaskCtx, TaskFn, Tracker } from './use/use-task';

packages/qwik/src/core/shared/shared-serialization.ts

@@ -847,26 +847,25 @@ export const createSerializationContext = (
         });
       } else if (obj instanceof Signal) {
         /**
-         * WrappedSignal might not be calculated yet so we need to use `untrackedValue` to get the
-         * value. ComputedSignal can be left uncalculated.
+         * ComputedSignal can be left uncalculated if invalid.
+         *
+         * SerializerSignal is always serialized if it was already calculated.
          */
-        const v =
-          obj instanceof WrappedSignal
-            ? obj.untrackedValue
-            : obj instanceof ComputedSignal &&
-                !(obj instanceof SerializerSignal) &&
-                (obj.$invalid$ || fastSkipSerialize(obj))
-              ? NEEDS_COMPUTATION
-              : obj.$untrackedValue$;
-        if (v !== NEEDS_COMPUTATION) {
+        const toSerialize =
+          obj instanceof ComputedSignal &&
+          !(obj instanceof SerializerSignal) &&
+          (obj.$invalid$ || fastSkipSerialize(obj))
+            ? NEEDS_COMPUTATION
+            : obj.$untrackedValue$;
+        if (toSerialize !== NEEDS_COMPUTATION) {
           if (obj instanceof SerializerSignal) {
             promises.push(
               (obj.$computeQrl$ as any as QRLInternal<SerializerArg<any, any>>)
                 .resolve()
                 .then((arg) => {
                   let data;
                   if ((arg as any).serialize) {
-                    data = (arg as any).serialize(v);
+                    data = (arg as any).serialize(toSerialize);
                   }
                   if (data === undefined) {
                     data = NEEDS_COMPUTATION;
@@ -876,7 +875,7 @@ export const createSerializationContext = (
                 })
             );
           } else {
-            discoveredValues.push(v);
+            discoveredValues.push(toSerialize);
           }
         }
         if (obj.$effects$) {

packages/qwik/src/core/signal/signal.public.ts

@@ -49,7 +49,10 @@ export interface ComputedSignal<T> extends ReadonlySignal<T> {
  *
  * @public
  */
-export interface SerializerSignal<T> extends ComputedSignal<T> {}
+export interface SerializerSignal<T> extends ComputedSignal<T> {
+  /** Fake property to make the serialization linter happy */
+  __noSerialize__: true;
+}
 
 /**
  * Creates a Signal with the given value. If no value is given, the signal is created with
@@ -88,7 +91,6 @@ export { createComputedQrl };
  * @public
  */
 export const createSerializer$: <T, S>(
-  // We want to also add T as a possible parameter type, but that breaks type inference
   arg: SerializerArg<T, S>
 ) => T extends Promise<any> ? never : SerializerSignal<T> = implicit$FirstArg(
   createSerializerQrl as any

packages/qwik/src/core/signal/signal.ts

@@ -430,8 +430,6 @@ export class ComputedSignal<T> extends Signal<T> {
   $invalidate$() {
     this.$invalid$ = true;
     this.$forceRunEffects$ = false;
-    // We should only call subscribers if the calculation actually changed.
-    // Therefore, we need to calculate the value now.
     this.$container$?.$scheduler$(ChoreType.RECOMPUTE_AND_SCHEDULE_EFFECTS, null, this);
   }
 
@@ -440,10 +438,8 @@ export class ComputedSignal<T> extends Signal<T> {
    * remained the same object
    */
   force() {
-    this.$invalid$ = true;
-    // TODO shouldn't force be set to true, invalid left alone and the effects scheduled?
-    this.$forceRunEffects$ = false;
-    triggerEffects(this.$container$, this, this.$effects$);
+    this.$forceRunEffects$ = true;
+    this.$container$?.$scheduler$(ChoreType.RECOMPUTE_AND_SCHEDULE_EFFECTS, null, this);
   }
 
   get untrackedValue() {
@@ -536,7 +532,7 @@ export class WrappedSignal<T> extends Signal<T> implements Subscriber {
 
   /**
    * Use this to force running subscribers, for example when the calculated value has mutated but
-   * remained the same object
+   * remained the same object.
    */
   force() {
     this.$invalid$ = true;
@@ -579,39 +575,51 @@ export class WrappedSignal<T> extends Signal<T> implements Subscriber {
   }
 }
 
+/** @public */
+export type SerializerArgObject<T, S> = {
+  /**
+   * This will be called with initial or serialized data to reconstruct an object. If no
+   * `initialData` is provided, it will be called with `undefined`.
+   *
+   * This must not return a Promise.
+   */
+  deserialize: (data: Awaited<S>) => T;
+  /** The initial value to use when deserializing. */
+  initial?: S | undefined;
+  /**
+   * This will be called with the object to get the serialized data. You can return a Promise if you
+   * need to do async work.
+   *
+   * The result may be anything that Qwik can serialize.
+   *
+   * If you do not provide it, the object will be serialized as `undefined`. However, if the object
+   * has a `[SerializerSymbol]` property, that will be used as the serializer instead.
+   */
+  serialize?: (obj: T) => S;
+};
+
 /**
  * Serialize and deserialize custom objects.
  *
- * If you pass a function, it will be used as the `deserialize` function.
+ * If you need to use scoped state, you can pass a function instead of an object. The function will
+ * be called with the current value, and you can return a new value.
  *
  * @public
  */
 export type SerializerArg<T, S> =
-  | {
-      /**
-       * This function will be called with serialized data to reconstruct an object.
-       *
-       * If it is created for the first time, it will get the `initial` data or `undefined`.
-       *
-       * If it uses signals or stores, it will be called when these change, and then the second
-       * argument will be the previously constructed object.
-       *
-       * This function must not return a promise.
-       */
-      deserialize: (data: S | undefined, previous: T | undefined) => T;
+  | SerializerArgObject<T, S>
+  | (() => SerializerArgObject<T, S> & {
       /**
-       * This function will be called with the custom object to get the serialized data. You can
-       * return a promise if you need to do async work.
+       * This gets called when reactive state used during `deserialize` changes. You may mutate the
+       * current object, or return a new object.
        *
-       * The result may be anything that Qwik can serialize.
+       * If it returns a value, that will be used as the new value, and listeners will be triggered.
+       * If no change happened, don't return anything.
        *
-       * If you do not provide it, the object will be serialized as `undefined`.
+       * If you mutate the current object, you must return it so that it will trigger listeners.
        */
-      serialize?: (customObject: T) => S | Promise<S>;
-      /** The initial value to use when deserializing. */
-      initial?: S;
-    }
-  | ((data: S | undefined, previous: T | undefined) => T);
+      update?: (current: T) => T | void;
+    });
 
 /**
  * A signal which provides a non-serializable value. It works like a computed signal, but it is
@@ -630,30 +638,31 @@ export class SerializerSignal<T, S> extends ComputedSignal<T> {
       return false;
     }
     throwIfQRLNotResolved(this.$computeQrl$);
-    const arg = (this.$computeQrl$ as any as QRLInternal<SerializerArg<T, S>>).resolved!;
-    let deserialize, initial;
+    let arg = (this.$computeQrl$ as any as QRLInternal<SerializerArg<T, S>>).resolved!;
     if (typeof arg === 'function') {
-      deserialize = arg;
-    } else {
-      deserialize = arg.deserialize;
-      initial = arg.initial;
+      arg = arg();
     }
+    const { deserialize, initial } = arg;
+    const update = (arg as any).update as ((current: T) => T) | undefined;
     const currentValue =
       this.$untrackedValue$ === NEEDS_COMPUTATION ? initial : this.$untrackedValue$;
     const untrackedValue = trackSignal(
       () =>
         this.$didInitialize$
-          ? deserialize(undefined, currentValue as T)
-          : deserialize(currentValue as S, undefined),
+          ? update?.(currentValue as T)
+          : deserialize(currentValue as Awaited<S>),
       this,
       EffectProperty.VNODE,
       this.$container$!
     );
     DEBUG && log('SerializerSignal.$compute$', untrackedValue);
+    const didChange =
+      (this.$didInitialize$ && untrackedValue !== 'undefined') ||
+      untrackedValue !== this.$untrackedValue$;
     this.$invalid$ = false;
-    const didChange = untrackedValue !== this.$untrackedValue$;
+    this.$didInitialize$ = true;
     if (didChange) {
-      this.$untrackedValue$ = untrackedValue;
+      this.$untrackedValue$ = untrackedValue as T;
     }
     return didChange;
   }

packages/qwik/src/core/signal/signal.unit.tsx

@@ -1,4 +1,4 @@
-import { $, type ValueOrPromise } from '@qwik.dev/core';
+import { $, isBrowser, type ValueOrPromise } from '@qwik.dev/core';
 import { createDocument, getTestPlatform } from '@qwik.dev/core/testing';
 import { afterEach, beforeEach, describe, expect, expectTypeOf, it } from 'vitest';
 import { getDomContainer } from '../client/dom-container';
@@ -28,7 +28,12 @@ import {
   type Signal,
 } from './signal.public';
 
-class Foo {}
+class Foo {
+  constructor(public val: number = 0) {}
+  update(val: number) {
+    this.val = val;
+  }
+}
 
 describe('signal types', () => {
   it('Signal<T>', () => () => {
@@ -41,7 +46,7 @@ describe('signal types', () => {
     const signal2 = createComputed$<number>(() => 1);
     expectTypeOf(signal2).toEqualTypeOf<ComputedSignal<number>>();
   });
-  it('SerializerSignal<T>', () => () => {
+  it('SerializerSignal<T, S>', () => () => {
     {
       const signal = createSerializer$({
         deserialize: () => new Foo(),
@@ -54,15 +59,25 @@ describe('signal types', () => {
       expectTypeOf(signal.value).toEqualTypeOf<Foo>();
     }
     {
-      const signal = createSerializer$(() => new Foo());
-      expectTypeOf(signal).toEqualTypeOf<SerializerSignal<Foo>>();
-      expectTypeOf(signal.value).toEqualTypeOf<Foo>();
+      const stuff = createSignal(1);
+      const signal = createSerializer$(() => ({
+        deserialize: () => (isBrowser ? new Foo(stuff.value) : undefined),
+        update: (foo) => {
+          if (foo!.val !== stuff.value) {
+            return;
+          }
+          foo!.update(stuff.value);
+          return foo;
+        },
+      }));
+      expectTypeOf(signal).toEqualTypeOf<SerializerSignal<undefined> | SerializerSignal<Foo>>();
+      expectTypeOf(signal.value).toEqualTypeOf<Foo | undefined>();
     }
     {
-      const signal = createSerializer$<Foo, number>({
-        deserialize: (data, prev) => {
+      const signal = createSerializer$({
+        // We have to specify the type here, sadly
+        deserialize: (data?: number) => {
           expectTypeOf(data).toEqualTypeOf<number | undefined>();
-          expectTypeOf(prev).toEqualTypeOf<Foo | undefined>();
           return new Foo();
         },
         serialize: (obj) => {
@@ -75,13 +90,12 @@ describe('signal types', () => {
     }
     {
       const signal = createSerializer$({
-        deserialize: (data, prev) => {
-          expectTypeOf(data).toEqualTypeOf<number | undefined>();
-          expectTypeOf(prev).toEqualTypeOf<Foo | undefined>();
+        deserialize: (data) => {
+          expectTypeOf(data).toEqualTypeOf<number>();
           return new Foo();
         },
-        // you only have to specify the type on the serialize function
-        serialize: (obj: Foo) => {
+        initial: 3,
+        serialize: (obj) => {
           expect(obj).toBeInstanceOf(Foo);
           return 1;
         },