feat: cut version 1 (#4)

BREAKING CHANGE: cut version 1.0

* feat: update app-runtime exports, add readmes
* docs: add root readme

Author: amcgee

README.md

@@ -1,4 +1,27 @@
-# app-runtime
-A singular runtime dependency for applications on the DHIS2 platform
+# DHIS2 Application Runtime
 
-**WORK IN PROGRESS, DO NOT USE**
+See [@dhis2/app-runtime](./runtime) in the `./runtime` directory for installation and usage.
+
+## Development
+
+```sh
+> yarn test # runs yarn test on each directory under ./services, and also in ./runtime
+> yarn build # runs yarn test on each directory under ./services, and then in ./runtime
+```
+
+## Example
+
+A `create-react-app` example is available at [./examples/cra](./examples/cra). Be sure to run `yarn build` in _this_ directory before installing in the example directory:'
+
+```sh
+> yarn build
+> cd examples/cra && yarn start
+# visit http://localhost:3000
+# login to https://play.dhis2.org/dev to allow the example to retrieve data
+```
+
+## Release
+
+Releases run automatically for every commit to the master branch using the [d2 cli](https://github.com/dhis2/cli).
+
+**NEVER PUSH DIRECTLY TO `master`! ALL DEVELOPMENT IN THIS REPOSITORY IS THROUGH PULL REQUESTS**

examples/cra/.env

@@ -0,0 +1 @@
+SKIP_PREFLIGHT_CHECK=true

examples/cra/package.json

@@ -12,7 +12,8 @@
         "start": "react-scripts start",
         "build": "react-scripts build",
         "test": "react-scripts test",
-        "eject": "react-scripts eject"
+        "eject": "react-scripts eject",
+        "preinstall": "echo \"Run yarn install with --check-files to update local dependency!\""
     },
     "eslintConfig": {
         "extends": "react-app"

examples/cra/src/App.js

@@ -1,14 +1,14 @@
 import React, { Component } from 'react'
 import './App.css'
-import { Query } from '@dhis2/app-runtime'
+import { DataQuery } from '@dhis2/app-runtime'
 
 class App extends Component {
     render() {
         return (
             <div className="App">
                 <header className="App-header">
                     <h3>Indicators (first 10)</h3>
-                    <Query
+                    <DataQuery
                         query={{
                             indicators: {
                                 resource: 'indicators.json',
@@ -30,7 +30,7 @@ class App extends Component {
                                 </pre>
                             )
                         }}
-                    </Query>
+                    </DataQuery>
                 </header>
             </div>
         )

runtime/README.md

@@ -0,0 +1,19 @@
+# DHIS2 Application Runtime
+
+A singular runtime dependency for applications on the DHIS2 platform
+
+## Installation
+
+```sh
+yarn add @dhis2/app-runtime
+```
+
+**NB** Please ensure that all webpack bundles reference the same Context, you can do this by adding `@dhis2/app-runtime` to `peerDependencies` (rather than `dependencies`) and webpack `externals` for _library_ builds. Top-level web applications should be able to include the dependency directly
+
+This library uses the official React Context API (introduced in 16.3) and React Hooks (introduced in 16.8), so **React >= 16.8 is required** to use it
+
+## Usage
+
+The `@dhis2/app-runtime` library is a thin wrapper around application services. See each service's README for usage instructions. Currently, the included services are:
+
+-   [data](../services/data) - declarative data fetching for DHIS2 api queries

runtime/bundle.js

@@ -1 +1,5 @@
-export { Provider as DataProvider, Query } from '@dhis2/app-service-data'
+export {
+    Provider as DataProvider,
+    Query as DataQuery,
+    useQuery as useDataQuery,
+} from '@dhis2/app-service-data'

runtime/src/index.js

@@ -2,35 +2,29 @@
 
 ## Installation
 
-```sh
-yarn add @dhis2/app-service-data # ONCE THIS IS PUBLISHED, IT'S NOT YET
-```
-
-**NB** Please ensure that all webpack bundles reference the same Context, you can do this by adding `@dhis2/app-service-data` to `peerDependencies` (rather than `dependencies`) and webpack `externals` for _library_ builds. Top-level apps should be able to include the dependency directly
-
-This library uses the official React Context API (introduced in 16.3) and React Hooks (introduced in 16.8), so **React >= 16.8 is required** to use it 
+This package is internal to `@dhis2/app-runtime` and should not be installed independently.  `@dhis2/app-service-data` is not currently published to `npm`.  Please install `@dhis2/app-runtime` instead.
 
 ## Usage
 
 At the top-level application entry point (i.e. `index.js` in Create React App configurations)
 
 ```js
-import { Provider } from '@dhis2/app-service-data'
+import { DataProvider } from '@dhis2/app-runtime'
 
 export default () => (
-    <Provider baseUrl="localhost:8080" apiVersion={32}>
+    <DataProvider baseUrl="localhost:8080" apiVersion={32}>
         <App />
-    </Provider>
+    </DataProvider>
 )
 ```
 
 To request data from a DHIS2 Core server anywhere in the app:
 
 ```js
-import { Query } from `@dhis2/app-service-data`
+import { DataQuery } from `@dhis2/app-runtime`
 
 const MyComponent = () => (
-  <Query query={{
+  <DataQuery query={{
     me: { resource: 'me' },
     indicators: { resource: 'indicators.json', pageSize: 10 }
   }}>
@@ -39,29 +33,29 @@ const MyComponent = () => (
       if (error) return `ERROR: ${error.message}`
       return <div>{JSON.stringify(data)}</div>
     }
-  </Query>
+  </DataQuery>
 )
 ```
 
 You can also use the cleaner React hooks api:
 
 ```js
-import { useQuery } from '@dhis2/app-service-data'
+import { useDataQuery } from '@dhis2/app-runtime'
 
 const MyComponent = () => {
-  const { loading, error, data } = useQuery({
-    me: { resource: 'me' },
-    indicators: { resource: 'indicators.json', pageSize: 10 }
-  })
-  if (loading) return '...'
-  if (error) return `ERROR: ${error.message}`
-  return <div>{JSON.stringify(data)}</div>
+    const { loading, error, data } = useDataQuery({
+        me: { resource: 'me' },
+        indicators: { resource: 'indicators.json', pageSize: 10 },
+    })
+    if (loading) return '...'
+    if (error) return `ERROR: ${error.message}`
+    return <div>{JSON.stringify(data)}</div>
 }
-``` 
+```
 
 ## Known limitations
 
-* Only GET requests are currently supported
-* ~`resourcePath` must be a string and cannot be split into `resource`, `query`, etc.~
-* The Provider does no data caching or request de-duplication yet
-* Data should be normalized (~and requested in a normalizable way~) at the provider level to optimize network requests
+-   Only GET requests are currently supported
+-   ~`resourcePath` must be a string and cannot be split into `resource`, `query`, etc.~
+-   The Provider does no data caching or request de-duplication yet
+-   Data should be normalized (~and requested in a normalizable way~) at the provider level to optimize network requests