feat(core): use/createSerialized$

Author: wmertens

.changeset/nasty-planes-jam.md

@@ -0,0 +1,8 @@
+---
+'@qwik.dev/core': minor
+---
+
+FEAT: `useSerialized$(fn)` and `createSerialized$(fn)` allow serializing custom objects. You must provide a
+function that converts the custom object to a serializable one via the `[SerializerSymbol]`
+property, and then provide `use|createSerialized$(fn)` with the function that creates the custom object
+from the serialized data. This will lazily create the value when needed.

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

@@ -221,6 +221,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-context.ts",
       "mdFile": "core.createcontextid.md"
     },
+    {
+      "name": "createSerialized$",
+      "id": "createserialized_",
+      "hierarchy": [
+        {
+          "name": "createSerialized$",
+          "id": "createserialized_"
+        }
+      ],
+      "kind": "Function",
+      "content": "Create a signal that holds a custom serializable value. See `useSerialized$` for more details.\n\n\n```typescript\ncreateSerialized$: <T extends CustomSerializable<T, S>, S, F extends ConstructorFn<T, S> = ConstructorFn<T, S>>(qrl: F | QRL<F>) => SerializedSignal<T, S, F>\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nqrl\n\n\n</td><td>\n\nF \\| [QRL](#qrl)<!-- -->&lt;F&gt;\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\nSerializedSignal&lt;T, S, F&gt;",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/signal/signal.public.ts",
+      "mdFile": "core.createserialized_.md"
+    },
     {
       "name": "createSignal",
       "id": "createsignal",
@@ -2031,6 +2045,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-resource-dollar.ts",
       "mdFile": "core.useresource_.md"
     },
+    {
+      "name": "useSerialized$",
+      "id": "useserialized_",
+      "hierarchy": [
+        {
+          "name": "useSerialized$",
+          "id": "useserialized_"
+        }
+      ],
+      "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\nuseSerialized$: {\n    fn: <T extends CustomSerializable<T, S>, S, F extends ConstructorFn<T, S> = ConstructorFn<T, S>>(fn: F | QRL<F>) => T extends Promise<any> ? never : ReadonlySignal<T>;\n}['fn']\n```\n\n\n\n```tsx\nclass MyCustomSerializable {\n  constructor(public n: number) {}\n  inc() {\n    this.n++;\n  }\n  [SerializeSymbol]() {\n    return this.n;\n  }\n}\nconst Cmp = component$(() => {\n  const custom = useSerialized$<MyCustomSerializable, number>(\n    (prev) =>\n      new MyCustomSerializable(prev instanceof MyCustomSerializable ? prev : (prev ?? 3))\n  );\n  return <div onClick$={() => custom.value.inc()}>{custom.value.n}</div>;\n});\n```",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-serializer.ts",
+      "mdFile": "core.useserialized_.md"
+    },
     {
       "name": "useServerData",
       "id": "useserverdata",

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

@@ -723,6 +723,51 @@ The name of the context.
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-context.ts)
 
+## createSerialized$
+
+Create a signal that holds a custom serializable value. See `useSerialized$` for more details.
+
+```typescript
+createSerialized$: <
+  T extends CustomSerializable<T, S>,
+  S,
+  F extends ConstructorFn<T, S> = ConstructorFn<T, S>,
+>(
+  qrl: F | QRL<F>,
+) => SerializedSignal<T, S, F>;
+```
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+qrl
+
+</td><td>
+
+F \| [QRL](#qrl)&lt;F&gt;
+
+</td><td>
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+SerializedSignal&lt;T, S, F&gt;
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/signal/signal.public.ts)
+
 ## createSignal
 
 Creates a Signal with the given value. If no value is given, the signal is created with `undefined`.
@@ -4905,6 +4950,45 @@ _(Optional)_
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-resource-dollar.ts)
 
