diff --git a/docs/addons/creating-addons.md b/docs/addons/creating-addons.md deleted file mode 100644 index 969143ff..00000000 --- a/docs/addons/creating-addons.md +++ /dev/null @@ -1,56 +0,0 @@ -# Creating Add-on's - -One of the core tenets of Adze is to **not do too much**. This means that the core functionality of Adze is to provide the user with the ability to have control over their logs, how they are shaped, and to be able to listen to their logs and do with the log data as they please. Anything resembling transporting log data to files, API's, or databases is purposefully omitted from the core. However, because of Adze [log listeners](../guide/globalstore-concepts.md#listeners), there is opportunity for add-on packages to provide simple solutions for handling log data transports and various other solutions. - -## Best Practices - -When creating add-on's for Adze your primary interface should be wrapping a [log listener](../guide/globalstore-concepts.md#listeners). By wrapping a log listener you can intercept the [log data](../guide/data.md#label-data-object) and [log render](../guide/data.md#log-render) and act upon it. To do this, your add-on should export a function that takes a callback function as a parameter and then executes that callback function at a later time and forwards the **log data** and **log render** to it as parameters. Let's take a look at an example. - -## Add-on Example - -Let's first create our wrapper function that our add-on will expose. - -#### my-addon.js - -```javascript -// We'll create an exported function that takes a callback as a parameter -// and sets a default to an empty anonymous function. -export function MyAddon(cb = () => {}) { - // Our wrapper will return a log listener callback function that - // accepts log data and a log render. - return (data, render) => { - // Do stuff with the log data and log render - - // Then make sure to execute the user specified callback before finishing. - cb(data, render); - }; -} -``` - -#### my-app.js - -```javascript -import { adze, createGlobalStore } from 'adze'; - -// Now, in our app, we'll import the wrapper function we created above. -import { MyAddon } from './my-addon.js'; - -const globalStore = createGlobalStore(); - -// Now, to use the add-on, I'll wrap my log listener callback function with -// the MyAddon wrapper. We'll target all logs to use this add-on. -globalStore.addListener( - '*', - MyAddon((data, render) => { - // Do normal log listener stuff here... - }) -); - -// Or alternatively, since we specified an empty anonymous function -// as the default parameter of our add-on, we can call it empty. -globalStore.addListener('*', MyAddon()); - -adze().log('This log will be intercepted by our add-on!'); -``` - -Following the pattern above allows your add-on to operate on log data and log renders while also giving control to the end-user over which logs it wants your add-on to target. diff --git a/docs/addons/official-addons.md b/docs/addons/official-addons.md deleted file mode 100644 index 3ca975e8..00000000 --- a/docs/addons/official-addons.md +++ /dev/null @@ -1,27 +0,0 @@ - | diff --git a/docs/get-started.md b/docs/get-started.md deleted file mode 100644 index 79c756fc..00000000 --- a/docs/get-started.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -layout: Home -home: true -heroImage: /logo.svg -heroText: A Library for Shaping Your Logs -tagline: Open the dev console for a demo -actionText: Quick Start → -actionLink: /guide/ -features: - - title: Chainable API - image: /chainsaw.svg - imageId: chainsaw - details: Write your logs as a chain of methods. - - title: Fully Configurable - image: /lumberjack-bust.svg - imageId: lumberjack-bust - details: Every aspect of Adze is under your control. - - title: Log Listeners - image: /logs-small.svg - imageId: logs-small - details: Log listeners give you control of your data. ---- - -::: slot typescript-support - -## First Class TypeScript Support - -Adze is built with TypeScript from the ground up. Take advantage of all of the benefits of -using TypeScript with your app's logs. -::: - -::: slot chainable-api - -## A Fluent, Chainable API - -Writing your logs should feel natural which is why Adze chose to implement a [chainable -API](/guide/adze-concepts.md) that feels very much like the standard console API (but better). - -```typescript -adze().label('Hello').count.log('World!'); -``` - -::: - -::: slot everything-configurable - -## Everything is Configurable - -Setup your logging exactly how you need it. [Everything with Adze is configurable](/config), from -the default log levels down to the emoji's your logs use. You can even create completely -custom log levels. How you use Adze is up to you. - -```typescript -adze({ useEmoji: true }).success("I'm configured to use emoji's!"); -``` - -::: - -::: slot browser-and-node - -## Supports Browser and Node Environments - -Run code containing your adze logs seamlessly [in both the browser and node](/guide/installation.md) environments. -There is no extra configuration required. -::: - -::: slot globalStore - -## Global Store and Overrides - -Adze comes with a component called [GlobalStore](/guide/globalstore-concepts.md) which provides a global store for your logs. With the global store you can recall logs from an in-memory cache and override log configurations; effectively -enabling [micro-service and micro-frontend architectures](/guide/micro-frontends). -::: - -::: slot footer -Made by [Andrew Stacy](https://github.com/AJStacy) with ❤️ - -Find Adze on [GitHub](https://github.com/AJStacy/adze) -::: - -::: slot learn-more - -## And much more... - -To learn more about Adze and how to use it in your project, take a look at the [Guide](/guide) and -watch the introduction video. -::: diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md index eaf6c419..4ff74ec2 100644 --- a/docs/getting-started/concepts.md +++ b/docs/getting-started/concepts.md @@ -26,11 +26,11 @@ various middleware hooks are called. As you can see in the diagram, a log chain is made up of three parts: -- [Log Class](adze-class.md) +- [Log Class](../reference/log-class.md) - This is where all logs begin, often by calling its static methods to start a chain. -- [Modifiers](modifiers.md) +- [Modifiers](../reference/modifiers.md) - These log methods modify the instance and then return it. -- [Terminator](default-terminators.md) +- [Terminator](../reference/terminators.md) - These methods end the chain and generate the log. #### Example @@ -50,7 +50,7 @@ log, simply call a terminator method. ### Modifiers -Once you have a Log instance you can immediately [terminate](terminators) it, or you can call +Once you have a Log instance you can immediately [terminate](../reference/terminators.md) it, or you can call certain methods that this library calls **modifiers**. Modifiers are methods on a Log instance that changes its behavior. For example, if you wanted to add a performance timestamp to your log you could use the `timeNow` modifier. @@ -71,10 +71,10 @@ For documentation of all of the supported modifiers, please read the [Modifiers] ### Terminator In our [Modifiers](../reference/modifiers.md) example code above, you can see we ended our -chain with [`log()`](default-terminators.md#log). The log method is one of the eight [default log terminators](default-terminators.md). -The library also comes with [other special terminators](other-terminators.md) like -[custom](other-terminators.md#custom). A log method is considered a terminator when it -ends your log chain and returns a [terminated log object](data.md#terminated-log-object). +chain with [`log()`](../reference/terminators.md#log). The log method is one of the nine [default log terminators](../reference/terminators.md). +The library also comes with other special terminators like +[custom](../reference/terminators.md#custom). A log method is considered a terminator when it +ends your log chain. For more information about all of the supported terminators, please read the [Terminators](../reference/terminators.md) page of the [Reference Manual](../reference/introduction.md). diff --git a/docs/home/universal.md b/docs/home/universal.md index db848915..1b5bb911 100644 --- a/docs/home/universal.md +++ b/docs/home/universal.md @@ -1,5 +1,5 @@ Modern JavaScript frameworks like [NextJS](https://nextjs.org/), [NuxtJS](https://nuxt.com/), and [SvelteKit](https://kit.svelte.dev/) combine your "back-end" and "front-end" code in the same location. **Adze is universal** which means it can be executed on the -[server side or the browser side](/guide/installation.md) without any extra considerations. Use it -anywhere! +[server side or the browser side](../getting-started/installation.md) without any extra +considerations. Use it anywhere! diff --git a/docs/reference/micro-frontends.md b/docs/reference/micro-frontends.md index dc102b2b..40ccdf53 100644 --- a/docs/reference/micro-frontends.md +++ b/docs/reference/micro-frontends.md @@ -11,11 +11,11 @@ For a more detailed explanation, please visit these excellent resources: A challenge that comes with micro-frontend architectures is enabling the parent application to be able to coordinate behaviors from the child applications. One of these challenges is logging. Within a micro-frontend architecture you will have multiple apps that are able to injected into the parent application without the parent application needing to know much about how the child application implements their features. In order to prevent chaos within the parent app, child apps typically remove all of their logs before packaging for the parent application. This keeps the browser console clean. The downside to this however is that you may need to capture some logs in production and react to them. Removing them leaves you helpless in this regard. -This is where [Adze](adze-concepts.md) and [GlobalStore](globalstore-concepts.md) come in to help. Because a GlobalStore is a global cache and configuration store, it takes precedence over the configuration of any Adze logs. What this means for a micro-frontend architecture is that you can keep your logs for production and the parent application can control their behavior without knowing anything about the child application. +This is where [Adze](../getting-started/concepts.md) and [GlobalStore](../getting-started/global-store.md) come in to help. Because a GlobalStore is a global cache and configuration store, it takes precedence over the configuration of any Adze logs. What this means for a micro-frontend architecture is that you can keep your logs for production and the parent application can control their behavior without knowing anything about the child application. ### Example Architecture -![micro front end architecture example](./assets/micro-frontends-diagram.svg) + ### Explanation @@ -23,4 +23,4 @@ Within the dev environment of each of your child applications you can interact w ## Best Practices -When writing logs in your child applications you should apply a common [namespace](modifiers.md#namespace-ns) across all of them. This enables the parent application to target those logs and control them as needed. +When writing logs in your child applications you should apply a common [namespace](../reference/modifiers.md#namespace--ns) across all of them. This enables the parent application to target those logs and control them as needed.