jason-rails 0.5.0 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e6d1d960c2bb555ccaa555a17de7730ce90c35aa57594256bcb73bc96dade09
-  data.tar.gz: b096c733bd15195ac383097a8138507915caa5fba29d9099325755972a64fe2a
+  metadata.gz: e62faa4e4f1246fa42810c324eec1f8fe96b8026ccdbe12f5b8bd7bc2df3bd4a
+  data.tar.gz: e4f829ce397c7192c173ba6e712a4b5873bd065d687cebf5ad72025f0436f51a
 SHA512:
-  metadata.gz: 4ce914a0e658fe97051ff6a64a48a29bccde202ad3fa60bc3aadc287f4a50a4f169d647b66f456e3147da8551b5b321185caa05c9790c964202d5275b20a8732
-  data.tar.gz: ebde6f3323cb516915e3ddea2f747595a864df2cac9f52e05c67b1320c46f20693c479d7b39b11f391638dc9e5027b92e86ad65089282c6c190b6ba4982b3de3
+  metadata.gz: 6e3abfbfd6e0fbbe6c40dc7c0540448091cd440aaeec3580951a6148d6f1f92e61d5808b39ca02e8c564e1aa57beaf1de4d4cddb34e27b96ace09ca61d856d9a
+  data.tar.gz: b58a34f35981aea9b991f036cb83f9e059fa17a5932d9e9df78b6e86b5532484fe0dc115531365d5044d2f7df42355b5481a353233dcbd6744077b8fcbd58f18

data/.gitignore

@@ -11,4 +11,7 @@
 .rspec_status
 client/node_modules/
 
-client/yarn-error.log
+client/yarn-error.log
+*.log
+*.gem
+.DS_Store

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jason-rails (0.4.1)
+    jason-rails (0.6.0)
       connection_pool (>= 2.2.3)
       jsondiff
       rails (>= 5)

data/README.md

@@ -1,10 +1,12 @@
 # Jason
 
+Jason is still in an experimental phase with a rapidly changing API. It is being used in some production applications, however it is still in 0.x.x series versions, which means that any 0.x version bump could introduce breaking changes.
+
 ## The goal
 
 I wanted:
  - Automatic updates to client state based on database state
- - Automatic persistence to database
+ - Persistence to the database without many layers of passing parameters
  - Redux for awesome state management
  - Optimistic updates
 
@@ -12,6 +14,8 @@ I also wanted to avoid writing essentially the same code multiple times in diffe
 
 Jason attempts to minimize this repitition by auto-generating API endpoints, redux stores and actions from a single schema definition. Further it adds listeners to ActiveRecord models allowing the redux store to be subscribed to updates from a model or set of models.
 
+An alternative way of thinking about Jason is "what if we applied the Flux/Redux state update pattern to make the _database_ the store?".
+
 ## Installation
 
 Add the gem and the NPM package
@@ -24,22 +28,154 @@ gem 'jason-rails'
   yarn add @jamesr2323/jason
 ```
 
+You will also need have peer dependencies of `redux`, `react-redux` and `@reduxjs/toolkit`.
+
+### In Rails
+
+Include the module `Jason::Publisher` in all models you want to publish via Jason.
+
+Create a new initializer e.g. `jason.rb` which defines your schema
+
+```ruby
+Jason.setup do |config|
+  config.schema = {
+    post: {
+      subscribed_fields: [:id, :name]
+    },
+    comment: {
+      subscribed_fields: [:id]
+    },
+    user: {
+      subscribed_fields: [:id]
+    }
+  }
+end
+```
+
+### In your frontend code
+
+First you need to wrap your root component in a `JasonProvider`.
+
+```jsx
+import { JasonProvider } from '@jamesr2323/jason'
+
+return <JasonProvider>
+  <YourApp />
+</JasonProvider>
+```
+
+This is a wrapper around `react-redux` Provider component. This accepts the following props (all optional):
+
+- `reducers` - An object of reducers that will be included in `configureStore`. Make sure these do not conflict with the names of any of the models you are configuring for use with Jason
+- `extraActions` - Extra actions you want to be available via the `useAct` hook. (See below)
+This must be a function which returns an object which will be merged with the main Jason actions. The function will be passed a dispatch function, store, axios instance and the Jason actions. For example you can add actions for one of your custom slices:
+
+```js
+function extraActions(dispatch, store, restClient, act) {
+  return {
+    local: {
+      upsert: payload => dis({ type: 'local/upsert', payload })
+    }
+  }
+}
+```
+
+- `middleware` - Passed directly to `configureStore` with additional Jason middleware
+
 ## Usage
+Jason provides three custom hooks to access functionality.
+
+### useAct
+This returns an object which allows you to access actions which both update models on the server, and perform an optimistic update to the Redux store.
+
+Example
+```jsx
+import React, { useState } from 'react'
+import { useAct } from '@jamesr2323/jason'
 
