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

Co-authored-by: Mr Stone <pierre.evens16@gmail.com>

Author: evens-stone

CHANGELOG.md

@@ -13,16 +13,17 @@ All notable changes to the "Stone.js Node Cli Adapter" extension will be documen
 * implement error handler and update lifecycle hooks ([4ca37b2](https://github.com/stone-foundation/stone-js-node-cli-adapter/commit/4ca37b2b0c5fee68c5c4db257f745b084b64de79))
 * major internal restructuring and cleanup ([#39](https://github.com/stone-foundation/stone-js-node-cli-adapter/issues/39)) ([1828efe](https://github.com/stone-foundation/stone-js-node-cli-adapter/commit/1828efeb9754a95231051030a3437cc1a5b17700))
 
-## [0.0.21](https://github.com/stonemjs/node-cli-adapter/compare/v0.0.2...v0.0.21) (2024-12-07)
+## [0.0.21](https://github.com/stone-foundation/stone-js-node-cli-adapter/compare/v0.0.2...v0.0.21) (2024-12-07)
 
 
 ### Miscellaneous Chores
 
-* change the way commands are handled ([9cc05f0](https://github.com/stonemjs/node-cli-adapter/commit/9cc05f016f2877068f98d788dc5671f7a043d65c))
+* change the way commands are handled ([9cc05f0](https://github.com/stone-foundation/stone-js-node-cli-adapter/commit/9cc05f016f2877068f98d788dc5671f7a043d65c))
 
 ## 0.0.2 (2024-12-05)
 
 
 ### Features
 
-* implement node cli adapter ([30743f7](https://github.com/stonemjs/node-cli-adapter/commit/30743f7aaaae46db17826e810be4549d56406b6f))
+* implement node cli adapter ([30743f7](https://github.com/stone-foundation/stone-js-node-cli-adapter/commit/30743f7aaaae46db17826e810be4549d56406b6f))
+

package-lock.json

@@ -6,11 +6,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/stone-js/node-cli-adapter.git"
+    "url": "git+ssh://git@github.com/stone-foundation/stone-js-node-cli-adapter.git"
   },
   "homepage": "https://stonejs.dev",
   "bugs": {
-    "url": "https://github.com/stone-js/node-cli-adapter/issues"
+    "url": "https://github.com/stone-foundation/stone-js-node-cli-adapter/issues"
   },
   "keywords": [
     "cli",
@@ -31,12 +31,18 @@
   "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": {
-    "node": ">=18.0.0"
+    "node": ">=18.17.0"
   },
   "scripts": {
     "lint": "ts-standard src",

package.json

@@ -9,7 +9,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' }
     ],
@@ -29,7 +32,36 @@ export default [
     ]
   },
   {
-    input: 'dist/**/*.d.ts',
+    input: [
+      'src/constants.ts',
+      'src/errors/**/*.ts',
+      'src/browser/**/*.ts',
+      'src/blueprint/**/*.ts',
+      'src/decorators/Command.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']
+      }),
+      json(),
+      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

@@ -1,4 +1,4 @@
-sonar.projectName=Node CLI Adapter
+sonar.projectName=Stone.js - Node CLI Adapter
 sonar.organization=stone-foundation
 sonar.projectKey=stone-foundation_stone-js-node-cli-adapter
 sonar.coverage.exclusions=**/*.spec.ts, **/*.test.ts

sonar-project.properties

@@ -0,0 +1,40 @@
+import { classDecoratorLegacyWrapper, ClassType } from '@stone-js/core'
+import { NodeConsoleAdapterAdapterConfig } from '../../options/NodeConsoleAdapterBlueprint'
+
+/**
+ * Configuration options for the `NodeConsole` decorator.
+ * These options extend the default Node Cli adapter configuration.
+ */
+export interface NodeConsoleOptions extends Partial<NodeConsoleAdapterAdapterConfig> {}
+
+/**
+ * A Stone.js decorator that integrates the Node Cli Adapter with a class.
+ *
+ * This decorator modifies the class to seamlessly enable Node Cli as the
+ * execution environment for a Stone.js application. By applying this decorator,
+ * the class is automatically configured with the necessary blueprint for Node Cli.
+ *
+ * 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. Defaults to `ClassType`.
+ * @param options - Optional configuration to customize the Node Cli Adapter.
+ *
+ * @returns A class decorator that applies the Node Cli adapter configuration.
+ *
+ * @example
+ * ```typescript
+ * import { NodeConsole } from '@stone-js/node-cli-adapter';
+ *
+ * @NodeConsole({
+ *   alias: 'NodeConsole',
+ * })
+ * class App {
+ *   // Your application logic here
+ * }
+ * ```
+ */
+export const NodeConsole = <T extends ClassType = ClassType>(_options: NodeConsoleOptions = {}): ClassDecorator => {
+  return classDecoratorLegacyWrapper<T>((_target: T, _context: ClassDecoratorContext<T>): undefined => {})
+}

src/browser/decorators/NodeConsole.ts

@@ -0,0 +1,12 @@
+import { NodeConsoleAdapterBlueprint } from '../../options/NodeConsoleAdapterBlueprint'
+
+/**
+ * Default blueprint configuration for the Node Cli Adapter.
+ *
+ * This blueprint defines the initial configuration for the Node Cli adapter
+ * within the Stone.js framework. It includes:
+ * - An alias for the Node Cli platform (`Node_CLI_PLATFORM`).
+ * - A default resolver function (currently a placeholder).
+ * - Middleware, hooks, and state flags (`current`, `default`, `preferred`).
+ */
+export const nodeConsoleAdapterBlueprint: NodeConsoleAdapterBlueprint = { stone: { adapters: [] } }

src/browser/options/NodeConsoleAdapterBlueprint.ts

@@ -11,15 +11,15 @@ const mockOptions = {
 
 const createMockBlueprint = (isMatch: boolean, add = vi.fn()): IBlueprint => ({
   add,
-  is: vi.fn((_key: string, _value: string) => isMatch),
+  is: vi.fn((_key: string, _value: string) => isMatch)
 }) as unknown as IBlueprint
 
 const next = vi.fn()
 
 describe('defineCommand', () => {
   it('should define a functional command (no isFactory)', async () => {
     const handler = async (_event: IncomingEvent): Promise<void> => {}
-    
+
     const blueprint = createMockBlueprint(true)
     next.mockResolvedValueOnce(blueprint)
 

tests/blueprint/BlueprintUtils.spec.ts

@@ -1,8 +1,10 @@
 import { COMMAND_KEY } from '../../src/decorators/constants'
-import { addBlueprint, setClassMetadata } from '@stone-js/core'
 import { Command, CommandOptions } from '../../src/decorators/Command'
 import { NodeConsoleOptions, NodeConsole } from '../../src/decorators/NodeConsole'
 import { nodeConsoleAdapterBlueprint } from '../../src/options/NodeConsoleAdapterBlueprint'
+import { NodeConsole as BrowserNodeConsole } from '../../src/browser/decorators/NodeConsole'
+import { addBlueprint, classDecoratorLegacyWrapper, setClassMetadata } from '@stone-js/core'
+import { nodeConsoleAdapterBlueprint as baseNodeConsoleAdapterBlueprint } from '../../src/browser/options/NodeConsoleAdapterBlueprint'
 
 /* eslint-disable @typescript-eslint/no-extraneous-class */
 
@@ -13,18 +15,21 @@ vi.mock('@stone-js/core', async (importOriginal) => {
     ...actual,
     addBlueprint: vi.fn(() => {}),
     setClassMetadata: vi.fn(() => {}),
-    classDecoratorLegacyWrapper: (fn: Function) => {
+    classDecoratorLegacyWrapper: vi.fn((fn: Function) => {
       fn()
       return fn
-    }
+    })
   }
 })
 
 describe('NodeConsole', () => {
   it('should call addBlueprint with correct parameters', () => {
     const options: NodeConsoleOptions = nodeConsoleAdapterBlueprint.stone.adapters?.[0] ?? {}
     NodeConsole(options)(class {})
+    BrowserNodeConsole()(class {})
     expect(addBlueprint).toHaveBeenCalled()
+    expect(classDecoratorLegacyWrapper).toHaveBeenCalledTimes(2)
+    expect(addBlueprint).not.toHaveBeenCalledWith(expect.any(Function), expect.any(Object), baseNodeConsoleAdapterBlueprint)
   })
 
   it('should call addBlueprint with default options if none are provided', () => {

tests/decorators/decorators.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 CLI Adapter", // Project name used in the docs
   "includeVersion": false, // Optional: Include project version in the output