Merge pull request #39 from podium-lib/podium_v5

Podium v5

README.md

@@ -1,41 +1,30 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 
 ```
-$ yarn
+$ npm install
 ```
 
 ### Local Development
 
 ```
-$ yarn start
+$ npm start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ### Build
 
 ```
-$ yarn build
+$ npm run build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
 ### Deployment
 
-Using SSH:
-
-```
-$ USE_SSH=true yarn deploy
-```
-
-Not using SSH:
-
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+The site is automatically deployed to GitHub pages whenever changes are made to the source branch.
+Create a new branch with your changes and submit a PR against `source`. Once merged, your changes will be visible at https://podium-lib.io/

blog/2023-12-01-version-5.0.0.md

@@ -0,0 +1,157 @@
+---
+slug: version-5.0.0
+title: Version 5.0.0
+authors: richard
+tags: [podium, version, release]
+---
+
+The Podium team is pleased to annouce and make available the release of version 5.0.0 of Podium. 🥳 🎉
+
+This is a breaking change from the v4.x line but since most of the changes are either under the hood or the removal of deprecations, upgrading, except in a couple notible exceptions,
+should be pretty simple for most users and may require no changes at all.
+
+<!--truncate-->
+
+### Breaking changes
+
+There are a couple breaking changes in this release that will need to be addressed if they affect you.
+
+#### 1. The Podium codebase has been converted to ESM and no longer supports common JS.
+
+While you can still mix and match podlets and layouts on Podium version 4 and 5, you will need to convert your codebase to ESM before upgrading to Podium version 5 podlets and layouts.
+See [this post](https://tsmx.net/convert-existing-nodejs-project-from-commonjs-to-esm/) for a guide if you need one.
+
+#### 2. An instance of HttpIncoming must now be passed as the first argument to the Podium client 
+
+n.b. If you are currently not seeing any deprecation warnings in your Podium version 4 apps, this won't affect you.
+
+The `.fetch()` and `.stream()` methods. Usage of the fetch/stream methods without passing in HttpIncoming was deprecated a long while ago.
+
+In Podium version 4, the following was acceptable but will now throw with version 5.
+```js
+const header = layout.client.register({...});
+
+app.get("/", (req, res) => {
+  await header.fetch();
+});
+```
+
+In Podium version 5, you need to ensure you pass in an HttpIncoming object like so:
+```js
+const header = layout.client.register({...});
+
+app.get("/", (req, res) => {
+  const incoming = res.locals.podium;
+  await header.fetch(incoming);
+});
+```
+
+#### 3. Removal of deprecated Podium v3 compatibility in the manifest file and codebase. 
+
+n.b. If you are currently not seeing any deprecation warnings in your Podium version 4 apps, this won't affect you.
+
+The `assets` key and its sub keys `js` and `css` have been removed from the manifest file.
+
+Previously through all of Podium version 4, we maintained both the `assets` key and `js` and `css` keys for backwards compatibility with Podium version 3.
+The value for `assets.js` would always be the same as for `js` and the value for `assets.css` would always be the same as `css`.
+
+Like so:
+
+```json
+{
+  "assets": { "js": [], "css": [] },
+  "js": [],
+  "css": []
+}
+```
+
+With Podium version 5, we've dropped the `assets` key (and therefore compatibility with Podium version 3) so that the manifest file will now look like:
+
+```json
+{
+  "js": [],
+  "css": []
+}
+```
+
+#### 4. Support for Node v10 and lower has been intentionally dropped and we are now actively only testing against Node v16 and higher.
+
+Releases are now made against Node v20 and we actively run test suites against Node version 16 and up. Versions 12 and 14 should work but we make no guarantees.
+
+#### 5. .js and .css methods on the Podium layout and Podium podlet modules, which are used to set assets, no longer return a value
+
+n.b. If you are currently not seeing any deprecation warnings in your Podium version 4 apps, this won't affect you.
+
+The podlet and layout `.js` and `.css` methods used to return a value. This was deprecated a long ways back and has now been removed.
+
+```js
+const result = layout.js()
+// result is null
+const result = podlet.js()
+// result is null
+```
+
+#### 6. Previously deprecated Podium client `change` and `dispose` events removed.
+
+These client registry events, emitted from the Podium client, were previously deprecated and have now been removed.
+You most likely aren't, but check your codebase to ensure you aren't relying on these events.
+
+### Other notable changes
+
+None of the following changes require any action when upgrading.
+
+#### 1. Under the hood, the Podium client request module has been replaced.
+
+The [Request](https://www.npmjs.com/package/request) module is deprecated and we've opted to replace it with [Undici](https://www.npmjs.com/package/undici), a fast modern alternative.
+
+#### 2. The podlet manifest file now supports an array of proxy endpoints instead of just an object.
+
+Previously, proxy entries in the podlet manifest were defined as an object and looked like this:
+
+```json
+{
+  "proxy": {
+    "one": "/target/path/one",
+    "two": "/target/path/two",
+  }
+}
+```
+
+This has been changed to support an array syntax in which multiple proxies definitions can be added
+
+```json
+{
+  "proxy": [
+    { "name": "one": "target": "/target/path/one" },
+    { "name": "two": "target": "/target/path/two" },
+  ]
+}
+```
+
+The object syntax has been preserved for backwards compatibility.
+
+#### 3. Added prettier printing of Podium client responses when using console.log
+
+Log output used to look like:
+
+```js
+PodiumClientResponse {
+  [Symbol(podium:client:response:redirect)]: '',
+  [Symbol(podium:client:response:content)]: '',
+  [Symbol(podium:client:response:headers)]: {},
+  [Symbol(podium:client:response:css)]: [],
+  [Symbol(podium:client:response:js)]: []
+}
+```
+
+But now looks like:
+
+```js
+{
+  redirect: '',
+  content: '',
+  headers: {},
+  css: [],
+  js: []
+}
+```

blog/authors.yml

@@ -1,24 +1,11 @@
-endi:
-  name: Endilie Yacop Sucipto
-  title: Maintainer of Docusaurus
-  url: https://github.com/endiliey
-  image_url: https://github.com/endiliey.png
-
-yangshun:
-  name: Yangshun Tay
-  title: Front End Engineer @ Facebook
-  url: https://github.com/yangshun
-  image_url: https://github.com/yangshun.png
-
-slorber:
-  name: Sébastien Lorber
-  title: Docusaurus maintainer
-  url: https://sebastienlorber.com
-  image_url: https://github.com/slorber.png
-
 trygve:
   name: Trygve Lie
   title: Lead maintainer
   url: https://github.com/trygve-lie/
   image_url: https://github.com/trygve-lie.png
 
+richard:
+  name: Richard Walker
+  title: Maintainer
+  url: https://github.com/digitalsadhu/
+  image_url: https://github.com/digitalsadhu.png

docs/api/document.md

@@ -219,7 +219,7 @@ or [`.buildScriptElement()`](https://github.com/podium-lib/utils#buildscriptelem
 methods found in the `@podium/utils` package:
 
 ```js
-const utils = require('@podium/utils');
+import utils from '@podium/utils';
 
 [ ... ]
 

docs/api/getting_started.md

@@ -45,8 +45,8 @@ Example of setting up a podlet server in all HTTP frameworks supported by the Po
 <TabItem value="express" label="Express">
 
 ```js
-const express = require('express');
-const Podlet = require('@podium/podlet');
+import express from 'express';
+import Podlet from '@podium/podlet';
 
 const app = express();
 
@@ -77,9 +77,9 @@ app.listen(7100);
 <TabItem value="hapi" label="Hapi">
 
 ```js
-const HapiPodlet = require('@podium/hapi-podlet');
-const Podlet = require('@podium/podlet');
-const Hapi = require('hapi');
+import HapiPodlet from '@podium/hapi-podlet';
+import Podlet from '@podium/podlet';
+import Hapi from 'hapi';
 
 const app = Hapi.Server({
     host: 'localhost',
@@ -122,9 +122,9 @@ app.start();
 <TabItem value="fastify" label="Fastify">
 
 ```js
-const fastifyPodlet = require('@podium/fastify-podlet');
-const fastify = require('fastify');
-const Podlet = require('@podium/podlet');
+import fastifyPodlet from '@podium/fastify-podlet';
+import fastify from 'fastify';
+import Podlet from '@podium/podlet';
 
 const app = fastify();
 
@@ -165,9 +165,9 @@ start();
 <TabItem value="http" label="HTTP">
 
 ```js
-const { HttpIncoming } = require('@podium/utils');
-const Podlet = require('@podium/podlet');
-const http = require('http');
+import { HttpIncoming } from '@podium/utils';
+import Podlet from '@podium/podlet';
+import http from 'http';
 
 const podlet = new Podlet({
     name: 'myPodlet',