+## useSerialized$
+
+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.
+
+The `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.
+
+This is useful when using third party libraries that use custom objects that are not serializable.
+
+Note that the `fn` is called lazily, so it won't impact container resume.
+
+```typescript
+useSerialized$: {
+    fn: <T extends CustomSerializable<T, S>, S, F extends ConstructorFn<T, S> = ConstructorFn<T, S>>(fn: F | QRL<F>) => T extends Promise<any> ? never : ReadonlySignal<T>;
+}['fn']
+```
+
+```tsx
+class MyCustomSerializable {
+  constructor(public n: number) {}
+  inc() {
+    this.n++;
+  }
+  [SerializeSymbol]() {
+    return this.n;
+  }
+}
+const Cmp = component$(() => {
+  const custom = useSerialized$<MyCustomSerializable, number>(
+    (prev) =>
+      new MyCustomSerializable(
+        prev instanceof MyCustomSerializable ? prev : (prev ?? 3),
+      ),
+  );
+  return <div onClick$={() => custom.value.inc()}>{custom.value.n}</div>;
+});
+```
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-serializer.ts)
+
 ## useServerData
 
 ```typescript

packages/qwik/public.d.ts

@@ -6,6 +6,7 @@ export {
   ComputedSignal,
   ContextId,
   createComputed$,
+  createSerialized$,
   createContextId,
   createSignal,
   CSSProperties,
@@ -60,6 +61,7 @@ export {
   useOnDocument,
   useOnWindow,
   useResource$,
+  useSerialized$,
   useServerData,
   useSignal,
   useStore,

packages/qwik/src/core/api.md

@@ -119,6 +119,18 @@ export const createComputedQrl: <T>(qrl: QRL<() => T>) => T extends Promise<any>
 // @public
 export const createContextId: <STATE = unknown>(name: string) => ContextId<STATE>;
 
+// Warning: (ae-forgotten-export) The symbol "CustomSerializable" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "ConstructorFn" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "SerializedSignal" needs to be exported by the entry point index.d.ts
+//
+// @public
+export const createSerialized$: <T extends CustomSerializable<T, S>, S, F extends ConstructorFn<T, S> = ConstructorFn<T, S>>(qrl: F | QRL<F>) => SerializedSignal<T, S, F>;
+
+// Warning: (ae-internal-missing-underscore) The name "createSerializedQrl" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal (undocumented)
+export const createSerializedQrl: <T extends CustomSerializable<T, S>, S, F extends ConstructorFn<T, S> = ConstructorFn<T, S>>(qrl: QRL<F>) => SerializedSignal<T, S, F>;
+
 // @public
 export const createSignal: {
     <T>(): Signal<T | undefined>;
@@ -1092,6 +1104,16 @@ export const useResource$: <T>(generatorFn: ResourceFn<T>, opts?: ResourceOption
 // @internal (undocumented)
 export const useResourceQrl: <T>(qrl: QRL<ResourceFn<T>>, opts?: ResourceOptions) => ResourceReturn<T>;
 
+// @public
+export const useSerialized$: {
+    fn: <T extends CustomSerializable<T, S>, S, F extends ConstructorFn<T, S> = ConstructorFn<T, S>>(fn: F | QRL<F>) => T extends Promise<any> ? never : ReadonlySignal<T>;
+}['fn'];
+
+// Warning: (ae-internal-missing-underscore) The name "useSerializedQrl" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal (undocumented)
+export const useSerializedQrl: <T extends CustomSerializable<T, S>, S, F extends ConstructorFn<T, S>>(qrl: QRL<F>) => T extends Promise<any> ? never : ReadonlySignal<T>;
+
 // @public (undocumented)
 export function useServerData<T>(key: string): T | undefined;
 

packages/qwik/src/core/index.ts

@@ -110,6 +110,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 { useSerializedQrl, useSerialized$ } from './use/use-serialized';
 export type { OnVisibleTaskOptions, VisibleTaskStrategy } from './use/use-visible-task';
 export { useVisibleTaskQrl } from './use/use-visible-task';
 export type { EagernessOptions, TaskCtx, TaskFn, Tracker, UseTaskOptions } from './use/use-task';
@@ -132,7 +133,14 @@ export { useComputed$ } from './use/use-computed-dollar';
 export { useErrorBoundary } from './use/use-error-boundary';
 export type { ErrorBoundaryStore } from './shared/error/error-handling';
 export { type ReadonlySignal, type Signal, type ComputedSignal } from './signal/signal.public';
-export { isSignal, createSignal, createComputedQrl, createComputed$ } from './signal/signal.public';
+export {
+  isSignal,
+  createSignal,
+  createComputedQrl,
+  createComputed$,
+  createSerializedQrl,
+  createSerialized$,
+} from './signal/signal.public';
 export { EffectPropData as _EffectData } from './signal/signal';
 
 //////////////////////////////////////////////////////////////////////////////////////////

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

@@ -8,7 +8,15 @@ import { type DomContainer } from '../client/dom-container';
 import type { VNode } from '../client/types';
 import { vnode_getNode, vnode_isVNode, vnode_locate, vnode_toString } from '../client/vnode';
 import { NEEDS_COMPUTATION } from '../signal/flags';
-import { ComputedSignal, EffectPropData, Signal, WrappedSignal } from '../signal/signal';
+import {
+  ComputedSignal,
+  EffectPropData,
+  SerializedSignal,
+  Signal,
+  WrappedSignal,
+  isSerializerObj,
+  type EffectSubscriptions,
+} from '../signal/signal';
 import type { Subscriber } from '../signal/signal-subscriber';
 import {
   STORE_ARRAY_PROP,
@@ -283,13 +291,16 @@ const inflate = (
       signal.$effects$ = d.slice(5);
       break;
     }
+    case TypeIds.SerializedSignal:
     case TypeIds.ComputedSignal: {
       const computed = target as ComputedSignal<unknown>;
-      const d = data as [QRLInternal<() => {}>, any, unknown?];
+      const d = data as [QRLInternal<() => {}>, EffectSubscriptions[] | null, unknown?];
       computed.$computeQrl$ = d[0];
       computed.$effects$ = d[1];
-      if (d.length === 3) {
+      if (d.length >= 3) {
         computed.$untrackedValue$ = d[2];
+        // The serialized signal is always invalid so it can recreate the custom object
+        computed.$invalid$ = typeId === TypeIds.SerializedSignal;
       } else {
         computed.$invalid$ = true;
         /**
@@ -478,6 +489,8 @@ const allocate = (container: DeserializeContainer, typeId: number, value: unknow
       return new WrappedSignal(container as any, null!, null!, null!);
     case TypeIds.ComputedSignal:
       return new ComputedSignal(container as any, null!);
+    case TypeIds.SerializedSignal:
+      return new SerializedSignal(container as any, null!);
     case TypeIds.Store:
     case TypeIds.StoreArray:
       // ignore allocate, we need to assign target while creating store
@@ -884,7 +897,7 @@ export const createSerializationContext = (
         discoveredValues.push(obj.data);
       } else if (Array.isArray(obj)) {
         discoveredValues.push(...obj);
-      } else if (SerializerSymbol in obj && typeof obj[SerializerSymbol] === 'function') {
+      } else if (isSerializerObj(obj)) {
         const result = obj[SerializerSymbol](obj);
         serializationResults.set(obj, result);
         discoveredValues.push(result);
@@ -1168,7 +1181,7 @@ function serialize(serializationContext: SerializationContext): void {
        * Special case: when a Signal value is an SSRNode, it always needs to be a DOM ref instead.
        * It can never be meant to become a vNode, because vNodes are internal only.
        */
-      const v =
+      const v: unknown =
         value instanceof ComputedSignal &&
         (value.$invalid$ || fastSkipSerialize(value.$untrackedValue$))
           ? NEEDS_COMPUTATION
@@ -1183,15 +1196,18 @@ function serialize(serializationContext: SerializationContext): void {
           ...(value.$effects$ || []),
         ]);
       } else if (value instanceof ComputedSignal) {
-        const out = [
+        const out: [QRLInternal, EffectSubscriptions[] | null, unknown?] = [
           value.$computeQrl$,
           // TODO check if we can use domVRef for effects
           value.$effects$,
         ];
         if (v !== NEEDS_COMPUTATION) {
           out.push(v);
         }
-        output(TypeIds.ComputedSignal, out);
+        output(
+          value instanceof SerializedSignal ? TypeIds.SerializedSignal : TypeIds.ComputedSignal,
+          out
+        );
       } else {
         output(TypeIds.Signal, [v, ...(value.$effects$ || [])]);
       }
@@ -1629,6 +1645,7 @@ export const enum TypeIds {
   Signal,
   WrappedSignal,
   ComputedSignal,
+  SerializedSignal,
   Store,
   StoreArray,
   FormData,
@@ -1662,6 +1679,7 @@ export const _typeIdNames = [
   'Signal',
   'WrappedSignal',
   'ComputedSignal',
+  'SerializedSignal',
   'Store',
   'StoreArray',
   'FormData',