generated from karmaniverous/npm-package-template
-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
25a11d3
commit 137e4d2
Showing
2 changed files
with
21 additions
and
106 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| name: Cloud Sync | ||
|
|
||
| on: | ||
| push: | ||
|
|
||
| jobs: | ||
| sync: | ||
| uses: karmaniverous/gha-workflows/.github/workflows/cloud-sync.yml@main | ||
| secrets: | ||
| RCLONE_CONFIG: ${{ secrets.RCLONE_CONFIG }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,118 +1,23 @@ | ||
| # JsonMap | ||
| > **_Where other tools use special syntax & structure to ENCAPSULATE Terraform code, Metastructure uses a powerful template engine to GENERATE Terraform code._** | ||
| `JsonMap` is a JSON mapping library, which facilitates the transformation of some input JSON object according to a set of rules. | ||
| ## Welcome to Metastructure! | ||
|
|
||
| Installing `JsonMap` is easy: | ||
| **Metastructure** is a command-line tool that works in conjunction with [Terraform](https://www.terraform.io/) and all the other things to generate & manage a complex AWS infrastructure. | ||
|
|
||
| ```bash | ||
| npm install @karmaniverous/jsonmap | ||
| ``` | ||
| With **Metastructure** you can... | ||
|
|
||
| `JsonMap` is _hyper-generic_: you bring your own mapping functions, which may be async and may be combined into complex transformation logic. | ||
| - **_Write a true global configuration._** Manage your entire enterprise from a single YAML file. | ||
|
|
||
| To do this, create a `lib` object, which combines your mapping function libraries into a single object. You can use async functions and organize this in any way that makes sense. | ||
| - **_Actually use SSO in Terraform._** Zero credentials management, ever. | ||
|
|
||
| For example: | ||
| - **_Integrate all the things._** Your configuration goes where Terraform can't. | ||
|
|
||
| ```js | ||
| import _ from 'lodash'; | ||
| import numeral from 'numeral'; | ||
| - **_DRY up your code base._** Because close doesn't count. | ||
|
|
||
| const lib = { _, numeral }; | ||
| ``` | ||
| **Metastructure** leverages the tools you already use to do the things you already do... just faster, smaller, and safer. | ||
|
|
||
| You also need to create a `map` object. This is a [plain old Javascript object](https://masteringjs.io/tutorials/fundamentals/pojo) (POJO) that expresses your mapping rules. | ||
|
|
||
| ## Why? | ||
|
|
||
| Mapping data from one form into another is a critical requirement of virtually every application. | ||
|
|
||
| `JsonMap` decouples mapping structure from mapping logic... and drives that decoupling deep into the logic layer. | ||
|
|
||
| The `lib` object contains the remaining logic that CAN'T be decoupled, and can be used consistently across your application. | ||
|
|
||
| The `map` object is a [POJO](https://masteringjs.io/tutorials/fundamentals/pojo), which can easily be stored in a database yet does NOT express code as text and thus exposes a minimal threat surface. | ||
|
|
||
| **This allows you to transform application logic into structured configuration data and write more generic, flexible applications.** | ||
|
|
||
| ## Usage | ||
|
|
||
| The transformation output will reflect the structure of your `map` object and include any static values. To add mapping logic, use a structured value that consists of an object with a single `$` key, like this: | ||
|
|
||
| ```ts | ||
| const map = { | ||
| foo: 'static value passed directly to output', | ||
| // Structure passed directly to output. | ||
| bar: [ | ||
| { | ||
| static: 'another static value', | ||
| // Keys starting with $ are available for progressive transformations but | ||
| // are not passed to the output object. | ||
| $remove: 'this should be removed from the output', | ||
| // Value defined by a mapping rule expressing an array of transformation | ||
| // objects. If there is only a single transformation object, no array is | ||
| // necessary. The output of the last transformation step is returned as | ||
| // the mapped value. | ||
| dynamic: { | ||
| $: [ | ||
| // Each transformation object uses a special syntax to reference an | ||
| // a method to run and an array of parameters to pass to it. | ||
| { | ||
| method: '$.lib._.get', | ||
| params: ['$.input', 'dynamodb.NewImage.roundup.N'], | ||
| }, | ||
| // The special syntax uses lodash-style paths. Its root object can | ||
| // reference the lib object ($.lib...), the transformation input | ||
| // ($.input...), the output generated so far ($.output...), or the | ||
| // outputs of previous transformation steps ($.[0]..., $.[1]...). | ||
| { | ||
| method: '$.lib.numeral', | ||
| // If there is only a single param, no array is necessary. | ||
| params: '$[0]', | ||
| }, | ||
| { | ||
| method: '$[0].format', | ||
| params: '$0,0.00', | ||
| }, | ||
| ], | ||
| }, | ||
| }, | ||
| ], | ||
| // Value defined by a single mapping rule executing a method against a | ||
| // previous output of the same mapping object. | ||
| progressive: { | ||
| $: { | ||
| method: '$.lib._.toUpper', | ||
| params: '$.output.bar[0].static', | ||
| }, | ||
| }, | ||
| $remove: 'this should be removed from the output', | ||
| }; | ||
| ``` | ||
|
|
||
| The transformation process is _generic_ and _asynchronous_. Feel free to use any function from any source in your `lib` object. | ||
|
|
||
| Your `lib` object can also include locally defined or anonymous functions. Combined with the `$[i]...` syntax, this allows for complex branching transformation logic. | ||
|
|
||
| Mapping objects are _recursive_. If a mapping object (i.e. `{ $: ... }`) renders another mapping object, it will be processed recursively until it does not. | ||
|
|
||
| Input objects can contain data of any kind, including functions. These can be executed as methods of their parent objects using transformation steps. | ||
|
|
||
| Once a `JsonMap` instance is configured, it can be executed against any input. Configure & execute a `JsonMap` instance like this: | ||
|
|
||
| ```js | ||
| import { JsonMap } from '@karmaniverous/jsonmap'; | ||
|
|
||
| // Assumes map & lib are already defined as above. | ||
| const jsonMap = new JsonMap(map, lib); | ||
|
|
||
| // Assumes some input data object is already defined. | ||
| const output = await jsonMap.transform(input); | ||
| ``` | ||
|
|
||
| The [unit tests](https://github.com/karmaniverous/jsonmap/blob/main/lib/JsonMap/JsonMap.test.js) demonstrate this example in action. | ||
| Explore the [Metastructure Wiki](https://github.com/karmaniverous/metastructure/wiki) to learn more, or clone the [Template Repository](https://github.com/karmaniverous/metastructure-template) to get started! | ||
|
|
||
| --- | ||
|
|
||
| See more great templates and other tools on | ||
| [my GitHub Profile](https://github.com/karmaniverous)! | ||
| Built for you with ❤️ on Bali! Find more great tools & templates on [my GitHub Profile](https://github.com/karmaniverous). |