feat: add browser-safe fallback entry with no-op modules for frontend compatibility (#28)

This pull request adds a browser-safe fallback entry with no-op modules to enable frontend compatibility while maintaining the Node.js HTTP adapter's functionality. Key changes include excluding browser-specific files from documentation generation, adding browser-specific blueprint and decorator implementations, and updating the rollup bundling and package exports configurations.

Author: evens-stone

README.md

@@ -172,7 +172,7 @@ The `@stone-js/node-http-adapter` brings your Stone.js application to life in th
 
 This package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture.
 
-Explore the full documentation: https://stonejs.dev
+Explore the full documentation: [https://stonejs.dev](https://stonejs.dev)
 
 ## API documentation
 

package-lock.json

@@ -30,8 +30,14 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "browser": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/browser.js"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
     }
   },
   "engines": {

package.json

@@ -8,7 +8,10 @@ import nodeExternals from 'rollup-plugin-node-externals'
 
 export default [
   {
-    input: 'src/**/*.ts',
+    input: [
+      'src/**/*.ts',
+      '!src/browser/**/*'
+    ],
     output: [
       { format: 'es', file: 'dist/index.js' }
     ],
@@ -27,7 +30,33 @@ export default [
     ]
   },
   {
-    input: 'dist/**/*.d.ts',
+    input: [
+      'src/constants.ts',
+      'src/errors/**/*.ts',
+      'src/browser/**/*.ts'
+    ],
+    output: [
+      { format: 'es', file: 'dist/browser.js' }
+    ],
+    plugins: [
+      multi(),
+      nodeExternals(), // Must always be before `nodeResolve()`.
+      nodeResolve({
+        extensions: ['.js', '.mjs', '.ts'],
+        exportConditions: ['node', 'import', 'require', 'default']
+      }),
+      typescript({
+        noEmitOnError: true,
+        tsconfig: './tsconfig.build.json',
+      }),
+      commonjs()
+    ]
+  },
+  {
+    input: [
+      'dist/**/*.d.ts',
+      '!dist/browser/**/*.d.ts'
+    ],
     output: [{ format: 'es' , file: 'dist/index.d.ts' }],
     plugins: [
       multi(),

rollup.config.mjs

@@ -0,0 +1,44 @@
+import { classDecoratorLegacyWrapper, ClassType } from '@stone-js/core'
+import { NodeHttpAdapterAdapterConfig } from '../../options/NodeHttpAdapterBlueprint'
+
+/**
+ * Interface for configuring the `NodeHttp` decorator.
+ *
+ * This interface extends `NodeHttpAdapterConfig` and allows partial customization
+ * of the Node.js HTTP adapter blueprint configuration.
+ */
+export interface NodeHttpOptions extends Partial<NodeHttpAdapterAdapterConfig> {}
+
+/**
+ * A class decorator for registering a Node.js HTTP adapter in the Stone.js framework.
+ *
+ * The decorator modifies the `nodeHttpAdapterBlueprint` by merging the provided options
+ * with the default configuration. It also registers the blueprint to the target class using
+ * the `addBlueprint` utility.
+ *
+ * NB: This decorator is stubbed for browser environments compatibility and does not
+ * perform any actual functionality in the browser. It is intended for use in Node.js environments
+ * where the Node.js HTTP adapter is applicable.
+ *
+ * @template T - The type of the class being decorated, defaulting to `ClassType`.
+ *
+ * @param options - An object containing configuration options for the Node.js HTTP adapter.
+ *
+ * @returns A class decorator function.
+ *
+ * @example
+ * ```typescript
+ * import { NodeHttp } from '@stone-js/node-http';
+ *
+ * @NodeHttp({
+ *   url: 'http://localhost:3000',
+ *   default: true,
+ * })
+ * class MyHttpService {
+ *   // Service implementation
+ * }
+ * ```
+ */
+export const NodeHttp = <T extends ClassType = ClassType>(_options: NodeHttpOptions = {}): ClassDecorator => {
+  return classDecoratorLegacyWrapper<T>((_target: T, _context: ClassDecoratorContext<T>): undefined => {})
+}

src/browser/decorators/NodeHttp.ts

@@ -0,0 +1,10 @@
+import { NodeHttpAdapterBlueprint } from '../../options/NodeHttpAdapterBlueprint'
+
+/**
+ * Node HTTP adapter options.
+ *
+ * This object defines the configuration for the Node HTTP adapter.
+ *
+ * NB: This is a stub for browser environments and does not perform any actual functionality in the browser.
+ */
+export const nodeHttpAdapterBlueprint: NodeHttpAdapterBlueprint = { stone: { http: {}, adapters: [] } }

src/browser/options/NodeHttpAdapterBlueprint.ts

@@ -74,7 +74,7 @@ describe('NodeHttpAdapter', () => {
       }),
       get: vi.fn((key, fallback) => blueprint.values[key] ?? fallback),
       has: vi.fn((key) => key in blueprint.values),
-      getAll: vi.fn(() => blueprint.values),
+      getAll: vi.fn(() => blueprint.values)
     }
     blueprint.set('stone.logger.resolver', () => ({
       info: vi.fn(),

tests/NodeHttpAdapter.spec.ts

@@ -1,7 +1,8 @@
-import { Mock } from 'vitest'
-import { addBlueprint } from '@stone-js/core'
 import { NodeHttp, NodeHttpOptions } from '../../src/decorators/NodeHttp'
+import { addBlueprint, classDecoratorLegacyWrapper } from '@stone-js/core'
+import { NodeHttp as BrowserNodeHttp } from '../../src/browser/decorators/NodeHttp'
 import { nodeHttpAdapterBlueprint } from '../../src/options/NodeHttpAdapterBlueprint'
+import { nodeHttpAdapterBlueprint as browserNodeHttpAdapterBlueprint } from '../../src/browser/options/NodeHttpAdapterBlueprint'
 
 /* eslint-disable @typescript-eslint/no-extraneous-class */
 
@@ -11,19 +12,22 @@ vi.mock('@stone-js/core', async (importOriginal) => {
   return {
     ...actual,
     addBlueprint: vi.fn(() => {}),
-    classDecoratorLegacyWrapper: (fn: Function) => {
+    classDecoratorLegacyWrapper: vi.fn((fn: Function) => {
       fn()
       return fn
-    }
+    })
   }
 })
 
 describe('NodeHttp', () => {
   it('should call addBlueprint with correct parameters', () => {
-    (addBlueprint as Mock).mockReturnValueOnce(() => {})
+    vi.mocked(addBlueprint).mockImplementation(() => {})
     const options: NodeHttpOptions = nodeHttpAdapterBlueprint.stone.adapters[0]
     NodeHttp(options)(class {})
+    BrowserNodeHttp()(class {})
     expect(addBlueprint).toHaveBeenCalled()
+    expect(classDecoratorLegacyWrapper).toHaveBeenCalledTimes(2)
+    expect(addBlueprint).not.toHaveBeenCalledWith(expect.any(Function), expect.any(Object), browserNodeHttpAdapterBlueprint)
   })
 
   it('should call addBlueprint with default options if none are provided', () => {

tests/decorators/NodeHttp.spec.ts

@@ -8,7 +8,7 @@ const blueprint: any = {
   }),
   get: vi.fn((key, fallback) => blueprint.values[key] ?? fallback),
   has: vi.fn((key) => key in blueprint.values),
-  getAll: vi.fn(() => blueprint.values),
+  getAll: vi.fn(() => blueprint.values)
 }
 
 describe('NodeHttpAdapter Resolvers', () => {

tests/resolvers.spec.ts

@@ -1,5 +1,6 @@
 {
   "entryPoints": ["src/**/*.ts"], // Entry point for your project, change accordingly
+  "exclude": ["src/browser/**/*"], // Exclude browser-specific files if any
   "out": "docs", // Output directory for the generated documentation
   "name": "Node HTTP Adapter", // Project name used in the docs
   "includeVersion": false, // Optional: Include project version in the output