edge-functions 1.0.0

package/.babelrc

@@ -0,0 +1,13 @@
+{
+  "presets": [
+    [
+      "@babel/preset-env",
+      {
+        "targets": {
+          "node": "current"
+        }
+      }
+    ]
+  ],
+  "plugins": ["babel-plugin-transform-import-meta"]
+}

package/.eslintignore

@@ -0,0 +1,3 @@
+lib/presets/custom/*/handler.js
+lib/presets/custom/*/worker.js
+examples/simple-js-esm/index.js

package/.eslintrc.json

@@ -0,0 +1,42 @@
+{
+  "env": {
+    "browser": true,
+    "es2021": true,
+    "jest/globals": true
+  },
+  "plugins": ["jsdoc", "jest"],
+  "extends": [
+    "airbnb-base",
+    "plugin:jsdoc/recommended",
+    "plugin:jest/recommended"
+  ],
+  "overrides": [],
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "settings": {
+    "import/resolver": {
+      "alias": {
+        "map": [
+          ["#root/*", "./"],
+          ["#lib/*", "./lib"],
+          ["#utils", "./lib/utils/index.js"],
+          ["#polyfills", "./lib/build/polyfills/index.js"],
+          ["#build", "./lib/build/dispatcher/index.js"],
+          ["#bundlers", "./lib/build/bundlers/index.js"],
+          ["#notations/*", "./lib/notations"],
+          ["#env", "./lib/env/index.js"],
+          ["#platform", "./lib/platform/index.js"],
+          ["#constants", "./lib/constants/index.js"],
+          ["#edge", "./lib/platform/edgehooks/index.js"]
+        ],
+        "extensions": [".js", ".json"]
+      }
+    }
+  },
+  "rules": {
+    "import/extensions": ["error", "always"],
+    "no-console": "off"
+  }
+}

package/.github/workflows/major.yml

@@ -0,0 +1,28 @@
+name: Release (Major)
+
+on:
+  push:
+    branches:
+      - main
+jobs:
+  publish-release:
+    strategy:
+      matrix:
+        node-version: [19.x]
+        os: [ubuntu-latest, macos-latest]
+
+    name: Release - ${{ matrix.os }} - Node v${{ matrix.node-version }}
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Node ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Installing dependencies
+        run: yarn install
+      - name: Create Release
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release -e ./releaserc.json

package/.github/workflows/minor.yml

@@ -0,0 +1,31 @@
+name: Release (Minor/Patch)
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - dev
+jobs:
+  publish-release:
+    strategy:
+      matrix:
+        node-version: [19.x]
+        os: [ubuntu-latest]
+
+    name: Release - ${{ matrix.os }} - Node v${{ matrix.node-version }}
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Node ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Installing dependencies
+        run: yarn install
+      - name: Create Release
+        run: npx semantic-release -e ./releaserc.json
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        

package/.vscode/settings.json

@@ -0,0 +1,20 @@
+{
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  },
+  "editor.formatOnSave": true,
+  "[javascript]": {
+    "editor.formatOnSave": true
+  },
+  "[javascriptreact]": {
+    "editor.formatOnSave": true
+  },
+  "[typescript]": {
+    "editor.formatOnSave": true
+  },
+  "[typescriptreact]": {
+    "editor.formatOnSave": true
+  },
+  "prettier.eslintIntegration": true,
+  "docwriter.style": "JSDoc"
+}

package/CODEOWNERS

@@ -0,0 +1,2 @@
+* @jotanarciso
+* @MagnunAVFAzion

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the Azion team at [support@azion.com](mailto:support@azion.com). All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

