Merge pull request #67 from AlexandrHoroshih/feat-serializable-style-def

theKashey · web-flow · commit 52b56910c4d3 · 2024-06-28T14:07:46.000+10:00
Add APIs to support serializable lookup table
diff --git a/README.md b/README.md
@@ -134,9 +134,57 @@ import { enableReactOptimization } from 'used-styles';
 enableReactOptimization(); // just makes it a but faster
 ```
 
+## Serialize API
+
+Use it to separate generation of styles lookup from your runtime.
+
+It is useful in cases, where you can't directly use Discovery APIs on your client CSS bundles during app's runtime, e.g. various serverless runtimes.
+Also it may be useful for you, if you want to save on the size of your container for the server app, since it allows you to only load styles lookup into it, without CSS bundles.
+
+1. `serializeStylesLookup(def: StyleDef): SerializedStyleDef` - creates a serializable object from original styles lookup. Result can be then stringified with `JSON.stringify`
+2. `loadSerializedLookup(def: SerializedStyleDef): StyleDef` - transforms serialized style definition back to normal `StyleDef`, which can be used with any Scanner API
+
+### Example
+
+#### During your build
+
+1. Add separate script to generate style lookup and store it as you like.
+```js
+// project/scripts/generate_styles_lookup.mjs
+import { serializeStylesLookup, discoverProjectStyles } from 'used-styles'
+import { writeFileSync } from 'fs'
+
+const stylesLookup = discoverProjectStyles('./path/to/dist/client');
+
+await stylesLookup;
+
+writeFileSync('./path/to/dist/server/styles-lookup.json', JSON.stringify(serializeStyles(lookup)))
+```
+2. Run this code after your build
+```sh
+yarn build
+node ./scripts/generate_styles_lookup.mjs
+```
+
+Notice, that you can store serialized lookup in any way, that suits you and your case, example above is not the only valid option.
+
+#### During your runtime
+
+1. Access previously created and stored styles lookup, convert it to `StyleDef` with `loadSerializedLookup` and use it normally
+```js
+import { loadSerializedLookup } from 'used-styles'
+
+const stylesLookup = loadSerializedLookup(require('./dist/server/styles-lookup.json');
+
+// ...
+
+getCriticalStyles(markup, stylesLookup)
+```
+
 # Example
 
 ## Demo
+
 - [React SSR](/example/ssr-react/README.md)
 - [React SSR + TS](/example/ssr-react-ts/README.md)
 - [React Streaming SSR](/example/ssr-react-streaming/README.md)
@@ -197,10 +245,10 @@ similar how StyledComponents works
 
 ```js
 import express from 'express';
-import { 
-  discoverProjectStyles, 
+import {
+  discoverProjectStyles,
   loadStyleDefinitions,
-  createCriticalStyleStream, 
+  createCriticalStyleStream,
   createStyleStream,
   createLink,
 } from 'used-styles';
@@ -209,9 +257,9 @@ const app = express();
 
 // generate lookup table on server start
 const stylesLookup = isProduction
-  ? discoverProjectStyles('./dist/client') 
-  // load styles for development
-  : loadStyleDefinitions(async () => []);
+  ? discoverProjectStyles('./dist/client')
+  : // load styles for development
+    loadStyleDefinitions(async () => []);
 
 app.use('*', async (req, res) => {
   await stylesLookup;
@@ -222,7 +270,7 @@ app.use('*', async (req, res) => {
     // create a style steam
     const styledStream = createStyleStream(stylesLookup, (style) => {
       // _return_ link tag, and it will be appended to the stream output
-      return createLink(`dist/${style}`) // <link href="dist/mystyle.css />
+      return createLink(`dist/${style}`); // <link href="dist/mystyle.css />
     });
 
     // or create critical CSS stream - it will inline all styles
@@ -245,7 +293,7 @@ const ABORT_DELAY = 10000;
 
 async function renderApp({ res, styledStream }) {
   let didError = false;
-  
+
   const { pipe, abort } = renderToPipeableStream(
     <React.StrictMode>
       <App />
@@ -262,7 +310,7 @@ async function renderApp({ res, styledStream }) {
         res.write(`<!DOCTYPE html><html><head><script defer src="client.js"></script></head><body><div id="root">`);
 
         styledStream.pipe(res, { end: false });
-        
+
         // start by piping react and styled transform stream
         pipe(styledStream);
 
@@ -273,8 +321,8 @@ async function renderApp({ res, styledStream }) {
       onError(error) {
         didError = true;
         console.error(error);
-      }
-    },
+      },
+    }
   );
 
   setTimeout(() => {
@@ -297,7 +345,7 @@ import ReactDOM from 'react-dom/client';
 import App from './App';
 
 // Call before `ReactDOM.hydrateRoot`
-moveStyles()
+moveStyles();
 
 ReactDOM.hydrateRoot(
   document.getElementById('root'),
diff --git a/__tests__/__snapshots__/react.integration.spec.tsx.snap b/__tests__/__snapshots__/react.integration.spec.tsx.snap
@@ -13,6 +13,19 @@ input { display: none; }
 }</style>"
 `;
 
+exports[`File based css stream works with (de)serialized styles definition 1`] = `
+"<style type=\\"text/css\\" data-used-styles=\\"file1.css,file2.css\\">html { color: htmlRED; }
+input { display: none; }
+@keyframes ANIMATION_NAME {
+    0% {
+        -webkit-transform: rotate(0deg);
+    }
+    to {
+        -webkit-transform: rotate(359deg);
+    }
+}</style>"
+`;
+
 exports[`React css stream React.renderToStream critical 1`] = `
 "<style type=\\"text/css\\" data-used-styles=\\"file1,file2\\">input { color: rightInput; }
 .a,
diff --git a/__tests__/extraction.spec.tsx b/__tests__/extraction.spec.tsx
@@ -1,4 +1,11 @@
-import { alterProjectStyles, getCriticalRules, loadStyleDefinitions, StyleDefinition } from '../src';
+import {
+  alterProjectStyles,
+  loadSerializedLookup,
+  getCriticalRules,
+  loadStyleDefinitions,
+  serializeStylesLookup,
+  StyleDefinition,
+} from '../src';
 
 describe('extraction stories', () => {
   it('handles duplicated selectors', async () => {
@@ -208,6 +215,80 @@ describe('extraction stories', () => {
       `);
   });
 
+  describe('Serializable definitions', () => {
+    test('Serialized defintion is equal to original', async () => {
+      const styles: StyleDefinition = loadStyleDefinitions(
+        () => ['test.css'],
+        () => `
+  @media screen and (min-width:1350px){.content__L0XJ\\+{color:red}}
+  .primary__L4\\+dg{ color: blue}
+  .primary__L4+dg{ color: wrong}
+          `
+      );
+      await styles;
+
+      const serializedDefinition = JSON.stringify(serializeStylesLookup(styles));
+      const deserializedDefinition = loadSerializedLookup(JSON.parse(serializedDefinition));
+
+      expect(deserializedDefinition.lookup).toEqual(styles.lookup);
+      expect(deserializedDefinition.ast).toEqual(styles.ast);
+      expect(deserializedDefinition.urlPrefix).toEqual(styles.urlPrefix);
+      expect(deserializedDefinition.isReady).toEqual(styles.isReady);
+      expect(typeof deserializedDefinition.then).toEqual(typeof styles.then);
+    });
+
+    test('Serializing unready definition throws', async () => {
+      const styles: StyleDefinition = loadStyleDefinitions(
+        async () => ['test.css'],
+        async () => `
+  @media screen and (min-width:1350px){.content__L0XJ\\+{color:red}}
+  .primary__L4\\+dg{ color: blue}
+  .primary__L4+dg{ color: wrong}
+          `
+      );
+
+      expect(() => serializeStylesLookup(styles)).toThrowErrorMatchingInlineSnapshot(
+        `"used-styles: style definitions are not ready yet. You should \`await discoverProjectStyles(...)\`"`
+      );
+    });
+
+    test('Invalid value in serializers throws', async () => {
+      expect(() => serializeStylesLookup({} as any)).toThrowErrorMatchingInlineSnapshot(
+        `"used-styles: style definitions has to be created using discoverProjectStyles or loadStyleDefinitions"`
+      );
+
+      expect(() => loadSerializedLookup({} as any)).toThrowErrorMatchingInlineSnapshot(
+        `"used-styles: serialized style definition should be created with serializeStylesLookup"`
+      );
+
+      expect(() => loadSerializedLookup('invalid' as any)).toThrowErrorMatchingInlineSnapshot(
+        `"used-styles: got a string instead of serialized style definition object, make sure to parse it back to JS object first"`
+      );
+    });
+
+    test('Serialized defintion is awaitable just like original', async () => {
+      const styles: StyleDefinition = loadStyleDefinitions(
+        () => ['test.css'],
+        () => `
+  @media screen and (min-width:1350px){.content__L0XJ\\+{color:red}}
+  .primary__L4\\+dg{ color: blue}
+  .primary__L4+dg{ color: wrong}
+          `
+      );
+      await styles;
+
+      const serializedDefinition = JSON.stringify(serializeStylesLookup(styles));
+      const deserializedDefinition = loadSerializedLookup(JSON.parse(serializedDefinition));
+
+      await deserializedDefinition;
+
+      const resolve = jest.fn();
+      await deserializedDefinition.then(resolve);
+
+      expect(resolve).toBeCalledTimes(1);
+    });
+  });
+
   describe('CSS Cascade Layers', () => {
     it('handles CSS Cascade Layers', async () => {
       const styles = loadStyleDefinitions(
diff --git a/__tests__/react.integration.spec.tsx b/__tests__/react.integration.spec.tsx
@@ -13,6 +13,8 @@ import {
   getCriticalStyles,
   getUsedStyles,
   parseProjectStyles,
+  serializeStylesLookup,
+  loadSerializedLookup,
 } from '../src';
 import { StyleDefinition } from '../src/types';
 
@@ -104,6 +106,47 @@ describe('File based css stream', () => {
 
     expect(usedCritical).toMatch(/htmlRED/);
   });
+
+  test('works with (de)serialized styles definition', async () => {
+    await styles;
+
+    const lookupAfterSerialization = loadSerializedLookup(JSON.parse(JSON.stringify(serializeStylesLookup(styles))));
+
+    expect(getUsedStyles('', lookupAfterSerialization)).toEqual(['file1.css']);
+    expect(getCriticalStyles('', lookupAfterSerialization)).toMatchSnapshot();
+
+    const output = renderToString(
+      <div>
+        <div className="only someclass">
+          <div className="another class11">
+            {Array(10)
+              .fill(1)
+              .map((_, index) => (
+                <div key={index}>
+                  <span className="d">{index}</span>
+                </div>
+              ))}
+            <div className="class1" />
+          </div>
+        </div>
+      </div>
+    );
+
+    const usedFiles = getUsedStyles(output, lookupAfterSerialization);
+    const usedCritical = getCriticalStyles(output, lookupAfterSerialization);
+
+    expect(usedFiles).toEqual(['file1.css', 'file2.css']);
+
+    expect(usedCritical).toMatch(/selector-11/);
+    expect(usedCritical).toMatch(/data-from-file1/);
+    expect(usedCritical).not.toMatch(/data-wrong-file1/);
+    expect(usedCritical).toMatch(/data-from-file2/);
+    expect(usedCritical).not.toMatch(/data-wrong-file1/);
+
+    expect(usedCritical).toMatch(/ANIMATION_NAME/);
+
+    expect(usedCritical).toMatch(/htmlRED/);
+  });
 });
 
 describe('React css stream', () => {
diff --git a/src/index.ts b/src/index.ts
@@ -8,6 +8,8 @@ import { discoverProjectStyles, loadStyleDefinitions, parseProjectStyles } from
 
 import { createUsedFilter as createUsedSelectorsFilter } from './utils/cache';
 
+export { serializeStylesLookup, loadSerializedLookup } from './serialize';
+
 export { UsedTypes, StyleDefinition, SelectionFilter } from './types';
 
 export {
diff --git a/src/serialize.ts b/src/serialize.ts
@@ -0,0 +1,46 @@
+import type { StyleDefinition, SerializedStyleDefinition } from './types';
+import { assertIsReady } from './utils/async';
+
+export function serializeStylesLookup(def: StyleDefinition): SerializedStyleDefinition {
+  assertIsReady(def);
+
+  return {
+    lookup: def.lookup,
+    ast: def.ast,
+    urlPrefix: def.urlPrefix,
+  };
+}
+
+export function loadSerializedLookup(def: SerializedStyleDefinition): StyleDefinition {
+  assertValidLookup(def);
+
+  return {
+    isReady: true,
+    lookup: def.lookup,
+    ast: def.ast,
+    urlPrefix: def.urlPrefix,
+    /**
+     * Serialized style definition is already ready,
+     * so `then` here is just a noop for compatibility
+     */
+    then: (res) => {
+      if (res) {
+        res();
+      }
+
+      return Promise.resolve();
+    },
+  };
+}
+
+function assertValidLookup(def: any): asserts def is SerializedStyleDefinition {
+  if (typeof def === 'string') {
+    throw new Error(
+      'used-styles: got a string instead of serialized style definition object, make sure to parse it back to JS object first'
+    );
+  }
+
+  if (!('lookup' in def) || typeof def.lookup !== 'object') {
+    throw new Error('used-styles: serialized style definition should be created with serializeStylesLookup');
+  }
+}
diff --git a/src/types.ts b/src/types.ts
@@ -38,6 +38,12 @@ export type StyleDefinition = Readonly<{
   then(resolve?: () => void, reject?: () => void): Promise<void>;
 }>;
 
+export type SerializedStyleDefinition = Readonly<{
+  lookup: Readonly<StylesLookupTable>;
+  ast: Readonly<StyleAst>;
+  urlPrefix: string;
+}>;
+
 /**
  * A function used to control which selectors should be used
  * @param selector - DEPRECATED
