feat(core): serializer support

FEAT: `NoSerializeSymbol`: objects that have this defined will not be serialized

FEAT: `SerializerSymbol`: objects that have this defined as a function will get it called with the object as a parameter during serialization. The function should return the data that should be serialized.
Use this to remove cached data, consolidate things etc.

Author: wmertens

.changeset/tricky-peaches-buy.md

@@ -0,0 +1,8 @@
+---
+'@qwik.dev/core': minor
+---
+
+FEAT: `NoSerializeSymbol`: objects that have this defined will not be serialized
+
+FEAT: `SerializerSymbol`: objects that have this defined as a function will get it called with the object as a parameter during serialization. The function should return the data that should be serialized.
+Use this to remove cached data, consolidate things etc.

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

@@ -841,6 +841,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/shared/utils/serialize-utils.ts",
       "mdFile": "core.noserialize.md"
     },
+    {
+      "name": "NoSerializeSymbol",
+      "id": "noserializesymbol",
+      "hierarchy": [
+        {
+          "name": "NoSerializeSymbol",
+          "id": "noserializesymbol"
+        }
+      ],
+      "kind": "Variable",
+      "content": "If an object has this property, it will not be serialized\n\n\n```typescript\nNoSerializeSymbol: unique symbol\n```",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/shared/utils/serialize-utils.ts",
+      "mdFile": "core.noserializesymbol.md"
+    },
     {
       "name": "OnRenderFn",
       "id": "onrenderfn",
@@ -1541,6 +1555,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-resource.ts",
       "mdFile": "core.resourcereturn.md"
     },
+    {
+      "name": "SerializerSymbol",
+      "id": "serializersymbol",
+      "hierarchy": [
+        {
+          "name": "SerializerSymbol",
+          "id": "serializersymbol"
+        }
+      ],
+      "kind": "Variable",
+      "content": "If an object has this property as a function, it will be called with the object and should return a serializable value.\n\nThis can be used to clean up etc.\n\n\n```typescript\nSerializerSymbol: unique symbol\n```",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/shared/utils/serialize-utils.ts",
+      "mdFile": "core.serializersymbol.md"
+    },
     {
       "name": "setPlatform",
       "id": "setplatform",

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

@@ -1855,6 +1855,16 @@ export type NoSerialize<T> =
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/shared/utils/serialize-utils.ts)
 
