@firebolt-js/openrpc - npm Package Compare versions

Comparing version 1.8.0-next.2 to 2.0.0-next.2

CHANGELOG.md

@@ -0,1 +1,20 @@
+# [2.0.0-next.2](https://github.com/rdkcentral/firebolt-openrpc/compare/v2.0.0-next.1...v2.0.0-next.2) (2023-05-01)
+
+
+### Bug Fixes
+
+* **release:** Publish prereleases to NPM ([8947d81](https://github.com/rdkcentral/firebolt-openrpc/commit/8947d8120c51dfd05f23cf90475517b766fa1c4f))
+
+# [2.0.0-next.1](https://github.com/rdkcentral/firebolt-openrpc/compare/v1.8.0-next.2...v2.0.0-next.1) (2023-05-01)
+
+
+### Features
+
+* **readme:** Update Readme for 2.0 ([3537aa0](https://github.com/rdkcentral/firebolt-openrpc/commit/3537aa01f5ec15efa7f202edcf2cde8e5b57d74f))
+
+
+### BREAKING CHANGES
+
+* **readme:** tagging this commit because all of the others were squashed
+
 # [1.8.0-next.2](https://github.com/rdkcentral/firebolt-openrpc/compare/v1.8.0-next.1...v1.8.0-next.2) (2023-01-31)
@@ -2,0 +21,0 @@

package.json

 {
   "name": "@firebolt-js/openrpc",
-  "version": "1.8.0-next.2",
+  "version": "2.0.0-next.2",
   "description": "The Firebolt SDK Code & Doc Generator",
-  "main": "src/js/sdk/index.mjs",
+  "main": "languages/javascript/src/sdk.mjs",
   "type": "module",
@@ -15,8 +15,8 @@ "bin": {
     "build": "npm run validate && npm run build:docs && npm run build:sdk",
-    "validate": "node ./src/cli.mjs --task validate --source ./src --shared-schemas test/sharedSchemas && npm run build:openrpc && node ./src/cli.mjs --task validate --source ./build/sdk-open-rpc.json --shared-schemas test/sharedSchemas",
-    "build:openrpc": "node ./src/cli.mjs --task openrpc --source ./src --template ./src/template/openrpc/template.json --output ./build/sdk-open-rpc.json --shared-schemas test/sharedSchemas",
-    "build:sdk": "node ./src/cli.mjs --task sdk --source ./src/ --template ./src/local/template/js --output ./build/sdk/javascript/src --shared-schemas test/sharedSchemas",
-    "build:d": "node ./src/cli.mjs --task declarations --source ./src/ --output ./dist/lib/sdk.d.ts --shared-schemas src/schemas",
-    "build:docs": "node ./src/cli.mjs --task docs --source ./src/ --template ./src/template/markdown --output ./build/docs/markdown --shared-schemas test/sharedSchemas --as-path",
-    "build:wiki": "node ./src/cli.mjs --task docs --source ./src/ --template ./src/template/markdown --output ./build/docs/wiki --shared-schemas test/sharedSchemas",
+    "validate": "node ./src/cli.mjs validate --input ./test/openrpc --schemas test/schemas --transformations && npm run build:openrpc && node ./src/cli.mjs validate --input ./build/sdk-open-rpc.json",
+    "build:openrpc": "node ./src/cli.mjs openrpc --input ./test --template ./src/openrpc-template.json --output ./build/sdk-open-rpc.json --schemas test/schemas",
+    "build:sdk": "node ./src/cli.mjs sdk --input ./build/sdk-open-rpc.json --template ./test/sdk --output ./build/sdk/javascript/src --schemas test/schemas",
+    "build:d": "node ./src/cli.mjs declarations --input ./build/sdk-open-rpc.json --output ./dist/lib/sdk.d.ts --schemas src/schemas",
+    "build:docs": "node ./src/cli.mjs docs --input ./build/sdk-open-rpc.json --output ./build/docs/markdown --schemas test/schemas --as-path",
+    "build:wiki": "node ./src/cli.mjs docs --input ./build/sdk-open-rpc.json --output ./build/docs/wiki --schemas test/schemas",
     "dist": "npm run validate && npm run build:sdk && npm run build:docs && npm run test",
@@ -23,0 +23,0 @@ "prepare": "husky install"

README.md

 ---
-title: Firebolt OpenRPC Tools
+title: Firebolt OpenRPC 2.0
 ---
-# Firebolt OpenRPC Tools
+# Firebolt OpenRPC 2.0
 Tools to enable consistent Firebolt SDK and document generation.
 
-- [Firebolt OpenRPC Tools](#firebolt-openrpc-tools)
-  - [To Use](#to-use)
-  - [CLI Arguments](#cli-arguments)
-    - [SDK Generation](#sdk-generation)
-      - [Note on --static-modules](#note-on---static-modules)
-    - [Document Generation](#document-generation)
-      - [Note on --as-path](#note-on---as-path)
-    - [OpenRPC Generation](#openrpc-generation)
-    - [OpenRPC Validation](#openrpc-validation)
-  - [CLI Shorthands](#cli-shorthands)
+## Overview
+Version 2.0 of `firebolt-openrpc` has two major changes.
 
-## To Use
+- Support for slicing up an OpenRPC API into multiple SDK artifacts
+- Normalize most tasks to take a single OpenRPC document as input, rather than a directory full of "modules"
 
-  - First, `npm install`.
-  - Next, invoke the cli directly with `src/cli.js`. See below for arguments.
+### OpenRPC task
+The `openrpc` task takes a single OpenRPC document and "Fireboltizes" it, i.e. Interprets Firebolt method tags and inserts external Markdown descriptions via JSON-Schema $ref.
 
-Alternatively, you may install globally using `npm install -g @firebolt-js/openrpc`, which will install the cli and add it to your $PATH so it may be invoked with the `firebolt-openrpc` command.
+This task continues to support a directory of modules and will merge and Fireboltize them into a single file.
 
-Firebolt OpenRPC Tools require Node 16.
+### Slice task
+To support outputting multipel SDK's, there is a new `slice` task. This task takes a single OpenRPC document and slices it into separate OpenRPC documents based on a provided `sdk.config.json`, e.g.:
 
-## CLI Arguments
+```json
+{
+  "info": {
+    "title": "Firebolt Core SDK",
+  },
+  "methods": [
+    {
+      "module": "Lifecycle",
+      "use": [
+        "xrn:firebolt:capability:lifecycle:ready"
+        "xrn:firebolt:capability:lifecycle:ready"
+      ],
+      "manage": [],
+      "provide": [
+        "xrn:firebolt:capability:discovery:entityInfo",
+        "xrn:firebolt:capability:discovery:purchases"
+      ]
+    }
+  ]
+}
+```
 
-`--task`: Tell the tool what you want it to do. Options are:
+The `info.title` attribute is copied to the output, and each entry in the `methods` array is used to query methods from the input using module names and capabilities.
 
-  - `sdk`: Generate the SDK
-  - `docs`: Generate the docs
-  - `openrpc`: Generate the openrpc
-  - `validate` Validate the openrpc
+Any `info.x-` extension attributes will also be copied from the sdk.config.json into the output OpenRPC document.
 
-`--source`: The relative or absolute path to the folder or file that the task will use.
+Generally, this task is run using the output of the `openrpc` task as input, however, it's not required.
 
-`--template`: The relative or absolute path to the folder or file containing template resources for the task.
+Wildcards are supported in `module` as well as `use`, `manage`, and `provide`.
 
-`--output`: The relative or absolute path to the folder or file that will hold the task's generated output.
+## SDK, Declarations, and Docs
+These tasks all take a single OpenRPC document and generate their respective artifacts.
 
-`--as-path`: Used by the document generator. This is a toggle for generating content as files vs folders. More info below in [Document Generation](/#document-generation).
+They all have the same arguments and are all implemented using shared code for more consistency.
 
-`--static-modules`: String. Used by the SDK generator. "Static modules" are modules without an OpenRPC json document. More on this below.
+--input: The input OpenRPC document
+--output: The output location
+--template: An optional template directory for adding to and overriding the built in templates
 
-### SDK Generation
 
-Indicated by `--task sdk`. Generate the Firebolt SDKs from an OpenRPC spec. Currently, only the JavaScript SDK is supported.
-
-#### Note on --static-modules
-
-Static modules are modules without a corresponding OpenRPC json document. It will be included statically from the location supplied by the `--template` option. Listing your module in the `--static-modules` property ensures that it is properly exported by the SDK and wires up mock responses as well.
-
-### Document Generation
-
-Indicated by `--task docs`. Generate markdown docs from the OpenRPC spec.
-
-#### Note on --as-path
-
-When deploying docs to web servers, `--as-path` is generally used. For deploying to GitHub pages/wikis, do not use `--as-path`.
-
-This toggle will generate content as files vs folders. For exmaple, this:
-```
-/docs/Topic.md
-```
-vs
-```
-/docs/Topic/index.md
-```
-It affects the output of:
-
-  - file names
-  - relative links
-  - relative images
-
-### OpenRPC Generation
-
-Indicated by `--task openrpc`. Assembles a corpus of individual OpenRPC documents into a single OpenRPC document.
-
-#### Tags
+## Firebolt Method Tags
 * __event__ - When a method is tagged with this then it will be treated as an asynchronous event. The call to subscribe to the event will return a success reponse and then zero or more asynchronous responses with the same id. These responses correlate to the event happening. Events are documented in a different section of the module. The app can use the event not through a specific method call but by doing `Module.listen('eventName')`
@@ -92,17 +73,4 @@ * __exclude-from-sdk__ - When a method is tagged with this then no SDK method is generated. Instead, custom code for that method is used. This is often used for methods that have client code associated with it instead of just calling the Transport directly.
 
-### OpenRPC Validation
+## OpenRPC Validation
 
 Indicated by `--task validate`. Reads and validates a corpus of individual OpenRPC documents and validates the result of assembling them together into a single OpenRPC document.
-
-## CLI Shorthands
-
-Don't feel like typing? Use `-t` instead of `--task`. This table shows the mapping:
-
-| shorthand | command            |
-| --------- | ------------------ |
-| `-t`      | `--task`           |
-| `-s`      | `--source`         |
-| `-tm`     | `--template`       |
-| `-o`      | `--output`         |
-| `-ap`     | `--as-path`        |
-| `-sm`     | `--static-modules` |

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Fixed alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Number of package files

165

increased by117.11%

Worsened metrics

Total package byte prevSize

312027

decreased by-9.8%

Lines of code

6741

decreased by-13.69%

Number of lines in readme file

76

decreased by-29.63%

No dependency changes