zero-com 0.0.4 → 0.0.5

package/README.md

@@ -2,28 +2,70 @@
 
 It is a zero-byte no-lib utility for transparently communicating client-side and server-side modules residing in the same full-stack project.
 
+## Table of Contents
+
+- [Usage](#usage)
+- [Transport layer](#transport-layer)
+- [Context](#context)
+- [Plugin options](#plugin-options)
+- [Complete Example](#complete-example)
+
 ## Usage
 
-Webpack config.
-```js
-new ZeroComWebpackPlugin({
-  development: true,
-  patterns: {
-    client: 'src/client/**',
-    server: 'src/server/api/**',
-  }
-})
+Zero-com can be used with either Webpack or Rollup.
+
+### Webpack
+
+To use Zero-com with Webpack, you need to add the `ZeroComWebpackPlugin` to your `webpack.config.js` file.
+
+```javascript
+// webpack.config.js
+const { ZeroComWebpackPlugin } = require('zero-com/webpack');
+
+module.exports = {
+  // ... your webpack config
+  plugins: [
+    new ZeroComWebpackPlugin({
+      development: true,
+      patterns: {
+        client: 'src/client/**',
+        server: 'src/server/api/**',
+      },
+    }),
+  ],
+};
 ```
 
-The above code will identify all the references from client-side code to the server-side files and will tranform the modules to comunicate through your defined transport layer. The only callable functions in the server-side modules will be the exported async functions (not arrow functions). See the example below.
+### Rollup
+
+To use Zero-com with Rollup, you need to add the `zeroComRollupPlugin` to your `rollup.config.js` file.
+
+```javascript
+// rollup.config.js
+import zeroComRollupPlugin from 'zero-com/rollup';
+
+export default {
+  // ... your rollup config
+  plugins: [
+    zeroComRollupPlugin({
+      development: true,
+      patterns: {
+        client: 'src/client/**',
+        server: 'src/server/api/**',
+      },
+    }),
+  ],
+};
+```
+
+The above code will identify all the references from client-side code to the server-side files and will tranform the modules to comunicate through your defined transport layer. The only callable functions in the server-side modules will be the exported async functions. See the example below.
 
 Server side
 ```js
 // server/phones.ts
-// callable
 export async function getPhones() { }
 
-// not callable from client-side
+// or
 export const getPhones = async () => { }
 ```
 
@@ -33,30 +75,264 @@ Client side
 import { getPhones } '../server/phones'
 ```
 
-## Trasport layer
-Zero-com does not define any transport layer, it allows you to define a new one or reuse your own.
+## Transport layer
 
-- `window.ZERO_COM_CLIENT_SEND` all mesages from client-side will be sent using this function.
-- `global.ZERO_COM_SERVER_REGISTRY` object available on the server-side of which the keys are the name of the methods and the values ​​are the functions to be executed.
+Zero-com does not define any transport layer, it is up to you to create one or reuse your own. This means you have complete control over how data is sent between the client and server.
 
-Client side example.
-```js
-window.ZERO_COM_CLIENT_SEND = async ({ method, params }) {
-  // -> send the message to server
-  // <- return response
-}
+### Communication Flow
+
+The following diagram illustrates the communication flow between the client and server:
+
+```
++--------+      +-----------------------------+      +-------------+
+| Client |----->| window.ZERO_COM_CLIENT_SEND |----->| Your Server |
++--------+      +-----------------------------+      +-------------+
+                                                           |
+                                                           v
++--------+      +-------------------------+      +-------------------+
+| Client |<-----| (Your custom transport) |<-----| someCustomHandler |
++--------+      +-------------------------+      +-------------------+
 ```
 
-Server side example.
-```js
-const someCustomHandler = (message) => {
-  const func = global.ZERO_COM_SERVER_REGISTRY[message.method]
-  return func(...message.params)
-}
+### Client-side
+
+All messages from the client-side will be sent using the `window.ZERO_COM_CLIENT_SEND` function. You need to define this function in your client-side code.
+
+```javascript
+// client/transport.js
+window.ZERO_COM_CLIENT_SEND = async ({ funcId, params }) => {
+  const response = await fetch('http://localhost:8000/api', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ funcId, params }),
+  });
+  return await response.json();
+};
+```
+
+### Server-side
+
+On the server-side, you need to create a handler that receives messages from the client, executes the corresponding function, and returns the result. The `global.ZERO_COM_SERVER_REGISTRY` object contains all the server functions that can be called from the client.
+
+```javascript
+// server/api.js
+import { execServerFn } from 'zero-com';
+
+const someCustomHandler = async (message) => {
+  const func = global.ZERO_COM_SERVER_REGISTRY[message.funcId];
+  if (func) {
+    return await execServerFn(func, message.params);
+  } else {
+    throw new Error(`Function with id ${message.funcId} not found.`);
+  }
+};
+
+// Example of how to use the handler with an Express server
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+app.post('/api', async (req, res) => {
+  try {
+    const result = await someCustomHandler(req.body);
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.listen(8000, () => {
+  console.log('Server running at http://localhost:8000/');
+});
+```
+
+## Context
+
+Often you want to pass a context-related object to the server functions to have access to data like the request, response, session, etc. Zero-com provides a simple way to do this.
+
+### Passing Context to Server Functions
+
+To pass context to a server function, you need to wrap the function in `serverFn` and receive the context as the first parameter.
+
+```javascript
+// server/api/phones.js
+import { serverFn } from 'zero-com';
+
+export const getPhones = serverFn(async (ctx, name) => {
+  // ctx is the context object passed from the server
+  console.log(ctx.request.headers);
+  // ... your code
+});
+```
+
+### Providing Context on the Server
+
+You can pass the context to `execServerFn` when you execute the server function.
+
+```javascript
+// server/api.js
+import { execServerFn } from 'zero-com';
+
+const myHandler = (request, response, message) => {
+  const ctx = { request, response };
+  const func = global.ZERO_COM_SERVER_REGISTRY[message.funcId];
+  // pass context on exec
+  return execServerFn(func, ctx, message.params);
+};
 ```
 
 ## Plugin options
-- development: if `false` will add internal variable renaming to the final bundle.
-- patterns
-  - client: pattern to identify client-side files
-  - server: pattern to identify server-side files
+
+| Option      | Type      | Description                                                                 |
+|-------------|-----------|-----------------------------------------------------------------------------|
+| `development` | `boolean`   | If `false`, will add internal variable renaming to the final bundle.        |
+| `patterns`    | `object`    |                                                                             |
+| `patterns.client` | `string` | A glob pattern to identify client-side files.                               |
+| `patterns.server` | `string` | A glob pattern to identify server-side files.                               |
+
+## Complete Example
+
+Here's a complete example of how to use Zero-com in a project.
+
+### Project Structure
+
+```
+.
+├── package.json
+├── webpack.config.js
+├── rollup.config.js
+└── src
+    ├── client
+    │   ├── index.js
+    │   └── transport.js
+    └── server
+        └── api
+            └── phones.js
+```
+
+### Client-side
+
+```javascript
+// src/client/index.js
+import { getPhones } from '../../server/api/phones';
+
+async function main() {
+  const phones = await getPhones('iPhone');
+  console.log(phones);
+}
+
+main();
+```
+
+```javascript
+// src/client/transport.js
+window.ZERO_COM_CLIENT_SEND = async ({ funcId, params }) => {
+  const response = await fetch('http://localhost:8000/api', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ funcId, params }),
+  });
+  return await response.json();
+};
+```
+
+### Server-side
+
+```javascript
+// src/server/api/phones.js
+import { serverFn } from 'zero-com';
+
+export const getPhones = serverFn(async (ctx, name) => {
+  // In a real application, you would fetch this from a database
+  const allPhones = [
+    { name: 'iPhone 13', brand: 'Apple' },
+    { name: 'Galaxy S22', brand: 'Samsung' },
+  ];
+
+  return allPhones.filter((phone) => phone.name.includes(name));
+});
+```
+
+### Server
+
+```javascript
+// server.js
+import express from 'express';
+import { execServerFn } from 'zero-com';
+import './src/server/api/phones.js'; // Make sure to import the server-side modules
+
+const app = express();
+app.use(express.json());
+
+app.post('/api', async (req, res) => {
+  const { funcId, params } = req.body;
+  const func = global.ZERO_COM_SERVER_REGISTRY[funcId];
+
+  if (func) {
+    try {
+      const result = await execServerFn(func, { req, res }, params);
+      res.json(result);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  } else {
+    res.status(404).json({ error: `Function with id ${funcId} not found.` });
+  }
+});
+
+app.listen(8000, () => {
+  console.log('Server running at http://localhost:8000/');
+});
+```
+
+### Webpack Configuration
+
+```javascript
+// webpack.config.js
+const { ZeroComWebpackPlugin } = require('zero-com/webpack');
+
+module.exports = {
+  mode: 'development',
+  entry: './src/client/index.js',
+  output: {
+    filename: 'main.js',
+    path: __dirname + '/dist',
+  },
+  plugins: [
+    new ZeroComWebpackPlugin({
+      patterns: {
+        client: 'src/client/**',
+        server: 'src/server/api/**',
+      },
+    }),
+  ],
+};
+```
+
+### Rollup Configuration
+
+```javascript
+// rollup.config.js
+import zeroComRollupPlugin from 'zero-com/rollup';
+
+export default {
+  input: 'src/client/index.js',
+  output: {
+    file: 'dist/main.js',
+    format: 'cjs',
+  },
+  plugins: [
+    zeroComRollupPlugin({
+      patterns: {
+        client: 'src/client/**',
+        server: 'src/server/api/**',
+      },
+    }),
+  ],
+};
+```

package/index.js

@@ -1,123 +1,17 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZeroComWebpackPlugin = void 0;
-const fs_1 = __importDefault(require("fs"));
-const minimatch_1 = require("minimatch");
-const path_1 = __importDefault(require("path"));
-const ts_morph_1 = require("ts-morph");
-const typescript_1 = __importDefault(require("typescript"));
-class ZeroComWebpackPlugin {
-    constructor(options) {
-        this.options = Object.assign(Object.assign({ development: true }, options), { patterns: Object.assign({}, options.patterns) });
-        this.compilationId = String(Math.floor(Math.random() * 1000000));
-        this.clientPattern = this.options.patterns.client;
-        this.serverPattern = this.options.patterns.server;
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
     }
-    apply(compiler) {
-        const ZERO_COM_CLIENT_SEND = 'ZERO_COM_CLIENT_SEND';
-        const ZERO_COM_SERVER_REGISTRY = 'ZERO_COM_SERVER_REGISTRY';
-        const pluginName = ZeroComWebpackPlugin.name;
-        const { webpack } = compiler;
-        const { RawSource } = webpack.sources;
-        compiler.hooks.normalModuleFactory.tap(pluginName, (nmf) => {
-            nmf.hooks.beforeResolve.tap(pluginName, (resolveData) => {
-                const absolutePath = path_1.default.resolve(resolveData.context, resolveData.request);
-                const isServerFile = (0, minimatch_1.minimatch)(absolutePath, path_1.default.join(compiler.context, this.serverPattern));
-                if (!isServerFile)
-                    return;
-                const requestedFromClient = (0, minimatch_1.minimatch)(resolveData.contextInfo.issuer, path_1.default.join(compiler.context, this.clientPattern));
-                const tsPath = absolutePath + '.ts';
-                const jsPath = absolutePath + '.js';
-                const mjsPath = absolutePath + '.mjs';
-                let resolvedPath = '';
-                if (fs_1.default.existsSync(tsPath)) {
-                    resolvedPath = tsPath;
-                }
-                else if (fs_1.default.existsSync(jsPath)) {
-                    resolvedPath = jsPath;
-                }
-                else if (fs_1.default.existsSync(mjsPath)) {
-                    resolvedPath = mjsPath;
-                }
-                else {
-                    throw new Error('Unable to resolve: ' + absolutePath);
-                }
-                const originalContent = fs_1.default.readFileSync(resolvedPath, 'utf8');
-                const project = new ts_morph_1.Project({
-                    compilerOptions: {
-                        target: typescript_1.default.ScriptTarget.ES2017,
-                        module: typescript_1.default.ModuleKind.ESNext,
-                    },
-                });
-                const sourceFile = project.createSourceFile(absolutePath, originalContent, { overwrite: true });
-                let newModuleContent = '';
-                if (requestedFromClient) {
-                    const generatedFunctions = [];
-                    sourceFile.getFunctions().forEach(func => {
-                        if (func.isExported() && func.isAsync()) {
-                            const funcName = String(func.getName());
-                            const lineNumber = func.getStartLineNumber();
-                            const funcParams = func.getParameters().map(p => p.getName()).join(', ');
-                            const method = formatMethodName(funcName, path_1.default.relative(compiler.context, absolutePath), lineNumber);
-                            const newFunctionBody = `return window.${ZERO_COM_CLIENT_SEND}({method: '${method}', params: [${funcParams}]})`;
-                            func.setBodyText(newFunctionBody);
-                            generatedFunctions.push(func.getText());
-                            console.log('client:', method);
-                        }
-                    });
-                    newModuleContent = generatedFunctions.join('\n\n');
-                }
-                else {
-                    const chunks = [];
-                    sourceFile.getFunctions().forEach(func => {
-                        if (func.isExported() && func.isAsync()) {
-                            const funcName = String(func.getName());
-                            const lineNumber = func.getStartLineNumber();
-                            const method = formatMethodName(funcName, path_1.default.relative(compiler.context, absolutePath), lineNumber);
-                            chunks.push(`global.${ZERO_COM_SERVER_REGISTRY}['${method}'] = ${funcName}`);
-                            console.log('server:', method);
-                        }
-                    });
-                    newModuleContent = `${originalContent} if (!global.${ZERO_COM_SERVER_REGISTRY}) global.${ZERO_COM_SERVER_REGISTRY} = Object.create(null); ${chunks.join(',')}`;
-                }
-                project.createSourceFile(absolutePath + '.ts', newModuleContent, { overwrite: true });
-                const result = project.emitToMemory();
-                const newContent = result.getFiles()[0].text;
-                const inlineLoader = `data:text/javascript,${encodeURIComponent(newContent)}`;
-                resolveData.request = inlineLoader;
-            });
-        });
-        if (this.options.development)
-            return;
-        const replacements = [
-            { target: ZERO_COM_CLIENT_SEND, replacement: `__ZERO_COM_CLIENT_SEND_${this.compilationId}` },
-            { target: ZERO_COM_SERVER_REGISTRY, replacement: `__ZERO_COM_SERVER_REGISTRY_${this.compilationId}` }
-        ];
-        compiler.hooks.thisCompilation.tap(pluginName, (compilation) => {
-            compilation.hooks.processAssets.tap({ name: pluginName, stage: webpack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE }, (assets) => {
-                for (const assetName in assets) {
-                    if (assetName.endsWith('.js')) {
-                        let assetSource = String(assets[assetName].source());
-                        let modified = false;
-                        replacements.forEach(({ target, replacement }) => {
-                            if (assetSource.includes(target)) {
-                                assetSource = assetSource.replaceAll(target, replacement);
-                                modified = true;
-                            }
-                        });
-                        if (modified) {
-                            compilation.updateAsset(assetName, new RawSource(assetSource));
-                        }
-                    }
-                }
-            });
-        });
-    }
-}
-exports.ZeroComWebpackPlugin = ZeroComWebpackPlugin;
-const formatMethodName = (funcName, path, line) => {
-    return `${funcName}@${path}:${line}`;
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib/index"), exports);

package/index.ts

@@ -1,154 +1 @@
-import fs from 'fs'
-import { minimatch } from 'minimatch'
-import path from 'path'
-import { Project } from 'ts-morph'
-import ts from 'typescript'
-import { Compiler } from 'webpack'
-
-type Options = {
-  development?: boolean,
-  patterns: {
-    client: string,
-    server: string,
-  }
-}
-
-export type Message = {
-  method: string,
-  params: any[],
-  [key: string]: any
-}
-
-export class ZeroComWebpackPlugin {
-  private options: Options
-  private compilationId: string
-  private clientPattern: string
-  private serverPattern: string
-
-  constructor(options: Options) {
-    this.options = {
-      development: true,
-      ...options,
-      patterns: {
-        ...options.patterns
-      }
-    }
-    this.compilationId = String(Math.floor(Math.random() * 1000000))
-    this.clientPattern = this.options.patterns.client
-    this.serverPattern = this.options.patterns.server
-  }
-
-  apply(compiler: Compiler) {
-    const ZERO_COM_CLIENT_SEND = 'ZERO_COM_CLIENT_SEND'
-    const ZERO_COM_SERVER_REGISTRY = 'ZERO_COM_SERVER_REGISTRY'
-
-    const pluginName = ZeroComWebpackPlugin.name
-    const { webpack } = compiler
-    const { RawSource } = webpack.sources
-
-    compiler.hooks.normalModuleFactory.tap(pluginName, (nmf) => {
-      nmf.hooks.beforeResolve.tap(pluginName, (resolveData) => {
-        const absolutePath = path.resolve(resolveData.context, resolveData.request)
-        const isServerFile = minimatch(absolutePath, path.join(compiler.context, this.serverPattern))
-        if (!isServerFile) return
-
-        const requestedFromClient = minimatch(resolveData.contextInfo.issuer, path.join(compiler.context, this.clientPattern))
-
-        const tsPath = absolutePath + '.ts'
-        const jsPath = absolutePath + '.js'
-        const mjsPath = absolutePath + '.mjs'
-        let resolvedPath = ''
-
-        if (fs.existsSync(tsPath)) {
-          resolvedPath = tsPath
-        } else if (fs.existsSync(jsPath)) {
-          resolvedPath = jsPath
-        } else if (fs.existsSync(mjsPath)) {
-          resolvedPath = mjsPath
-        } else {
-          throw new Error('Unable to resolve: ' + absolutePath)
-        }
-
-        const originalContent = fs.readFileSync(resolvedPath, 'utf8')
-
-        const project = new Project({
-          compilerOptions: {
-            target: ts.ScriptTarget.ES2017,
-            module: ts.ModuleKind.ESNext,
-          },
-        })
-
-        const sourceFile = project.createSourceFile(absolutePath, originalContent, { overwrite: true })
-        let newModuleContent = ''
-
-        if (requestedFromClient) {
-          const generatedFunctions: string[] = []
-          sourceFile.getFunctions().forEach(func => {
-            if (func.isExported() && func.isAsync()) {
-              const funcName = String(func.getName())
-              const lineNumber = func.getStartLineNumber()
-              const funcParams = func.getParameters().map(p => p.getName()).join(', ')
-              const method = formatMethodName(funcName, path.relative(compiler.context, absolutePath), lineNumber)
-              const newFunctionBody = `return window.${ZERO_COM_CLIENT_SEND}({method: '${method}', params: [${funcParams}]})`
-              func.setBodyText(newFunctionBody)
-              generatedFunctions.push(func.getText())
-              console.log('client:', method)
-            }
-          })
-          newModuleContent = generatedFunctions.join('\n\n')
-        } else {
-          const chunks: string[] = []
-          sourceFile.getFunctions().forEach(func => {
-            if (func.isExported() && func.isAsync()) {
-              const funcName = String(func.getName())
-              const lineNumber = func.getStartLineNumber()
-              const method = formatMethodName(funcName, path.relative(compiler.context, absolutePath), lineNumber)
-              chunks.push(`global.${ZERO_COM_SERVER_REGISTRY}['${method}'] = ${funcName}`)
-              console.log('server:', method)
-            }
-          })
-          newModuleContent = `${originalContent} if (!global.${ZERO_COM_SERVER_REGISTRY}) global.${ZERO_COM_SERVER_REGISTRY} = Object.create(null); ${chunks.join(',')}`
-        }
-
-        project.createSourceFile(absolutePath + '.ts', newModuleContent, { overwrite: true })
-        const result = project.emitToMemory()
-        const newContent = result.getFiles()[0].text
-        const inlineLoader = `data:text/javascript,${encodeURIComponent(newContent)}`
-        resolveData.request = inlineLoader
-      })
-    })
-
-    if (this.options.development) return
-
-    const replacements = [
-      { target: ZERO_COM_CLIENT_SEND, replacement: `__ZERO_COM_CLIENT_SEND_${this.compilationId}` },
-      { target: ZERO_COM_SERVER_REGISTRY, replacement: `__ZERO_COM_SERVER_REGISTRY_${this.compilationId}` }
-    ]
-
-    compiler.hooks.thisCompilation.tap(pluginName, (compilation) => {
-      compilation.hooks.processAssets.tap({ name: pluginName, stage: webpack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE }, (assets) => {
-        for (const assetName in assets) {
-          if (assetName.endsWith('.js')) {
-            let assetSource = String(assets[assetName].source())
-            let modified = false
-            replacements.forEach(({ target, replacement }) => {
-              if (assetSource.includes(target)) {
-                assetSource = assetSource.replaceAll(target, replacement)
-                modified = true
-              }
-            })
-            if (modified) {
-              compilation.updateAsset(assetName, new RawSource(assetSource))
-            }
-          }
-        }
-
-      })
-    })
-
-  }
-}
-
-const formatMethodName = (funcName: string, path: string, line: number) => {
-  return `${funcName}@${path}:${line}`
-}
+export * from './lib/index'

package/lib/common.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatFuncIdName = exports.ZERO_COM_SERVER_REGISTRY = exports.ZERO_COM_CLIENT_SEND = void 0;
+exports.ZERO_COM_CLIENT_SEND = 'ZERO_COM_CLIENT_SEND';
+exports.ZERO_COM_SERVER_REGISTRY = 'ZERO_COM_SERVER_REGISTRY';
+const formatFuncIdName = (funcName, path, line) => {
+    return `${funcName}@${path}:${line}`;
+};
+exports.formatFuncIdName = formatFuncIdName;

package/lib/common.ts

@@ -0,0 +1,14 @@
+export type Options = {
+  development?: boolean,
+  patterns: {
+    client: string,
+    server: string,
+  }
+}
+
+export const ZERO_COM_CLIENT_SEND = 'ZERO_COM_CLIENT_SEND'
+export const ZERO_COM_SERVER_REGISTRY = 'ZERO_COM_SERVER_REGISTRY'
+
+export const formatFuncIdName = (funcName: string, path: string, line: number): string => {
+  return `${funcName}@${path}:${line}`
+}