@thepassle/app-tools 0.9.3 → 0.9.4

package/api/README.md

@@ -0,0 +1,443 @@
+# Api
+
+Small wrapper around the native [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API.
+
+## Install
+
+```
+npm i -S @thepassle/app-tools
+```
+
+## Usage
+
+```js
+import { Api } from '@thepassle/app-tools/api.js';
+
+/** Using defaults: */
+const api = new Api();
+
+/** Or with configuration: */
+const api = new Api({
+  baseURL: 'https://api.foo.com',
+  responseType: 'text',
+  plugins: [
+    {
+      beforeFetch: ({url, headers, fetchFn, responseType, baseURL, method, opts, data}) => {},
+      afterFetch: (res) => res,
+      transform: (data) => data,
+      handleError: (e) => true
+    }
+  ]
+});
+
+const user = await api.get('/users/1');
+await api.post('/form/submit', { name: 'John Doe', email: 'johndoe@internet.com' });
+
+try {
+  await api.get('/foo');
+} catch(e) {
+  console.log(e); // StatusError
+  e.message; // the `statusText` of the `response`
+  e.response; // access the `response`
+}
+```
+
+### Error Handling
+
+By default `api` will throw an error if a response is not ok (`!response.ok`). If this is the case, it will throw a `StatusError`. The `StatusError` is thrown with the `response.statusText` as message, and also has the actual `response` available on it: `e.response`.
+
+## Composable
+
+Use plugins to customize your requests to fit your needs
+
+### `logger`
+
+```js
+import { logger, loggerPlugin } from '@thepassle/app-tools/api/plugins/logger.js';
+
+/** Logs metadata to the console */
+api.get(url, {plugins: [logger]});
+
+/** Or */
+const logger = loggerPlugin({collapsed: false});
+api.get(url, {plugins: [logger]});
+```
+
+### `cache`
+
+```js
+import { cache, cachePlugin } from '@thepassle/app-tools/api/plugins/cache.js';
+
+/** Caches the response for a default of 10 minutes */
+api.get(url, {plugins: [cache]});
+
+/** Or */
+const cache = cachePlugin({maxAge: 1000});
+api.get(url, {plugins: [cache]});
+```
+
+### `debounce`
+
+```js
+import { debounce, debouncePlugin } from '@thepassle/app-tools/api/plugins/debounce.js';
+
+/** Debounces the response for a default of 1000 ms */
+api.get(url, {plugins: [debounce]});
+
+/** Or */
+const debounce = debouncePlugin({maxAge: 2000});
+api.get(url, {plugins: [debounce]});
+```
+
+**Note:** The `debounce` plugin wraps the `fetchFn` in a debouncer. `await`ing the call will cause the debounce to be awaited. E.g.:
+
+```js
+api.get(url, {plugins: [debounce]}).then(() => { console.log(1) });
+api.get(url, {plugins: [debounce]}).then(() => { console.log(2) });
+
+// Output: 
+// 2
+```
+
+But awaiting it will become:
+```js
+await api.get(url, {plugins: [debounce]}).then(() => { console.log(1) });
+await api.get(url, {plugins: [debounce]}).then(() => { console.log(2) });
+
+// Output: 
+// 1
+// 2
+```
+
+### `abort`
+
+```js
+import { abort } from '@thepassle/app-tools/api/plugins/abort.js';
+
+/** Aborts previous, unfinished requests via an AbortController if requests are fired in quick succession, like spammy clicks on buttons */
+api.get(url, {plugins: [abort]});
+```
+
+### `mock`, `delay`
+
+```js
+import { mock } from '@thepassle/app-tools/api/plugins/mock.js';
+import { delay, delayPlugin } from '@thepassle/app-tools/api/plugins/delay.js';
+
+/** Easily mock requests during development using the native `Response` object */
+api.get(url, {
+  plugins: [
+    mock(() => new Response(JSON.stringify({foo: 'bar'}))),
+    delay // defaults to 1000ms
+  ]
+});
+
+/** Or */
+const delay = delayPlugin(2000);
+api.get(url, {plugins: [delay]});
+```
+
+### `jsonPrefix`
+
+```js
+import { jsonPrefix, jsonPrefixPlugin } from '@thepassle/app-tools/api/plugins/jsonPrefix.js';
+
+/** Add plugins to run on all requests */
+const api = new Api({ plugins: [jsonPrefix] });
+
+/** Or */
+const jsonPrefix = jsonPrefixPlugin('<prefix>');
+const api = new Api({ plugins: [jsonPRefix] });
+```
+
+### `xsrf`
+
+```js
+import { xsrf, xsrfPlugin } from '@thepassle/app-tools/api/plugins/xsrf.js';
+
+/** Add plugins to run on all requests */
+const api = new Api({ plugins: [xsrf] });
+
+/** Or */
+const xsrf = xsrfPlugin({
+  xsrfCookieName: '',
+  xsrfHeaderName: ''
+});
+const api = new Api({ plugins: [xsrf] });
+```
+
+### Other
+
+```js
+import { logger } from '@thepassle/app-tools/api/plugins/logger.js';
+
+/** Add plugins to run on all requests */
+const api = new Api({ plugins: [logoutOnUnauthorized, logger] });
+```
+
+## Methods
+
+```js
+api.get(url, opts);
+api.options(url, opts);
+api.delete(url, opts);
+api.head(url, opts);
+api.post(url, data, opts);
+api.put(url, data, opts);
+api.patch(url, data, opts);
+
+api.addPlugin({
+  beforeFetch: ({url, headers, fetchFn, responseType, baseURL, method, opts, data}) => {},
+  afterFetch: (res) => res,
+  transform: (data) => data,
+  handleError: (e) => true
+});
+```
+
+## Big List of Options
+
+```js
+api.get(url, {
+  baseURL: 'https://api.foo.com',
+  responseType: 'text',
+  params: { foo: 'bar' },
+  plugins: [
+    {
+      beforeFetch: ({url, headers, fetchFn, responseType, baseURL, method, opts, data}) => {},
+      afterFetch: (res) => res,
+      transform: (data) => data,
+      handleError: (e) => true
+    }
+  ],
+
+  // Also supports all the options of the native fetch API
+  // mode, credentials, cache, redirect, referrer, integrity, keepalive, signal, referrerPolicy, headers, method
+});
+```
+
+## Options
+
+### `baseURL`
+
+BaseURL to resolve all requests from. Can be set globally when instantiating a new `Api` instance, or on a per request basis. When set on a per request basis, will override the globally set baseURL (if set)
+
+```js
+api.get(url, { baseURL: 'https://api.foo.com' });
+```
+
+### `responseType`
+
+Overwrite the default responseType (`'json'`)
+
+```js
+api.get(url, { responseType: 'text' });
+```
+
+### `params`
+
+An object to be queryParam-ified and added to the request url
+
+```js
+api.get(url, { params: { foo: 'bar' } });
+```
+
+### `plugins`
+
+An array of plugins.
+
+```js
+api.get(url, {
+  plugins: [
+    {
+      beforeFetch: ({url, headers, fetchFn, responseType, baseURL, method, opts, data}) => {},
+      afterFetch: (res) => res,
+      transform: (data) => data,
+      handleError: (e) => true
+    }
+  ]
+})
+```
+
+## Plugins
+
+You can also use plugins. You can add plugins on a per-request basis, or you can globally add them to your `api` instance:
+
+```js
+const api = new Api({
+  plugins: [
+    {
+      beforeFetch: ({url, headers, fetchFn, responseType, baseURL, method, opts, data}) => {},
+      afterFetch: (res) => res,
+      transform: (data) => data,
+      handleError: (e) => true
+    }
+  ]
+});
+```
+
+You can also dynamically add plugins:
+
+```js
+api.addPlugin({
+  afterFetch: (res) => res
+});
+```
+
+Or you can add them on a per request basis:
+
+```js
+api.get(url, {
+  plugins: [
+    {
+      beforeFetch: ({url, headers, fetchFn, responseType, baseURL, method, opts, data}) => {},
+      afterFetch: (res) => res,
+      transform: (data) => data,
+      handleError: (e) => true
+    }
+  ]
+});
+```
+
+### `beforeFetch`
+
+Run logic before the actual `fetch` call happens, or alter/modify the meta information of a request.
+If you want to alter or modify the meta information of a request, make sure to return the value.
+
+```js
+api.get('/foo', {
+  plugins: [{
+    beforeFetch: (meta) => ({...meta, url: '/bar'})
+  }]
+});
+
+// RESULT: url `/bar` gets called instead of `/foo`
+```
+
+If you dont want to alter or modify any meta information of the request, you dont have to return anything.
+```js
+{ 
+  beforeFetch: ({url}) => {
+    console.log(url)
+  } 
+}
+```
+
+### `afterFetch`
+
+Runs immediately after the `fetch` call happened. `afterFetch` should always return a `Response`:
+```js
+{ afterFetch: (res) => res; }
+{ afterFetch: (res) => new Response(JSON.stringify({foo: 'bar'}), res); }
+```
+
+### `transform`
+
+Runs after the `Response` object has been handled according to the `responseType`, (e.g.: `res.json()`). Can be used to transform the returned data:
+Should always return the data.
+
+```js
+{ transform: (data) => data }
+```
+
+### `handleError`
+
+Whether or not an error should throw. Return `true` if an error should throw, return `false` if an error should be ignored.
+
+```js
+{ handleError: (e) => e.message !== 'AbortError' }
+```
+
+### Plugin Examples
+
+#### Request logger
+
+```js
+function requestLogger() {
+  let start;
+  return {
+    beforeFetch: () => {
+      start = Date.now();
+    },
+    afterFetch: () => {
+      console.log(`Request took ${Date.now() - start}ms`);
+    }
+  }
+}
+
+api.addPlugin(requestLogger());
+```
+
+#### Automatic logout on 401 or 403
+
+```js
+api.get(url, {
+  plugins: [
+    {
+      beforeFetch: ({url, headers, fetchFn, responseType, baseURL, method, opts, data}) => {},
+      afterFetch: (res) => {
+        if(res.status === 401 || res.status === 403) {
+          logout();
+        }
+        return res;
+      }
+    }
+  ]
+});
+```
+
+#### Accessing the response body in `afterFetch`
+
+If you want to access the response body of your response in a plugin, make sure to clone the response:
+
+```js
+const myPlugin = {
+  afterFetch: async (originalResponse) => {
+    const clone = originalResponse.clone();
+    let data = await clone.text(); // or `.json()` etc
+
+    data = data.replaceAll('foo', 'bar');
+    
+    // Always make sure to return a `Response`
+    return new Response(data, originalResponse);
+  }
+}
+
+api.addPlugin(myPlugin);
+```
+
+#### Returning a new response entirely
+
+You can also overwrite the response entirely by returning a new `Response`
+
+```js
+api.addPlugin({
+  afterFetch: async (res) => new Response(JSON.stringify({foo: 'bar'}), res);
+});
+```
+
+#### Overwriting the `fetch` implementation
+
+You can also overwrite the `fetch` implementation to use:
+
+```js
+api.addPlugin({
+  beforeFetch: (meta) => ({
+    ...meta,
+    fetchFn: () => Promise.resolve(new Response('{}'))
+  })
+})
+```
+
+Do note that if you use multiple plugins that overwrite the `fetchFn`, the last plugin to overwrite the `fetchFn` will win, there can only be one `fetchFn`.
+
+#### Transforming data
+
+```js
+api.addPlugin({
+  // Adds a `.foo` property to all of your response data
+  transform: (data) => {
+    data.foo = 'bar';
+    return data;
+  }
+})
+```

package/dialog/README.md

@@ -0,0 +1,252 @@
+# Pwa
+
+## Install
+
+```
+npm i -S @thepassle/app-tools
+```
+
+## Usage
+
+```js
+import { Dialog } from '@thepassle/app-tools/dialog.js'; 
+
+const dialog = new Dialog({
+  foo: { 
+    opening: (context) => {context.dialog.querySelector('form').innerHTML = 'hello world';},
+    opened: (context) => {},
+    closing: (context) => {},
+    closed: (context) => {}
+  },
+  bar: someAbstraction({
+    title: 'foo', 
+    import: () => import('./my-component.js'),
+    render: () => html`<my-dialog></my-dialog>`
+  }),
+});
+
+dialog.open({id: 'foo'});
+await dialog.opened;
+dialog.isOpen; // true
+/** Or */
+dialog.opened.then((context) => {});
+
+dialog.close();
+await dialog.closed;
+dialog.isOpen; // false
+/** Or */
+dialog.closed.then((context) => {});
+
+dialog.addEventListener('opening', ({context}) => {});
+dialog.addEventListener('opened', ({context}) => {});
+dialog.addEventListener('closing', ({context}) => {
+  console.log(dialog.returnValue);
+});
+dialog.addEventListener('closed', ({context}) => {
+  const { id, dialog } = context;
+  
+  if (id === 'foo') {
+    console.log(dialog.returnValue);
+  }
+
+  if(dialog.returnValue === 'dismiss') {
+    console.log('Dialog was closed via light dismiss');
+  }
+
+  if(dialog.returnValue === 'programmatic') {
+    console.log('Dialog was closed via `dialog.close()`');
+  }
+});
+
+dialog.modify((dialogNode) => {
+  dialogNode.classList.add('foo');
+});
+
+/** You can also pass parameters to the dialog renderer */
+dialog.open({
+  id: 'foo', 
+  parameters: {
+    foo: 'bar'
+  }
+});
+```
+
+## Callbacks
+
+```js
+import { Dialog } from '@thepassle/app-tools/dialog.js'; 
+
+const dialog = new Dialog({
+  foo: { 
+    /** 
+     * Executed right after the dialog has been created and added to the DOM, before animations have run
+     * Can be used for setup work, like adding `id`s to the dialog, lazy loading, 
+     * and rendering to the dialog's DOM
+     */
+    opening: (context) => {
+      context.dialog; // dialog node
+      context.id; // 'foo';
+      context.parameters; // { bar: 'bar' }
+    },
+    
+    /** 
+     * Executed after animations for the dialog element have run 
+     */
+    opened: (context) => {},
+    
+    /** 
+     * Executed when the native <dialog>'s `close` event has fired, on "light dismiss", 
+     * escape was pressed, or `dialog.close` was called
+     * Executed before animations 
+     * 
+     * Has access to `dialog.returnValue`
+     */
+    closing: (context) => {},
+
+    /** 
+     * Executed after the dialog's close animations have run and right before the dialog node is removed from the DOM 
+     * 
+     * Has access to `dialog.returnValue`
+     */
+    closed: (context) => {}
+  },
+});
+
+dialog.open({id: 'foo', parameters: {bar: 'bar'}})
+```
+
+## Styling the dialog
+
+It's recommended to provide a unique ID for the kind of dialog you want to show. For example:
+
+```js
+import { Dialog } from '@thepassle/app-tools/dialog.js'; 
+
+const dialog = new Dialog({
+  foo: { 
+    opening: ({dialog}) => {
+      dialog.id = 'foo';
+    },
+  },
+});
+```
+
+You can then, in your global stylesheet, select the dialog like so:
+```css
+dialog[app-tools]#foo {
+  border-radius: 10px;
+  background: lightgrey;
+  /* etc */
+}
+
+@media (max-width: 600px) {
+  dialog[app-tools]#foo {
+    width: 90%;
+  }
+}
+```
+
+## Animating the dialog
+
+```js
+import { Dialog } from '@thepassle/app-tools/dialog.js'; 
+
+const dialog = new Dialog({
+  foo: { 
+    opening: ({dialog}) => {
+      dialog.id = 'foo';
+      dialog.form.innerHTML = 'hello world';
+    },
+  },
+});
+
+dialog.open({id: 'foo'});
+```
+
+```css
+dialog[app-tools]#foo {
+  opacity: 0;
+  transform: translateY(40px);
+  transition: opacity .3s ease-out, transform .3s ease-out;
+}
+
+dialog[app-tools][open]#foo {
+  opacity: 1;
+  transform: translateY(0);
+}
+```
+
+## Abstractions
+
+It can be useful to declare some abstractions for the different kinds of dialogs you want to use in your app. Here's an example using Lit:
+
+```js
+import { html, render } from 'lit';
+import { Dialog } from '@thepassle/app-tools/dialog.js'; 
+
+function modal(config) {
+  return {
+    opening: ({dialog, parameters}) => {
+      config.import();
+      render(config.render({parameters, title: config.title}), dialog.form);
+    },
+    closing: ({dialog}) => {
+      console.log(dialog.returnValue); // "bar"
+    }
+  }
+}
+
+const dialog = new Dialog({
+  foo: modal({
+    title: 'Cart',
+    import: () => import('./shopping-cart.js'),
+    render: ({title, parameters}) => html`
+      <h1>${title}</h1>
+      <shopping-cart foo=${parameters.foo}></shopping-cart>
+      <button value="bar">Close</button>
+    `
+  })
+});
+
+dialog.open({id: 'foo', parameters: { foo: 'bar' }});
+```
+
+### Context menu
+
+```js
+import { computePosition } from '@floating-ui/dom';
+import { Dialog } from '@thepassle/app-tools';
+
+export const dialog = new Dialog({
+  context: context()
+});
+
+function context() {
+  return {
+    opening: async ({dialog, parameters, id}) => {
+      dialog.id = 'context';
+      render(parameters.template(), dialog.form);
+
+      if (!media.MAX.XS()) {
+        const { x, y } = await computePosition(
+          parameters.target, 
+          dialog, 
+          { placement: 'bottom-end'}
+        );
+        Object.assign(dialog.style, {
+          marginLeft: `${x}px`,
+          marginTop: `${y}px`,
+        });
+      }
+    }
+  }
+}
+
+dialog.open({
+  id: 'context', 
+  parameters: {
+    target: e.target,
+    template: () => html`<h1>hello world</h1>`
+  }
+});
+```

package/env/README.md

@@ -0,0 +1,29 @@
+# Env
+
+## Install
+
+```
+npm i -S @thepassle/app-tools
+```
+
+## Usage
+
+```js
+import { DEV, PROD } from '@thepassle/app-tools/env.js'; 
+
+if (DEV) {
+  console.log('Running in dev mode');
+}
+
+if (PROD) {
+  console.log('Running in prod mode');
+}
+```
+
+When resolving imports, Node will look for keys in the package export to figure out which file to use. For example "default", "import", or "require".
+
+Tools however can use custom keys here as well, like "types", "browser", "development", or "production". Depending on what kind of import it is, and which environment (dev/prod) tools (like bundlers or dev servers) can resolve/distinguish between which file should actually be used.
+
+## Acknowledgement
+
+This was inspired by [`esm-env`](https://github.com/benmccann/esm-env) by Ben McCann. I've added to my own repo because I like to have useful utils like these centralized in one place for my personal projects, especially when they're as small and elegant as this.