ToC

• ToC
• REWRITE IN PROGRESS
  • The problems with v17
• XLIB v18+
  • Goals
  • Non-Goals
  • R&D Status
    • COMPLETE
    • PENDING

REWRITE IN PROGRESS

Xlib is being rewritten from first principles. The current master branch of this repo is dedicated to this rewrite. The current npm xlib package points to xlib@17.x which is a stable, high quality core/util library for node. See the v17 branch for it's source.

The v17 branch is:

• highly stable
• full featured
• used in production
• available as the default npm xlib package

The problems with v17

• too opinionated: had debugging and logging interactions built into the runtime. v18 includes a logger and source-map-support but doesn't do these automatically.
• obsolete features
  • required Bluebird promises: bluebird was great before promises became a native part of javascript. v18 has xlib.promise which supports any promise implementation you use.
  • brittle axios: axios "works" but fails for advanced features (proxy, network failures, authentication). v18 uses gaxios instead and is less strongly tied to it.
  • no use of async/await: not in itself a reason to rewrite, but supporting async/await by default simplifies the api
• node only: v18 targets browsers and node equally

The remainder of this readme is dedicated to the v18 rewrite.

XLIB v18+

Your isomorphic toolbox

Goals

• Monorepo: the core xlib, tooling, and build verification projects all live in this repo
• Docs: full online documentation
• Promises: async / await by default
• Isometric: full support for node and browser
• Performance: take advantage of worker threads where it makes sense
• Full Featured: aim to provide 80% of utility needs
• Professional: no hacks, fully documented, deployment environment aware
• Dev Experience: will include dev-env scafolding scripts and an easy build system
• Lightweight: A library, not framework. No unexpected logging to console, tree-shake support

Non-Goals

• Legacy browser support: Ignoring IE, but Edge-Classic support will be attempted
• Legacy Node support: Development is done on Node 14.x. Node 12.x should work fine.
• Dev Tooling Agnostism: Development is done on VSCode via ubuntu. You should be able to build/dev on windows, but it's not tested.
  • Win10 Tip: Use WSL for development!

R&D Status

Current v18.x is of develop build quality (meaning: do not use this right now).

Critical R&D complete. Now porting most useful xlib features to the new codebase.

The following signifiers will be attached to the v18 rewrite as work progresses

• develop: not suitable for any use.
• alpha: usable for PoC projects only.
• beta: can be used for production, but features may be missing, and breaking changes should be expected between xlib versions

COMPLETE

• isomorphic: xlib feature parity for browser and node projects
  • Full test suite runs (and passes) under Node and Evergreen Firefox + Chrome
• typings: ensure dependent projects get sub-package typings automatically
  • basically, tsconfig.json has to be setup properly. for example, esModuleInterop:true
• debugging: ensure dependent projects can debug into xlib's *.ts source files
  • dependent project's launch.json needs to properly setup the outFiles setting. see build-examples/xlib-node-basic
  • browser debugging properly sourcemaps to original .ts files
• monorepo: develop xlib ecosystem as seperate projects within the same repository
  • use npm @microsoft/rush
• upgradeability: ensure dependent modules can be properly upgraded in a reliable way
  • use rush check and rush dep-check and rush dep-upgrade for this workflow
• documentation: proper code documentation, auto-gen from source
  • functional doc system using api-extractor via the @xlib/xlib-docs website project.
  • if we need to change in the future, consider using https://github.com/tgreyuk/typedoc-plugin-markdown
• testing: isometric testing supported: mocha used in browsers, jest used in node.
  • jest doesn't work in browsers. didn't switch to full mocha because heft nicely runs jest tests when it builds typescript, and I don't want to spend the time figuring out to do similar with mocha.
  • however there is a problem, in that jest's expect library isn't available cross-platform and it doesn't seem easy to register another assertion lib to globally override jest's in node.
  • so currently working on building the xlib.diagnostics.logging module to handle this kind of work.

PENDING

• publishing: ensure xlib ecosystem can be published to npm
• basic react e2e: proof of concept using react to setup a real app (including ssl and dev vs production env)
• doc site: a documenation site with full text search and versioning
• modern promise libary
  • probably just use builtin promises
• enterprise grade logging system (without the enterprise plumbing requirement)
  • ??? some plugable listener lib probably
• isomorphic worker threads: currently using npm threads which works, but is brittle