Encapsule Project

Homepage • GitHub • Discussion • Twitter

Encapsule Project is a quest to define a universal protocol for domain-specific software models + infrastructure to support composition of distributed apps & services.

 Holistic App Platform v0.4.4-colfaxpeak

Package: @encapsule/holistic v0.4.4-colfaxpeak build ID "cOPp4PdPRXKyaPt5tQTCqQ"
Sources: @encapsule/holodev#e2ac2697de97dbe7b68722e9de19e7f6d6e282cc
Created: 2022-06-11T19:59:25.000Z // License: MIT
Purpose: tools // Environment: Node.js

@encapsule/holistic distribution package contains the Holistic App Platform's consituent runtime libraries, and the 'appgen' command-line tool used to create derived JavaScript projects and keep them up-to-date.

 Contents

• Introduction
• ⧉ @encapsule/holistic Distribution Package
  • Prerequisites
  • Installation
  • Usage
• Holistic App Platform
  • Overview
  • appgen CLI Tool
  • Platform Runtime Libraries
    • ◰ d2r2
    • ◰ d2r2-components
    • ◰ holarchy
    • ◰ holarchy-cm
    • ◰ holism
    • ◰ holism-metadata
    • ◰ holism-services
    • ◰ holistic-app-models
    • ◰ holistic-html5-service
    • ◰ holistic-nodejs-service
    • ◰ holistic-service-core
    • ◰ holodeck
    • ◰ holodeck-assets
    • ◰ hrequest
• Issues
• Discussion

 @encapsule/holistic

TODO: Briefly explain the contents of the @encapsule/holistic distribution package and explain how it relates to the Holistic App Platform.

 Prerequisites

▴ Top

To get started you will need the following tools installed and available in your development environment:

• GNU Make
• git
• Node.js >=16.13.1
• npm >=8.1.2

With these base prerequisites satisfied, you will be able to install the @encapsule/holistic distribution package. And, then leverage the appgen command line utility to create/update your Holistic App Platform application service.

 Installation

▴ Top

TODO: Add some notes on installation once the package is published to npm.

 Usage

▴ Top

TODO: Add a brief introduction to how this package is used along with a link to the appgen section of this README.

 Holistic App Platform

▴ Top

 Overview

▴ Top

A holistic application service is a developer-maintained Node.js package git repository initialized and subsequently updated with the appgen command-line utility.

All holistic application services maintained with appgen have the same basic structure and base-level feature set.

• Base-level directory structure and entry module file naming conventions.
  • Base-level directory structure is prescriptive and required.
  • Developers can extend the directory / file structure:
    • Extend existing directory branches.
    • Create new directory trees rooted in the root directory.
• The package.json in derived holistic application packages is code-generated and owned appgen.
  • After first appgen run developers should edit holistic-app.json and not the code-generated package.json.
    • devDependencies is managed by appgen and is developer-extensible via holistic-app.json.
    • scripts is managed by appgen and is developer-extensible via holistic-app.json. Platform-defined scripts include:
      • build - build the holistic application by calling make application.
      • clean - remove the previous application build.
      • debug-server - build and start the Node.js HTTP app server on localhost under Node.js inspector.
      • holodeck - execute your application's @encapsule/holodeck test runner.
      • iruts - generate a batch of v4 UUID-derived IRUT-format identifier strings.
      • reset - scrub and additionally clear your local npm cache forcing complete re-stage on npm install.
      • server - build and start the Node.js HTTP app server on localhost.
      • scrub - clean and additionally delete node_modules directory.
      • start - launch a previously built Node.js HTTP app server on localhost.
• Core application build is automated by an appgen-generated Makefile.
  • Abstracts building a holistic application so that you can launch the Node.js HTTP app server. And, service the bundled client application.
  • Does not abstract the application-specific details required to:
    • Test your holistic application.
    • Package your application for distribution (e.g. further source transformation, Dockerfile generation...).
    • Deploy your application to a cloud service provider.
  • Developers can define application-specific test, packaging, and deployment targets in Makefile-App.
  • Holistic application build depends on [eslint], [babel], and [webpack].
    • Configuration for these tools is imposed by appgen and is not currently developer-extensible.

 appgen CLI Tool

▴ Top

The appgen utility is a code generation tool used by developers to initialize and maintain holistic applications.

Both initialization and maintenance operations are performed using the same simple command line:

$ path_to_holistic/appgen --appRepoDir path_to_your_app_repo

Here is what happens when you execute appgen on your_app_repo:

• Reads or creates a default holistic-app.json file.
• Read your project's package.json.
• Remove previously installed platform runtime libraries (RTL's).
• Install new platform RTL's.
• Register platform RTL dependencies.
• Merge application and platform-defined package dependencies.
• De-duplicate and error check finalized dependencies.
• Merge platform-defined npm integrations (e.g. run targets) with app-specific integrations.
• Merge changes back into package.json.
• Rewrite derived app's package.json.
• Initialize or recreate core project directory structure.
• Synthesize core GNU Makefile and Makefile-App files.
• Synthesize tool configuration files required by Makefile targets.
• Execute npm install to update dependencies per rewritten package.json.

 Platform Runtime Libraries

▴ Top

All platform runtime libraries (RTLs) are distributed via the @encapsule/holistic distribution package. And are copied into, and registered for use in derived projects via appgen.

 @encapsule/d2r2

◰ This package contains the Data-Driven React Router (d2r2) component factory extension for React. And, the ComponentRouter dynamic view compositor packaged as a generic React component. Used to build extensible view templates, and decoupled view libraries.

 @encapsule/d2r2-components

◰ This package contains a collection of re-usable d2r2 React components for use with the d2r2 ComponentRouter dynamic view compositor.

 @encapsule/holarchy

◰ Cellular process modeling and runtime engine for Node.js and browser.

 @encapsule/holarchy-cm

◰ This package contains the Holistic App Platform's core re-usable CellModel library.

 @encapsule/holism

◰ This package contains an experimental HTTP 1.1 application server and REST framework derived from the Node.js HTTP API's and the @encapsule/arccore filter RTL. This provides developers with a simple mechanism to define and re-use backend operations as plug-in service filters hosted by the holism server RTL. The package is intended for use in derived applications and services.

 @encapsule/holism-metadata

◰ This package contains an extensible framework for defining application-specific metadata - i.e. data about your app. It is intended for use in derived apps/services and is typically used in conjunction with @encapsule/holism integration plug-in filters to satisfy queries re: publishing organization, application, page, route, hashroute, resource, operation...

 @encapsule/holism-services

◰ This package contains re-usable service filter plug-ins for use with the @encapsule/holism app server package.

 @encapsule/holistic-app-models

◰ This package contains a collection of optional application and service models that may be resused to build holistic-powered runtimes.

 @encapsule/holistic-html5-service

◰ Exports the HolisticAppClient CellModel library for use in derived HTML5 applications.

 @encapsule/holistic-nodejs-service

◰ Exports the HolisticAppServer CellModel for use in derived @encapsule/holistic applications/services.

 @encapsule/holistic-service-core

◰ Exports the HolisticAppCommon CellModel library for use in derived HolisticAppServer and HolisticAppClient CellModels.

 @encapsule/holodeck

◰ This package contains the holodeck test runner and test harness plug-in filter factory infrastructure. Holodeck functions like a medical imaging system for your code that bombards it with queries and captures the results to disk. Comparison of git diff's is often all that's required to verify the correct and expected behavior of updated app/service code tracked in this way.

 @encapsule/holodeck-assets

◰ This package contains re-usable test runners, harnesses, and vectors for use in conjunction with @encapsule/holodeck test infrastructure package.

 @encapsule/hrequest

◰ This package contains arccore.filter wrappers for XMLHttpRequest (browser) and the request module (Node.js server). Provides a mechanism to ensure the runtime fidelity of HTTP GET/POST communication between the client and server. And, between the server and other backend REST service integrations.

 Issues

▴ Top

Please post bug reports to one of the follow issue queues depending on topic:

• @encapsule/holistic GitHub Issues - Holistic platform RTL + appgen issues.

• @encapsule/arccore GitHub Issues - Core data RTL issues.

• @encapsule/arctools GitHub Issue - Core data tools and RTL issues.

 Discussion

▴ Top

Join the Holistic App Platform Discussion (Google Group) -- A group for discussion of Holistic App Platform runtime libraries, tools, design patterns, service architecture, and related topics.

---

Copyright © 2022 Chris Russell Seattle, Washington USA

Published under MIT license by Encapsule Project

Please follow @Encapsule on Twitter for news and updates.