+## NoSerializeSymbol
+
+If an object has this property, it will not be serialized
+
+```typescript
+NoSerializeSymbol: unique symbol
+```
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/shared/utils/serialize-utils.ts)
+
 ## OnRenderFn
 
 ```typescript
@@ -3549,6 +3559,18 @@ export type ResourceReturn<T> =
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-resource.ts)
 
+## SerializerSymbol
+
+If an object has this property as a function, it will be called with the object and should return a serializable value.
+
+This can be used to clean up etc.
+
+```typescript
+SerializerSymbol: unique symbol
+```
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/shared/utils/serialize-utils.ts)
+
 ## setPlatform
 
 Sets the `CorePlatform`.

packages/qwik/src/core/api.md

@@ -498,6 +498,9 @@ export type NoSerialize<T> = (T & {
 // @public
 export const noSerialize: <T extends object | undefined>(input: T) => NoSerialize<T>;
 
+// @public
+export const NoSerializeSymbol: unique symbol;
+
 // @public (undocumented)
 export type OnRenderFn<PROPS> = (props: PROPS) => JSXOutput;
 
@@ -811,6 +814,9 @@ export const _restProps: (props: Record<string, any>, omit: string[], target?: {
 // @internal
 export function _serialize(data: unknown[]): Promise<string>;
 
+// @public
+export const SerializerSymbol: unique symbol;
+
 // @public
 export const setPlatform: (plt: CorePlatform) => CorePlatform;
 

packages/qwik/src/core/index.ts

@@ -139,7 +139,11 @@ export { EffectPropData as _EffectData } from './signal/signal';
 // Developer Low-Level API
 //////////////////////////////////////////////////////////////////////////////////////////
 export type { ValueOrPromise } from './shared/utils/types';
-export { type NoSerialize } from './shared/utils/serialize-utils';
+export {
+  NoSerializeSymbol,
+  SerializerSymbol,
+  type NoSerialize,
+} from './shared/utils/serialize-utils';
 export { noSerialize } from './shared/utils/serialize-utils';
 export { version } from './version';
 

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

@@ -48,7 +48,7 @@ import { isElement, isNode } from './utils/element';
 import { EMPTY_ARRAY, EMPTY_OBJ } from './utils/flyweight';
 import { ELEMENT_ID, ELEMENT_KEY } from './utils/markers';
 import { isPromise } from './utils/promises';
-import { fastSkipSerialize } from './utils/serialize-utils';
+import { SerializerSymbol, fastSkipSerialize } from './utils/serialize-utils';
 import { type ValueOrPromise } from './utils/types';
 
 const deserializedProxyMap = new WeakMap<object, unknown[]>();
@@ -864,8 +864,6 @@ export const createSerializationContext = (
         discoveredValues.push(obj.$ssrNode$.id);
       } else if (isJSXNode(obj)) {
         discoveredValues.push(obj.type, obj.props, obj.constProps, obj.children);
-      } else if (Array.isArray(obj)) {
-        discoveredValues.push(...obj);
       } else if (isQrl(obj)) {
         obj.$captureRef$ && obj.$captureRef$.length && discoveredValues.push(...obj.$captureRef$);
       } else if (isPropsProxy(obj)) {
@@ -884,6 +882,12 @@ export const createSerializationContext = (
         promises.push(obj);
       } else if (obj instanceof EffectPropData) {
         discoveredValues.push(obj.data);
+      } else if (Array.isArray(obj)) {
+        discoveredValues.push(...obj);
+      } else if (SerializerSymbol in obj && typeof obj[SerializerSymbol] === 'function') {
+        const result = obj[SerializerSymbol](obj);
+        serializationResults.set(obj, result);
+        discoveredValues.push(result);
       } else if (isObjectLiteral(obj)) {
         Object.entries(obj).forEach(([key, value]) => {
           discoveredValues.push(key, value);
@@ -940,6 +944,7 @@ const discoverValuesForVNodeData = (vnodeData: VNodeData, discoveredValues: unkn
 };
 
 const promiseResults = new WeakMap<Promise<any>, [boolean, unknown]>();
+const serializationResults = new WeakMap<object, unknown>();
 
 /**
  * Format:
@@ -1134,6 +1139,11 @@ function serialize(serializationContext: SerializationContext): void {
         }
         output(Array.isArray(storeTarget) ? TypeIds.StoreArray : TypeIds.Store, out);
       }
+    } else if (SerializerSymbol in value && typeof value[SerializerSymbol] === 'function') {
+      const result = serializationResults.get(value);
+      depth--;
+      writeValue(result, idx);
+      depth++;
     } else if (isObjectLiteral(value)) {
       if (Array.isArray(value)) {
         output(TypeIds.Array, value);

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

@@ -1,4 +1,4 @@
-import { $, component$ } from '@qwik.dev/core';
+import { $, component$, noSerialize } from '@qwik.dev/core';
 import { describe, expect, it } from 'vitest';
 import { _fnSignal, _wrapProp } from '../internal';
 import { EffectPropData, type Signal } from '../signal/signal';
@@ -17,6 +17,7 @@ import {
   dumpState,
 } from './shared-serialization';
 import { EMPTY_ARRAY, EMPTY_OBJ } from './utils/flyweight';
+import { NoSerializeSymbol, SerializerSymbol } from './utils/serialize-utils';
 
 const DEBUG = false;
 
@@ -780,6 +781,57 @@ describe('shared-serialization', () => {
       expect((obj as any).shared).toBe(newValue);
     });
   });
+
+  describe('custom serialization', () => {
+    it('should ignore noSerialize', async () => {
+      const obj = { hi: true };
+      const state = await serialize(noSerialize(obj));
+      expect(dumpState(state)).toMatchInlineSnapshot(`
+        "
+        0 Constant undefined
+        (5 chars)"
+      `);
+    });
+    it('should ignore NoSerializeSymbol', async () => {
+      const obj = { hi: true, [NoSerializeSymbol]: true };
+      const state = await serialize(obj);
+      expect(dumpState(state)).toMatchInlineSnapshot(`
+        "
+        0 Constant undefined
+        (5 chars)"
+      `);
+    });
+    it('should use SerializerSymbol', async () => {
+      const obj = { hi: 'obj', [SerializerSymbol]: (o: any) => o.hi };
+      class Foo {
+        hi = 'class';
+        [SerializerSymbol]() {
+          return this.hi;
+        }
+      }
+      const state = await serialize([obj, new Foo()]);
+      expect(dumpState(state)).toMatchInlineSnapshot(`
+        "
+        0 Array [
+          String "obj"
+          String "class"
+        ]
+        (23 chars)"
+      `);
+    });
+    it('should not use SerializeSymbol if not function', async () => {
+      const obj = { hi: 'orig', [SerializerSymbol]: 'hey' };
+      const state = await serialize(obj);
+      expect(dumpState(state)).toMatchInlineSnapshot(`
+        "
+        0 Object [
+          String "hi"
+          String "orig"
+        ]
+        (22 chars)"
+      `);
+    });
+  });
 });
 
 async function serialize(...roots: any[]): Promise<any[]> {

packages/qwik/src/core/shared/utils/serialize-utils.ts

@@ -93,7 +93,7 @@ export const shouldSerialize = (obj: unknown): boolean => {
 };
 
 export const fastSkipSerialize = (obj: object): boolean => {
-  return noSerializeSet.has(obj);
+  return typeof obj === 'object' && obj && (NoSerializeSymbol in obj || noSerializeSet.has(obj));
 };
 
 export const fastWeakSerialize = (obj: object): boolean => {
@@ -140,3 +140,19 @@ export const _weakSerialize = <T extends object>(input: T): Partial<T> => {
   weakSerializeSet.add(input);
   return input as any;
 };
+
+/**
+ * If an object has this property, it will not be serialized
+ *
+ * @public
+ */
+export const NoSerializeSymbol = Symbol('noSerialize');
+/**
+ * If an object has this property as a function, it will be called with the object and should return
+ * a serializable value.
+ *
+ * This can be used to clean up etc.
+ *
+ * @public
+ */
+export const SerializerSymbol = Symbol('serialize');