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 [email protected] 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