actionstore 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a5099e39606b34e15e4a298ba73a6798c7d09bfd5118d40434e0bc6ed217d63
-  data.tar.gz: 062f6d85f3f781c30c3c950c2421bd80693e35c4c20fb7a76d143ad5bd1d2520
+  metadata.gz: 1c94128c58646259de5ca05a0ddfa34011643c0443015ce23459ec4b17ec5a94
+  data.tar.gz: '0971d6f3ac13a40ac0ae568897df4ec40cd4730bfc58bc5778091ea2cddc24b9'
 SHA512:
-  metadata.gz: ce0944a422441bc62c5108850ecd23415a26e02b6211865de9730264ec0ebb8aa9c2abb2b24c84efde29f569a7dcff87fa72add19605458f05cddb07fa500aa8
-  data.tar.gz: 1a54c2f513d7fa7766b5dadcfba6f7705168848ecd622d2558e48a1a4a88a0cd7a2a81e80c7be66a1cd52ab15cf74ec5ab6186d325a74df0f70797fe184dee39
+  metadata.gz: 31b3eedd570fd0b54362f560f594843e198a444c9d915da7c610dead9c1dd8bd0c324edd1dba328b5c74cf5b6ed8914c00e13a949352e9abdd386bd706529b55
+  data.tar.gz: a5298c7bc3e1519f64543cc0bce8a25d647b73476db78d866eb5252abb36add17d50038b0266ceb2b4e07431809c5e38b3fd99bd76050bcab4d7456126e451d1

data/README.md

@@ -0,0 +1,184 @@
+# ActionStore
+
+[![CircleCI](https://circleci.com/gh/buhrmi/actionstore.svg?style=shield)](https://circleci.com/gh/buhrmi/actionstore)
+[![Gem Version](https://badge.fury.io/rb/actionstore.svg)](https://rubygems.org/gems/actionstore)
+[![npm version](https://badge.fury.io/js/@buhrmi%2Factionstore.svg)](https://www.npmjs.com/package/@buhrmi/actionstore)
+
+ActionStore allows you to push data directly into Svelte stores via ActionCable. Here's an [introductory blog post](https://dev.to/buhrmi/actionstore-real-time-svelte-stores-for-rails-4jhg).
+
+> **Note**
+> There's currently no way to configure the Websocket URL. At the moment it only works in the browser, with the default Rails configuration, on the same origin.
+
+## Installation
+
+### Ruby gem
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'actionstore'
+```
+
+And then execute:
+
+    $ bundle install
+
+### Npm package
+
+Install the package:
+
+    $ yarn add @buhrmi/actionstore
+
+## Usage
+
+Below are some usage examples. For more condensed details, see the [API section](#API).
+
+### Subscribe to a database record
+
+In a Svelte component:
+
+```html
+<script>
+import {subscribe} from '@buhrmi/actionstore'
+
+// you need the signed global id of the record you want to subscribe to
+export let user_sgid
+
+// Calling `subscribe` will set up an ActionCable subscription and return a 
+// Svelte store which you can push to
+const user = subscribe(user_sgid)
+</script>
+
+{#if $user}
+  Hello {$user.name}
+{/if}
+```
+
+Now you can populate the store from the backend:
+
+```ruby
+class User < ApplicationRecord
+  has_actionstore
+
+  def subscribed channel
+    push_update name: 'Rich Harris'
+  end
+end
+```
+
+### Multiple stores
+
+You can also push data into stores specified by an id
+
+```js
+import {subscribe,store} from '@buhrmi/actionstore'
+export let user_sgid
+const user = subscribe(user_sgid)
+
+// Use the store() method to get an ActionStore by id
+const messages = store('messages')
+
+```
+
+Now you can push into the "messages" store from the backend
+
+```ruby
+user.push_append_into 'messages', text: 'hello'
+```
+
+### Autopush changes
+
+You can automatically sync record changes to the store.
+
+```ruby
+class User < ApplicationRecord
+  has_actionstore
+  
+  # this will only push changed attributes
+  after_update_commit -> { push_update saved_changes.transform_values(&:last) }
+ end
+```
+
+### Perform actions
+
+With ActionStore you can define actions directly on the model and call them from the frontend.
+
+```js
+const user = subscribe(user_sgid)
+user.perform 'say_hello', 'thomas'
+```
+
+```ruby
+class User
+  def perform_say_hello channel, name
+    puts "Hello #{name}"
+  end
+end
+```
+
+### Trigger events
+
+```js
+const user = subscribe(user_sgid)
+user.on('show_alert', function(data) {
+  window.alert(data)
+})
+```
+
+```ruby
+user.push_event 'show_alert', 'Boo!'
+```
+
+
+
+## API
+
+ActionStore consists of two parts, the frontend (Javascript) part and the backend (Ruby) part. Find details below.
+
+### Javascript
+
+The `@buhrmi/actionstore` package exports the following functions:
+
+`const someStore = subscribe(sgid, initial=null, storeId=sgid)` - Sets up a new subscription to the record with the specified global id. You can optionally pass a storeId. If a new subscription with the same storeId is created, the old subscription will be cancelled and removed.
+
+`const someStore = store(storeId, initial=null)` - Gets the store with the specified id.
+
+#### Stores
+
+ActionStores are Svelte stores augmented with the following functions:
+
+`someStore.on(event, handler)` - Sets up an event handler for server-sent events
+
+`someStore.perform(action, ...arguments)` - Will call the equivalent `perform_[action]` method on the subscribed model.
+
+### Ruby
+
+Adding `has_actionstore` to your ActiveRecord model (or anything else that can be located via [Global ID](https://github.com/rails/globalid)) will create the following instance methods and behavior
+
+#### Pushing Data
+
+`record.push_append(data)` - Append data to an array in the default store
+
+`record.push_update(changes)` - Updats fields of an object in the default store
+
+`record.push_update_by(key, value, changes)` - Updates fields of an object in the default store, identified by the specified key and value
+
+`record.push_append_into(store_name, data)` - Append data to an array in a specified store
+
+`record.push_update_into(store_name, changes)` - Update fields of an object in a specified store
+
+`record.push_update_by_into(store_name, key, value, changes)` - Update fields of an object in a specified store, identified by the specified key and value
+
+#### Triggering events
+
+`record.push_event(event_name, data)` - Trigger an event on the default store
+
+`record.push_event_into(store_name, event_name, data)` - Trigger an event on a specified store
+
+#### Actions
+
+Any method on the object that starts with `perform_` can potentially be called from the frontend. The first argument is always the channel that received the action (useful for authentication), followed by the arguments passed from the frontend.
+
+#### Callbacks
+
+Whenever a subscription is created or destroyed, the `subscribed(channel)` or `unsubscribed(channel)` method is called on the subject (if defined).

data/lib/actionstore/version.rb

@@ -1,3 +1,3 @@
 module Actionstore
-  VERSION = "0.3.0"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actionstore
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Stefan Buhrmester
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-10-06 00:00:00.000000000 Z
+date: 2022-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -31,6 +31,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - Rakefile
 - lib/actionstore.rb
 - lib/actionstore/actionstore.rb
@@ -61,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
 summary: Push data into Svelte stores from Rails