plastikfan / jaxom-ts Goto Github PK

This will help improve code coverage by reducing the optionality in items that are not optional from the spec service clients perspective. This is potentially a big change that warrants the change being made under its own issue rather than bundling in with the coverage issue (#35)

Manadatory labels should be setup in client constructors so they can be used without needing to check if they are valid or not.

branch: mandatory-spec-labels

See:

https://ericdouglas.github.io/2015/09/27/checklist-for-your-new-open-source-javascript-project/

https://codeburst.io/how-to-create-and-publish-your-first-node-js-module-444e7585b738

When the JSON is build to represent an XML tree, sometimes the descendents contain multipe entries of the same type. These should be combined into a common collection.

• Add a method: combine to normaliser which combines collections of elements of the same type into the same collection
• Add tests to check handling of combine method on abstract elements

functionality that provides access to spec should be implemented as a separate class, which is injected into the transformer and converter

Code coverage with coveralls (https://github.com/nickmerwin/node-coveralls)
https://github.com/alanshaw/nodeunit-lcov-coveralls-example

https://github.com/zinserjan/mocha-webpack/blob/master/docs/guides/code-coverage.md

Might need to use remap-istanbul (https://www.sitepen.com/blog/code-coverage-for-typescript-and-other-transpiled-languages/)

This link may be better as it focuses on webpack and typescript: https://tomasalabes.me/blog/typescript/tests/code-coverage/webpack/2018/09/24/ts-code-coverage.html

Istanbul typescript/mocha integration: https://istanbul.js.org/docs/tutorials/typescript/

And: https://zinserjan.github.io/mocha-webpack/docs/guides/code-coverage.html

• Create account
• install node-coveralls into package

The npm pack command invokes the "prepare" step, which in turn is configured to invoke __b:publish. This step currently only builds the source bundle when it should also include the cli bundle.

branch: build-cli-for-publish

The release procedure as documented in https://itnext.io/step-by-step-building-and-publishing-an-npm-typescript-package-44fe7164964c has exposed an issue with the current implmentation.

The problem is with the webpack build. The production build does not produce the test bundle, which means that it is missing when th release process needs to test the release before publishing.

webpack bundle names should change for more clarity:

• webpack.jaxom.src.prod.js --> webpack.config.src.js
• webpack.jaxom.test.prod.js --> webpack.config.test.js
• webpack.jaxom.src.dev.js --> webpack.config.src.js
• webpack.jaxom.test.dev.js --> webpack.config.test.js

Need to be able run jaxom adhoc. The basic cli tool needs to be able to read in and XML file and output the corresponding JSON.
The tool needs the following parameters:

• file path to input xml file (positional: 1)

• xpath query (positional: 2)

• output file name (positional 3, optional) if missing display to screen

• Read XML file and obtain the XML as string

branch: jaxom-cli

• Set process code (process.exitCode = 1;)

This issue was discovered as a result of improving test code coverage. The following is an example of the case that causes an exception:

<?xml version="1.0"?>
  <Application name="pez">
    <Cli>
      <Commands>
        <Command name="base-command" abstract="true">
          <AlphaChild rank="alpha"/>
        </Command>
        <Command name="list-command" inherits="base-command">
          <BetaChild rank="beta"/>
        </Command>
      </Commands>
    </Cli>
  </Application>

which throws:

 TypeError: reduce: list must be array or iterable
  at _reduce (/Users/Plastikfan/dev/github/js/jaxom-ts/node_modules/ramda/src/internal/_reduce.js:60:9)
  at reduceBy (/Users/Plastikfan/dev/github/js/jaxom-ts/node_modules/ramda/src/reduceBy.js:55:10)
  at /Users/Plastikfan/dev/github/js/jaxom-ts/node_modules/ramda/src/internal/_dispatchable.js:41:15
  at /Users/Plastikfan/dev/github/js/jaxom-ts/node_modules/ramda/src/internal/_curryN.js:37:27
  at /Users/Plastikfan/dev/github/js/jaxom-ts/node_modules/ramda/src/internal/_arity.js:14:19
  at /Users/Plastikfan/dev/github/js/jaxom-ts/node_modules/ramda/src/internal/_checkForMethod.js:22:72
  at /Users/Plastikfan/dev/github/js/jaxom-ts/node_modules/ramda/src/internal/_curry2.js:22:18
  at f1 (/Users/Plastikfan/dev/github/js/jaxom-ts/node_modules/ramda/src/internal/_curry1.js:18:17)
  at Normaliser.combineDescendants (/Users/Plastikfan/dev/github/js/jaxom-ts/lib/normaliser/normaliser.class.ts:50:51)

caused by this line (of normaliser.combineDescendants):

const renameGroupByElementChildrenObj = groupByElement(children);

Need to export the generic cli types, inclidung ParseInfoFactory

Use coverage reports to improve testing coverage

branch: feature/improve-test-coverage

current implementation of createTypedCollection needs to be made generic somehow. The problem with turning it into a generic is that the way you interact with different types of collection is different so it would be difficult to turn this into generic functionality.

Also, the current implementation is not creating the typed collecion as we expect.
Need to read up on more of the advanced topic of typescript particular with generics. Although having said that, the iterablies.d.ts which contains the type descritpions of the collection types does show that all collections have the following methods in their definition:

• Symbol.iterator: IterableIterator
• entries()
• keys()
• values()

Even Set has the "keys" method, which actually just returns the vlaues despite the name of the method.

We possibly need to make getTransform a generic function, this will then make it typesafe. But the template would take a string denoting the type. So the template paramter would take string values for types (if that makes sense)

eg 'number', 'boolean', 'symbol' etc are not strings, but types.

You can create a map which maps strings to their type
eg 'numer' -> number

Static initialisation of the transformer can be simplified and there doesn't need to be a static function that is separately invoked

• Ensure all functions are jsdocumented
• Change let declarations to const whereever possible
• Add type info to variable declarations where possible (including using {} type)

Currently, exceptions thrown are just Error. We need to create one or more custom exception types and throw these instead.

• JaxConfigError
• JaxParseError(contains element path)
• JaxInternalError
• JaxSolicitedError (throwIf config setting)

Start using debug/tslib in typescript projects.

• move all transform related function into new transfromer class
• Move types, specs and exceptions out of converter directory

Create the Xpath converter from jaxine implementation

• Extract class functionality into impl file so that private methods can be tested
• Review all spec access and use lens to access fields in a consistent manner
• Review default spec (R.defaultTo) access when fields not present on user spec
• Remove spec paramater from transformer functions
• Fix the default spec
• Remove fetchCoercionOption and replace with calls to fetchSpecOption
• Clear up coercion activation in buildLocalAttributes and composeText
• Fix up throwIfMissing functionality in buildChildren
• Add converter front-end tests
• Remove context from createTypedCollection (during tidy up)
• Add composeText tests

When the JSON is build to represent an XML tree, sometimes the descendents contain multipe entries of the same type. These should be combined into a common collection.

coercion inside the spec should be separate between textNodes and attributes. trim should be outside of coercion.

See https://travis-ci.org/
https://github.com/dwyl/learn-travis
https://www.freecodecamp.org/news/how-to-wire-travis-ci-to-do-the-heavy-lifting-in-your-workflow-72693c855696/

More info here:
https://www.robinwieruch.de/javascript-continuous-integration

Need to install @istanbuljs/nyc-config-typescript

Currently, when an error occurs during parsing/transformation we throw an error. However, this error does not currently show the element at fault. This is not useful to the end use, because they won't know exactly what to fix in their xml config that contains the error. We need to pass around the XML Node/Element to any function/method that is capable of throwing an error so useful contextual information can be provided to the client.

See: https://www.codeproject.com/questions/186261/how-to-get-the-full-path-of-an-xml-node

• Add attribute name

If the user provides a spec where attributes.coercion.matchers.collection.delim is the same as attributes.coercion.matchers.collection.assoc.delim, then there will be a problem in extracting collection item values. The spec servce should validate the spec and throw an exception if validation fails.

branch: validate-spec.

When the grand child elements of the element being built does not have an id, the parent (ie the thing in the middle) may still have multiple entries of the same type listed as separate entities. These are still ripe for combination, whcih the current implementation of combineDescendants does not complete.

branch: combine-anon

The existing IFileWriter interface should be replaced with memfs for a more comprehensive implemetation of a virtual file system.

branch: use-memfs

Create project boilerplate. Branch: feature/boilerplate

TSlint is legacy, eslint is the future/

Interface types that are 'shared' between jaxom-ts & zenobia-ts need to be in an alternative package. The reason for this is, if another implementation is developed that replicates jaxom in some other way, there should be no dependency of this alternative implementation on jaxom-ts. The best solution would be for these types to be declared elsewhere. Can we and does it male sense to have a package just for types? And can we define these in DefinitelyTyped (perhaps as @types/)? According to DefinitelyTyped, it is Ok to define modules that have types only; these are called 'Ghost modules' or 'non-instantiated modules' (https://definitelytyped.org/guides/best-practices.html).

See: https://devblogs.microsoft.com/typescript/writing-dts-files-for-types/ and https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html
But note, this should not done until jaxom-ts is well tested and we know for sure what the types should be and thus fit for being published.

See this:
https://itnext.io/step-by-step-building-and-publishing-an-npm-typescript-package-44fe7164964c

for information about which new scripts to add to package.json

Also see:
https://cameronnokes.com/blog/the-30-second-guide-to-publishing-a-typescript-package-to-npm/

This will allow use of the new optional chaining operator '?.', which will allow us to remove the 'ts-optchain' dependency.

• Remove ts-optchain dependency and replace with the native new ?. operator where required

This is due to the function isCombinable. Zenobia needs to build Arguments which is a collection of Argument's. However, Argument is not inheritable like Command's are. But that doesnt mean it should not benefit from normalisation. The isCombinale function needs to be modified to not insisting on the recurse attribute being defined on an element.

branch: no-normalise-without-recurse

types.PrimitiveType needs to be defined/clarified

Why is it currently only ['number', 'boolean'] not including string or symbol.

Type of assocType on transformAssoc needs to be changed from any, to something more useful.

transformPrimitives is also a bit confusing wiuth regards to types.

All test code should executedd inside an 'it', otherwise if there is an error within this code, you don't know which test is failing.

use https://greenkeeper.io instead. david-dm.org is insufficiently documented so don't use that.

• Install greenkeeper into github repo and grant access
• check the greenkeeper build on travis
• Then enable (https://greenkeeper.io/docs.html#enabling_a_repo); this will require reviewing the first pull request that greenkeeper generates. Beware, the initial pull-request may take up to 30 minutes to materialise, so be patient.

transformCollection does not cater for typed array properly (Uint8Array, Int8Array and Set).

The following line is inadequate:

if ((collectionType === '[]') || R.toLower(collectionType) === 'array') {

Define the exports that clients of jaxom can use in the entry point: index.ts.

Might be able to fix project config by using references, see: https://code-examples.net/en/docs/typescript/handbook/project-references

When the user invokes buildElement on the converter, if there is a requirement to build a lot of different element types within that XML tree, it can beome very verbose to specify and probably repeat the same definitions accross multiple elements. We should allow the user to specify a common entry inside IParseInfo. Any setting not specified in the element specific entry should be looked up in the common entry. This will make using Jaxom easier and more concise. The def entry will also share any settings in common.

This will require buildElement to be split out into 2 parts; the first part is the entry point from the user call at which point we can check for the abstract flag and throw if present. The second part is the existing recursive functionality.