-### Define your schema
+export default function PostCreator() {
+  const act = useAct()
+  const [name, setName] = useState('')
 
+  function handleClick() {
+    act.posts.add({ name })
+  }
+
+  return <div>
+    <input value={name} onChange={e => setName(e.target.value)} />
+    <button onClick={handleClick}>Add</button>
+  </div>
+}
+```
+
+### useSub
+This subscribes your Redux store to a model or set of models. It will automatically unsubscribe when the component unmounts.
+
+Example
+```jsx
+import React from 'react'
+import { useSelector } from 'react-redux'
+import { useSub } from '@jamesr2323/jason'
+import _ from 'lodash'
+
+export default function PostsList() {
+  useSub({ model: 'post', includes: ['comments'] })
+  const posts = useSelector(s => _.values(s.posts.entities))
+
+  return <div>
+    { posts.map(({ id, name }) => <div key={id}>{ name }</div>) }
+  </div>
+}
+```
+
+### useEager
+Jason stores all the data in a normalized form - one redux slice per model. Often you might want to get nested data from several slices for use in components. The `useEager` hook provides an API for doing that. Under the hood it's just a wrapper around useSelector, which aims to mimic the behaviour of Rails eager loading.
+
+Example
+This will fetch the comment as well as the post and user linked to it.
+
+```jsx
+import React from 'react'
+import { useSelector } from 'react-redux'
+import { useEager } from '@jamesr2323/jason'
+import _ from 'lodash'
+
+export default function Comment({ id }) {
+  const comment = useEager('comments', id, ['post', 'user'])
+
+  return <div>
+    <p>{ comment.body }</p>
+    <p>Made on post { comment.post.name } by { comment.user.name }</p>
+  </div>
+}
+```
+
+## Authorization
+
+By default all models can be subscribed to and updated without authentication or authorization. Probably you want to lock down access.
+
+### Authorizing subscriptions
+You can do this by providing an class to Jason in the initializer under the `subscription_authorization_service` key. This must be a class receiving a message `call` with the parameters `user`, `model`, `conditions`, `sub_models` and return true or false for whether the user is allowed to access a subscription with those parameters. You can decide the implementation details of this to be as simple or complex as your app requires.
+
+### Authorizing updates
+Similarly to authorizing subscriptions, you can do this by providing an class to Jason in the initializer under the `update_authorization_service` key. This must be a class receiving a message `call` with the parameters `user`, `model`, `instance`, `update`, `remove` and return true or false for whether the user is allowed to access a subscription with those parameters.
+
+## Roadmap
+
+Development is primarily driven by the needs of projects we're using Jason in. In no particular order, being considered is:
+- Failure handling - rolling back local state in case of an error on the server
+- Authorization - more thorough authorization integration, with utility functions for common authorizations. Allowing authorization of access to particular fields such as restricting the fields of a user that are publicly broadcast.
+- Utilities for "Draft editing" - both storing client-side copies of model trees which can be committed or discarded, as well as persisting a shadow copy to the database (to allow resumable editing, or possibly collaborative editing features)
+- Benchmark and migrate if necessary ConnectionPool::Wrapper vs ConnectionPool
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/jason. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/jason/blob/master/CODE_OF_CONDUCT.md).
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/jason/api/pusher_controller.rb

@@ -0,0 +1,15 @@
+ class Jason::Api::PusherController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def auth
+    channel_main_name = params[:channel_name].remove("private-#{Jason.pusher_channel_prefix}-")
+    subscription_id = channel_main_name.remove('jason-')
+
+    if Jason::Subscription.find_by_id(subscription_id).user_can_access?(current_user)
+      response = Pusher.authenticate(params[:channel_name], params[:socket_id])
+      return render json: response
+    else
+      return head :forbidden
+    end
+  end
+end

data/app/controllers/jason/api_controller.rb

@@ -1,6 +1,21 @@
 class Jason::ApiController < ::ApplicationController
-  def schema
-    render json: Jason.schema
+  before_action :load_and_authorize_subscription, only: [:create_subscription, :remove_subscription, :get_payload]
+  # config seems to be a reserved name, resulting in infinite loop
+  def configuration
+    payload = {
+      schema: Jason.schema,
+      transportService: Jason.transport_service,
+    }
+
+    if Jason.transport_service == :pusher
+      payload.merge!({
+        pusherKey: Jason.pusher_key,
+        pusherRegion: Jason.pusher_region,
+        pusherChannelPrefix: Jason.pusher_channel_prefix
+      })
+    end
+
+    render json: payload
   end
 
   def action
@@ -20,10 +35,10 @@ class Jason::ApiController < ::ApplicationController
       all_instance_ids.insert(priority.to_i, instance.id)
 
       all_instance_ids.each_with_index do |id, i|
-        model.find(id).update!(priority: i, skip_publish_json: true)
+        model.find(id).update!(priority: i)
       end
 
-      model.publish_all(model.find(all_instance_ids))
+      model.find(all_instance_ids).each(&:force_publish_json)
     elsif action == 'upsert' || action == 'add'
       payload = api_model.permit(params)
       return render json: model.find_or_create_by_id!(payload).as_json(api_model.as_json_config)
@@ -33,4 +48,31 @@ class Jason::ApiController < ::ApplicationController
 
     return head :ok
   end
+
+  def create_subscription
+    @subscription.add_consumer(params[:consumer_id])
+    render json: { channelName: @subscription.channel }
+  end
+
+  def remove_subscription
+    @subscription.remove_consumer(params[:consumer_id])
+  end
+
+  def get_payload
+    if params[:options].try(:[], :force_refresh)
+      @subscription.set_ids_for_sub_models
+    end
+
+    render json: @subscription.get
+  end
+
+  private
+
+  def load_and_authorize_subscription
+    config = params[:config].to_unsafe_h
+    @subscription = Jason::Subscription.upsert_by_config(config['model'], conditions: config['conditions'], includes: config['includes'])
+    if !@subscription.user_can_access?(current_user)
+      return head :forbidden
+    end
+  end
 end

data/client/lib/JasonContext.d.ts

@@ -2,6 +2,6 @@
 declare const context: import("react").Context<{
     actions: any;
     subscribe: null;
-    eager: null;
+    eager: (entity: any, id: any, relations: any) => void;
 }>;
 export default context;

data/client/lib/JasonContext.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = require("react");
-const context = react_1.createContext({ actions: {}, subscribe: null, eager: null });
+const eager = function (entity, id, relations) {
+    console.error("Eager called but is not implemented");
+};
+const context = react_1.createContext({ actions: {}, subscribe: null, eager });
 exports.default = context;

data/client/lib/JasonProvider.js

@@ -8,7 +8,7 @@ const useJason_1 = __importDefault(require("./useJason"));
 const react_redux_1 = require("react-redux");
 const JasonContext_1 = __importDefault(require("./JasonContext"));
 const JasonProvider = ({ reducers, middleware, extraActions, children }) => {
-    const [store, value, connected] = useJason_1.default({ reducers, middleware, extraActions });
+    const [store, value] = useJason_1.default({ reducers, middleware, extraActions });
     if (!(store && value))
         return react_1.default.createElement("div", null); // Wait for async fetch of schema to complete
     return react_1.default.createElement(react_redux_1.Provider, { store: store },

data/client/lib/createJasonReducers.js

@@ -42,6 +42,7 @@ function generateJasonSlices(models) {
             setSubscriptionIds(s, a) {
                 const { payload } = a;
                 const { subscriptionId, model, ids } = payload;
+                console.log({ initialState });
                 s[model][subscriptionId] = ids;
             },
             addSubscriptionId(s, a) {
@@ -53,6 +54,12 @@ function generateJasonSlices(models) {
                 const { payload } = a;
                 const { subscriptionId, model, id } = payload;
                 s[model][subscriptionId] = lodash_1.default.remove(s[model][subscriptionId] || [], id);
+            },
+            removeSubscription(s, a) {
+                const { payload: { subscriptionId } } = a;
+                lodash_1.default.map(models, model => {
+                    delete s[model][subscriptionId];
+                });
             }
         }
     }).reducer;

data/client/lib/createPayloadHandler.d.ts

@@ -1,6 +1,9 @@
-export default function createPayloadHandler({ dispatch, serverActionQueue, subscription, config }: {
+export default function createPayloadHandler({ dispatch, serverActionQueue, transportAdapter, config }: {
     dispatch: any;
     serverActionQueue: any;
-    subscription: any;
+    transportAdapter: any;
     config: any;
-}): (data: any) => void;
+}): {
+    handlePayload: (data: any) => void;
+    tearDown: () => void;
+};

data/client/lib/createPayloadHandler.js

@@ -11,7 +11,7 @@ function diffSeconds(dt2, dt1) {
     var diff = (dt2.getTime() - dt1.getTime()) / 1000;
     return Math.abs(Math.round(diff));
 }
-function createPayloadHandler({ dispatch, serverActionQueue, subscription, config }) {
+function createPayloadHandler({ dispatch, serverActionQueue, transportAdapter, config }) {
     const subscriptionId = uuid_1.v4();
     let idx = {};
     let patchQueue = {};
@@ -19,7 +19,7 @@ function createPayloadHandler({ dispatch, serverActionQueue, subscription, confi
     let updateDeadline = null;
     let checkInterval;
     function getPayload() {
-        setTimeout(() => subscription.send({ getPayload: config }), 1000);
+        setTimeout(() => transportAdapter.getPayload(config), 1000);
     }
     function camelizeKeys(item) {
         return deepCamelizeKeys_1.default(item, key => uuid_1.validate(key));
@@ -41,7 +41,7 @@ function createPayloadHandler({ dispatch, serverActionQueue, subscription, confi
                 dispatch({ type: `jasonModels/setSubscriptionIds`, payload: { model, subscriptionId, ids } });
             }
             else if (destroy) {
-                dispatch({ type: `${pluralize_1.default(model)}/remove`, payload: id });
+                // Middleware will determine if this model should be removed if it isn't in any other subscriptions
                 dispatch({ type: `jasonModels/removeSubscriptionId`, payload: { model, subscriptionId, id } });
             }
             else {
@@ -87,6 +87,10 @@ function createPayloadHandler({ dispatch, serverActionQueue, subscription, confi
         }
     }
     tGetPayload();
-    return handlePayload;
+    // Clean up after ourselves
+    function tearDown() {
+        dispatch({ type: `jasonModels/removeSubscription`, payload: { subscriptionId } });
+    }
+    return { handlePayload, tearDown };
 }
 exports.default = createPayloadHandler;

data/client/lib/createTransportAdapter.d.ts

@@ -0,0 +1,5 @@
+export default function createTransportAdapter(jasonConfig: any, handlePayload: any, dispatch: any, onConnect: any): {
+    getPayload: (config: any, options: any) => void;
+    createSubscription: (config: any) => void;
+    removeSubscription: (config: any) => void;
+};

data/client/lib/createTransportAdapter.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const actionCableAdapter_1 = __importDefault(require("./transportAdapters/actionCableAdapter"));
+const pusherAdapter_1 = __importDefault(require("./transportAdapters/pusherAdapter"));
+function createTransportAdapter(jasonConfig, handlePayload, dispatch, onConnect) {
+    const { transportService } = jasonConfig;
+    if (transportService === 'action_cable') {
+        return actionCableAdapter_1.default(jasonConfig, handlePayload, dispatch, onConnect);
+    }
+    else if (transportService === 'pusher') {
+        return pusherAdapter_1.default(jasonConfig, handlePayload, dispatch);
+    }
+    else {
+        throw (`Transport adapter does not exist for ${transportService}`);
+    }
+}
+exports.default = createTransportAdapter;

data/client/lib/index.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="react" />
 import _useAct from './useAct';
 import _useSub from './useSub';
+import _useEager from './useEager';
 export declare const JasonProvider: ({ reducers, middleware, extraActions, children }: {
     reducers?: any;
     middleware?: any;
@@ -9,3 +10,4 @@ export declare const JasonProvider: ({ reducers, middleware, extraActions, child
 }) => JSX.Element;
 export declare const useAct: typeof _useAct;
 export declare const useSub: typeof _useSub;
+export declare const useEager: typeof _useEager;