doodlewind / bumpover Goto Github PK

Do you want to request a feature or report a bug?

Bug

What's the current behavior?

https://jsfiddle.net/hp7n1k76/

Return weird result bumping '{}'

What's the expected behavior?

Return '{}' as result (this is not void, so defaultValue should not apply).

With v0.4.0 released, bumpover is pretty close for an announcement. Following work required:

• Update CHANGELOG.
• Add Chinese writeup.
• Add JSFiddle demo using UMD build.
• Add bundle size badge, and juejin.im badge afterwards.
• Add .github template.

Nice to have:

• Submit PR to superstruct that adds link to this repo.

Let's make this happen!

We have only one test case for now, which is poor. To ensure reliable releases, adding test cases covering these parts are planned:

Bumpover

• bumper.bump with empty data
• bumper.bump with empty rule
• bumper.bump with invalid rule
• bumper.bump with invalid data
• bumper.bump with nested data and rule updating node value
• bumper.bump with nested data and rule updating node key
• bumper.bump with nested data and multi rules
• bumper.bump with invalid struct
• bumper.bump with nested data and one rule struct
• bumper.bump with nested data and multi rule structs
• bumper.bump with invalid option
• bumper.bump with stop action on root
• bumper.bump with stop action on node
• bumper.bump with invalid action
• bumper.bump with ignore unknown on node
• bumper.bump with ignore unknown on root
• bumper.bump with default value
• bumper.bump with async resolve
• bumper.bump with childKey unmatched node (allow stub)
• bumper.test
• bumper.assert

XMLBumpover

• bumper.bump with empty data
• bumper.bump with namespace tags
• bumper.bump with CDATA tags
• bumper.bump with stop action
• bumper.bump with ignore unknown

JSONBumpover

• bumper.bump with empty data (throws for now)
• bumper.bump with nested data and multi rules

Bumpover is designed to migrate data at first. For such tasks, writing unit tests is critical to ensure reliablity. Since bumper.bump is async, it may be confusing testing it.

A new post introducing how to write test for complex taasks in ./docs is nice to have.

Since we have added unit tests in #19, before next minor release, it makes sense integrating CI coverage service with its badge into README, which looks more reliable :-)

In a complex data structure, the fields expressing a node's children may differ in different types of nodes. So it's useful to have each rule specify its childrenKey for traversing. This field is optional, with options.childrenKey as default.

Moreover, the childrenKey API looks verbose, which can be simplified with a better name. For nodes without matched childrenKey, we also need a way handling them.

UMD build is necessay for using in browser environment, e.g., JSFiddle. Requirement:

• Raw UMD build for JSFiddle debugging.
• Minified UMD build for <script> tag in production.

Following documentation is supposed to ship with next minor release:

• Basic README with motivation, shining points and very brief demos
• Basic API reference
• Changelog

Do you want to request a feature or report a bug?

Bug

What's the current behavior?

https://jsfiddle.net/1u29rkjk/

Error thrown on { tag: 'div', children: 123 }:

index.js:81 Uncaught (in promise) TypeError: children.map is not a function
    at bumpRoot (index.js:81)
    at rule.update.then.result (index.js:170)
    at <anonymous>

What's the expected behavior?

This is undefined behaviour for now indeed. Any ideas for expected result?

Do you want to request a feature or report a bug?

Feature

For now the nodes with no rules matched will be kept or ignored, without being handled by any custom rules. So it seems better to add a "default" update handler for such nodes, in this case we can even remove the "ignoreUnknown", giving more flexibility to user.

Do you want to request a feature or report a bug?

Feature

It's better replacing the new Promise() with Promise.resolve in trivial cases.

Do you want to request a feature or report a bug?

Feature

We can add options.beforeMatch(node) without side effect, which allows some general analysis of the document.

For now README is enriched and API reference is added. For an easy to use library, a vivid guide is also critical. It's good to show following examples:

• Installing.
• Validating plain object with superstruct.
• Bumping plain object.
• Bumping with struct validation.
• Bumping XML string.
• Customize serializer and deserializer (e.g., JSON string).
• Async bumping image nodes.
• Using action: 'stop' to return beforehand.
• Using ignoreUnknown to keep or discard unknown nodes.

Some of them can be picked out as working JSFiddle examples. Moreover, the default example in README is not hitting pain points. Using a better one?

• Replace example in README.

Do you want to request a feature or report a bug?

Bug

What's the current behavior?

require('bumpover') throws error.

What's the expected behavior?

Dependencies should be installed automatically.

For now we need to support following methods:

• bumper.bump
• bumper.assert
• bumper.test
• validate rule.struct

bumper.bump should implement following options:

• silent
• defaultValue

With following bumpovers out of the box:

• class Bumpover
• class XMLBumpover
• class JSONBumpover

Features planned with low priority for recent releases:

• validate (do with schema)
• customizable rule methods
• cache bump result
• benchmark
• test runner cli & utils

Currently errors from superstruct are thrown as string, which is overkill. Providing a consistent error format sounds to be a better solution.

This feature is of relative low priority for now, since we don't have enough real world cases addressing it.

For now examples are built by npm scripts, which was a workaround for build test. Now that Ava is integreted, this is no longer necessary. So we need new way running examples. Requirements:

• Running examples does not couple with main package.json.
• Example can have more side effect like HTML view and network request, with its standalone package.json or simply run in node.
• All examples should have similiar way of running, with a unified README in examples folder.

XML dependencies are not provided in JSFiddle demo.

Bumpover walks through data in DFS way. To customize new data structure after bumping, one approach is to use the Result.action field.

Each Result resolved by bumpNode has one of actions in below:

• next: Continue recursive traversing.
• skip: Recognize current node as leaf node, return from traversing.

In this case we can preserve certain complex structure in bumped data, i.e., macro tags in rich text xml format.

Do you want to request a feature or report a bug?

Feature

For tree shaking it'll be better bundle Bumpover with package.module.

https://github.com/rollup/rollup/wiki/pkg.module

Do you want to request a feature or report a bug?

Feature

We have a well defined rule runner for now, whereas for a large doc shape, writing rules in flat array may not scale up as expected.

One solution is to expose the getRule to user, leaving them to get and even compose rules, like what chainCommand did in ProseMirror. But then rules may not be enforced as flat array.

This is a very premature idea. New API may change whenever better thoughts are proposed.

For now we only have a catalog in reference.md. It's necessary to add up existing API into it.

Currently the traversing logic is not guarded by test cases. For a mature library, following points are necessary:

• Standalone test folder containing test cases.
• Test runner devDependencies integration.
• Running tests on CI via npm scripts.

Currently when bumping '' in JSONBumpover, an error is thrown by JSON.parse. It may be nicer handling them in a more elegant way.

This feature is pretty good to have if it doesn't introduce large refactoring.

Currently an action is required for each rule, which is verbose in most of the cases. Making this field optional can lead to terser rules. The default action should be 'next'.

This change is supposed to be landed after we have reliable unit tests.

Do you want to request a feature or report a bug?

Feature

What's the current behavior?

The result returned by rule.struct is discarded.

What's the expected behavior?

Use the validated result as newNode.