package/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing
+
+First off, thanks for taking the time to contribute!
+
+All types of contributions are encouraged and valued. See the Table of Contents for different ways to help and details about how this project handles them. 🎉
+
+## Table of Contents
+- [Code of Conduct](#code-of-conduct)
+- [I Have a Question](#i-have-a-question)
+- [I Want To Contribute](#i-want-to-contribute)
+  - [Reporting Bugs](#reporting-bugs)
+  - [Suggesting Enhancements](#suggesting-enhancements)
+  - [Your First Code Contribution](#your-first-code-contribution)
+
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+By participating, you are expected to uphold this code.
+
+## I Have a Question
+
+> If you want to ask a question, we assume that you have read the available [Documentation](README.md).
+
+Before you ask a question, it is best to search for existing [Issues](https://github.com/aziontech/vulcan/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue.
+
+If you then still feel the need to ask a question and need clarification, we recommend the following:
+
+- Open an [Issue](https://github.com/aziontech/vulcan/issues/new).
+- Provide as much context as you can about what you're running into.
+
+We will then take care of the issue as soon as possible.
+
+## I Want To Contribute
+
+> ### Legal Notice
+> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content, and that the content you contribute may be provided under the project license.
+
+### Reporting Bugs
+
+#### Before Submitting a Bug Report
+
+A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information, and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.
+
+- Make sure that you are using the latest version.
+- Determine if your bug is really a bug and not an error on your side e.g. using incompatible binary to your OS/Platform (Make sure that you have read the [documentation](README.md).
+- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/aziontech/vulcan/issues?q=label%3Abug).
+- Collect information about the bug:
+  - Stack trace
+  - OS, Platform and Version (Windows, Linux, macOS, x86, ARM)
+  - Golang version, runtime environment or what seems relevant.
+  - Possibly your input and the output
+  - Can you reliably reproduce the issue? And can you also reproduce it with older versions?
+
+We use GitHub issues to track bugs and errors. If you run into an issue with the project:
+
+- Open an [Issue](https://github.com/aziontech/vulcan/issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.)
+- Explain the behavior you would expect and the actual behavior.
+- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case.
+- Provide the information you collected in the previous section.
+
+### Suggesting Enhancements
+
+This section guides you through submitting an enhancement suggestion for Cells Site Tempalte, **including completely new features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.
+
+#### Before Submitting an Enhancement
+
+- Make sure that you are using the latest version.
+- Perform a [search](https://github.com/aziontech/vulcan/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
+- If your enhancement is nontrivial,
+please open an [Issue](https://github.com/aziontech/vulcan/issues/new) to discuss the
+idea and implementation strategy before submitting a PR.
+
+#### How Do I Submit a Good Enhancement Suggestion?
+
+Enhancement suggestions are tracked as [GitHub issues](https://github.com/aziontech/vulcan/issues).
+
+- Use a **clear and descriptive title** for the issue to identify the suggestion.
+- Provide a **step-by-step description of the suggested enhancement** in as many details as possible.
+- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point you can also tell which alternatives do not work for you.
+- You may want to **include screenshots and animated GIFs** which help you demonstrate the steps or point out the part which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. <!-- this should only be included if the project has a GUI -->
+- **Explain why this enhancement would be useful** to most Cells Site Template users. You may also want to point out the other projects that solved it better and which could serve as inspiration.
+
+### Your First Code Contribution
+
+1. Fork the repo
+2. Clone your forked repo
+3. Commit the changes you’ve developed on your fork
+4. If everything looks good, create a pull request on the base repo with your changes.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Azion Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+
+# Vulcan - Forging The Edge
+
+Vulcan is a powerful tool designed to streamline the development and deployment of JavaScript applications and frameworks. This powerful utility automates polyfills for Edge Computing, significantly simplifying the process of creating Workers, particularly for the Azion platform.
+
+One of the key highlights of Vulcan is its ability to establish an intuitive and efficient protocol for facilitating the creation of presets. This makes customization and adaptation to specific project needs even more accessible, providing developers with the necessary flexibility to optimize their applications effectively and efficiently.
+
+## Quick Installation
+
+For those who just want to use Vulcan in their project without contributing to the development, you can install it directly from npm.
+
+```shell
+npm install edge-functions
+```
+
+or if you prefer yarn:
+
+```shell
+yarn add edge-functions
+```
+
+## Getting Started for Development
+
+Follow these steps to start using Vulcan:
+
+1. Clone the repository: Clone the Vulcan repository from GitHub to your local machine.
+
+   ```shell
+   git clone https://github.com/aziontech/vulcan.git
+   ```
+
+2. Installation: Navigate to the cloned Vulcan directory and install the required dependencies.
+
+   ```shell
+   cd vulcan
+   npm install
+   ```
+3. Install the Vulcan CLI globally, which allows you to use it as a command-line tool from anywhere in your system.
+
+   ```shell
+   npm install -g
+   ```
+
+   This command sets up the necessary project structure and configuration files for Vulcan.
+
+5. Start developing: Once the project is set up, you can start developing your JavaScript applications or frameworks using the power of Vulcan. Leverage the automated polyfills, Worker creation assistance, and other features provided by Vulcan to enhance your development workflow.
+
+
+## Docs
+* [Overview](docs/overview.md)
+* [Presets](docs/presets.md)
+
+## Contributing
+Check the [Contributing doc](CONTRIBUTING.md).
+
+## Code of Conduct
+Check the [Code of Conduct ](CODE_OF_CONDUCT.md).
+
+## License
+[MIT](LICENSE.md)

package/aliases.js

@@ -0,0 +1,13 @@
+export default [
+  ['#root/*', './'],
+  ['#lib/*', './lib'],
+  ['#utils', './lib/utils/index.js'],
+  ['#polyfills', './lib/build/polyfills/index.js'],
+  ['#build', './lib/build/dispatcher/index.js'],
+  ['#bundlers', './lib/build/bundlers/index.js'],
+  ['#notations/*', './lib/notations'],
+  ['#env', './lib/env/index.js'],
+  ['#platform', './lib/platform/index.js'],
+  ['#constants', './lib/constants/index.js'],
+  ['#edge', './lib/platform/edgehooks/index.js'],
+];

package/docs/overview.md

@@ -0,0 +1,36 @@
+# Overview
+
+## Build Pipeline
+```mermaid
+flowchart LR
+
+A[Trigger] -->|args| B(Dispatcher)
+B --> C(Prebuild)
+C -->|args| D(Common Build)
+D --> E[Artifacts]
+```
+
+### Trigger
+An external call to run a build.
+
+### Dispatcher
+* Receive build options(args);
+* Select which build process to run;
+* Load necessary template files and import correct modules (prebuild and configs);
+
+### Prebuild
+Custom prebuild module that runs actions to generate entrypoint and necessary files.
+
+The user is free to run any action in this step. All actions must be called in a exported `main` function.
+
+### Common Build
+Module that runs azion common build.
+
+Polyfills can be used to generate the worker(s) file(s).
+
+Some configs can be passed to the builder but if user tries to override `azion worker configs` this passed configs will be ignored.
+
+### Artifacts
+Files generated to run in azion structure:
+* js worker(s);
+* Storage assets files;

package/docs/presets.md

@@ -0,0 +1,115 @@
+
+
+# Documentation: Presets
+Vulcan is an extensible platform that allows you to easily create new presets for frameworks and libraries to run on the Edge. This documentation will describe the fundamental structure and how to add your own preset.
+
+
+## Presets Structure
+
+To add a new preset, you need to create appropriate folders in two directories: `presets/default` or `presets/custom`. The folder representing your framework or library will automatically be included in the preset listings. Each preset has two modes, represented by folders of the same name: `compute` and `deliver`.
+
+
+
+https://github.com/aziontech/vulcan/assets/12740219/06edb9a0-26cd-4055-bd2e-d400b6a06f3c
+
+
+
+
+- Compute: This holds configurations for frameworks that use computation on the Edge (Front-End SSR or Back-End).
+- Deliver: This holds configurations for frameworks that merely handle requests on the Edge to deliver static files (routing, but not execute.
+
+
+
+Each preset is made up of three primary files: `config.js`, `prebuild.js`, and `handler.js`.
+
+![file-1](https://github.com/aziontech/vulcan/assets/12740219/4ba25280-0463-4ecf-9ad6-f9066444f483)
+
+
+
+1.  `config.js`: This file is responsible for extending the Vulcan build (Edge build) and allows the inclusion of polyfills, plugins, and other necessities. By default, you don't need to make alterations.
+    
+2.  `prebuild.js`: This file allows you to add the build and adaptation stages of the framework. This stage is executed before Vulcan's Forging process (which adapts it for the Edge). Here, you have access to the `#utils` domain, which provides methods and an interface for you to manipulate the build of the framework or library.
+
+	Commonly used methods include:
+	-	 `exec`: An abstraction for `child_process:spawn`. You send the command, the scope (which will be shown in the log, default is 'process'), and the verbose flag to display or not the resultant logs.
+
+	- `getPackageManager`: This method returns the package manager relative to the user's project (can be yarn, npm, or pnpm).
+
+	- `copyDirectory`: This function is used to copy the resulting static files from the framework build to the local Edge environment (.edge/statics).
+
+	- `feedback`: This interface is used to display messages during the process, if necessary, or in case of error.
+
+
+4.  `handler.js`: This function is executed on the Edge. During the Forging stage, it is inserted within the provider's worker (presets/providers). Here, you have access to edgehooks (import from #edge), which are ready-made snippets of code to add to your handler.
+
+	Current edgehooks include:
+
+	- mountSPA: This function takes the request and sets up the routing for a standard SPA, ready to redirect requests to index.html and also route the static files.
+
+	- mountSSG: This function takes the request and sets up routes according to the SSG structure.
+	
+	 - ErrorHTML: This edgehook provides a return of an HTML template showing the error and the description passed as a parameter. You can pass the captured error as the third parameter, and it will be displayed on the screen (it's a good way to debug).
+
+#	How to add a new preset
+
+Here's a step-by-step guide on how to add a new preset in Vulcan:
+
+1.  ## **Create a folder inside `./lib/presets/custom`:**
+   https://github.com/aziontech/vulcan/assets/12740219/abb1b2cc-5f74-473d-b731-c0b7157cb95e
+
+  -   The name of this folder should represent the name of your framework or library.
+      
+-   Inside this folder, you should create another folder named `compute` or `deliver`, depending on the operation mode you want. If the folder is created directly at the root, it will be interpreted as being of the `deliver` type by default.
+        
+ -   **Compute**: This mode should be used when there is effectively a computation being performed at the Edge.
+
+-   **Deliver**: This mode should be used when you intend to use the worker only for routing requests and delivering static files that will be computed on the client side.
+        
+3.  ## **Create the following files in your preset's folder:**
+    
+    ##  handler.js
+    This file contains the code that is executed within the worker in the edge function. Essentially, it is the code that runs directly on the edge. In the context of the `deliver` mode, this may simply act as a router. However, in cases where computation is needed, it can be designed to perform more complex tasks. Remember, the capabilities of your handler.js are dependent on your use case and the mode of operation you've chosen for your preset.
+	
+	  #### For the cases involving static (deliver) frameworks, here's what you can do:
+	- For Single Page Application (SPA) types: 
+		Consider copying the preset handler similar to Vue. This utilizes the 	`mountSPA` hook which sets up the routing for your SPA effectively.
+		
+	- For Static Site Generator (SSG) projects: 
+	If you have a project that generates multiple HTML files, take a look at how the Next.js project handles this. They use the `mountSSG` hook, which sets up static routing for all the generated HTML pages.	
+
+	**Note**: Remember, these are just examples and can serve as a starting point for your own custom preset. Adjust and extend them as necessary to fit your project's specific needs.
+      
+	## config.js
+	   This file serves as an extension to the edge build. It enables the inclusion of polyfills, plugins, or any other procedures that relate to the build process executed on the edge. Although it is editable, we strongly advise against making changes to this file unless absolutely necessary. It's designed to ensure optimal operation, and modifications should be undertaken with careful consideration.
+	   
+	   ## prebuild.js
+	   In this file, you should adapt the native build process of your framework or library. Usually, in the case of *deliver* presets, this file will be used to ensure that the generated static artifacts are placed in the *.edge/statics/* directory.
+      #### React (deliver) Example:
+
+![prebuild](https://github.com/aziontech/vulcan/assets/12740219/85adc374-220b-4003-8c3e-6ec5b06a483f)
+
+
+
+   **Note**: The use of `compute` type presets is still under development and does not have many examples available. We currently support build/import resolution for pure JavaScript code (or with polyfills), as shown in the `./examples/simple-js-esm` example.
+
+
+
+3.  ## **Test your preset:**
+   After setting up your preset, you can test it using Vulcan's build command. Depending on the mode of your preset, run one of the following commands in your terminal:
+
+
+
+https://github.com/aziontech/vulcan/assets/12740219/7033d37a-30ee-4098-8fe5-bbfca536591d
+
+
+
+
+For `compute` mode:
+
+    vulcan build --preset <name> --mode compute
+
+For `deliver` mode:
+
+    vulcan build --preset <name> --mode deliver
+
+Replace `<name>` with the name of your preset. This will initiate Vulcan's build process for your preset, allowing you to verify its functionality.

package/examples/angular-static/.editorconfig

@@ -0,0 +1,16 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/examples/angular-static/README.md

@@ -0,0 +1,27 @@
+# Angular Static
+
+This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 16.1.3.
+
+## Development server
+
+Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
+
+## Code scaffolding
+
+Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
+
+## Build
+
+Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
+
+## Running unit tests
+
+Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
+
+## Running end-to-end tests
+
+Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
+
+## Further help
+
+To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.