reactiverecord

    0.8.11 • Public • Published

    Reactive Record

    npm version npm downloads

    Communicate with JSON APIs in React

    What does it do?

    All on its own, Reactive Record is a front-end-only Object Data-store Mapping (ODM) implementation that lets you interact with RESTful APIs. By defining models on the front end and integrating closely with the popular state container, Redux, Reactive Record offers a Ruby-on-Rails-esque, Active Record-ey syntax. Think Active Record for JavaScript. Reactive Record is agnostic to back-end architecture. It's built for APIs which respond to GET/POST/POST/DELETE requests for resources identified by predefined keys, so Rails, Express, Sinatra, CouchDB UNAMEIT! Reactive Record allows you to write syntax like this:

    const userAddress = new Address()
    
    userAddress.address1 = "1100 Congress Ave"
    userAddress.city = "Austin"
    userAddress.state = "TX"
    
    userAddress.save()
    /* 
      REQUEST:
        Method: POST 
        URL: /api/addresses
        Data: {
          "address1": "1100 Congress Ave",
          "city": "Austin",
          "state": "TX"
        }
      RESPONSE:
        Status: 201 Created
        Body: {
          "_id": "583132c8edc3b79a853b8d69",
          "createdAt": "2016-11-20T05:21:12.988Z",
          "updatedAt": "2016-11-20T05:21:12.988Z",
          "userId": "580432279153ea2679095acd",
          "address1": "1100 Congress Ave",
          "city": "Austin",
          "state": "TX"
        }
    */
    userAddress.id
    // Returns 583132c8edc3b79a853b8d69
    userAddress.destroy()
    // Does what you would expect (A DELETE request to the same resource)
    

    What does it look like?

    Reactive Record comes with 3 extremely helpful React components, and one higher order component, which allow you to create, read, update and delete API resources. Those components are Member, Collection, Form and validated.

    import ReactiveRecord, { Member, Collection } from "reactiverecord"
    const Post = ReactiveRecord.model("Post")
    
    function Posts() {
      return (
        <Collection for={Post} where={status: "published"}>
          { posts => (
            <div className="post-excerpts">
              {posts.map( post => <PostExcerpt resource={post} /> )}
            </div>
          )}
        </Collection>
      )
    }
    
    function FullArticle({ params:{ id } }) {
      return (
        <Member for={Post} find={parseInt(id)}>
          { post => (
            <div className="the-content">
              <h1>{post.title}</h1>
              <small>Published: {post.createdAt}</small>
              <div>{post.content}</div>
            </div>
          )}
        </Member>
      )
    }
    

    Using this pattern, you get an API request to /posts?status=published, or /posts/:id, and inside the function as children component, you'll receive exactly those API resources, but as #<Post> Reactive Record model instances. So you can do post.title and post.updateAttributes({ status: "unpublished" }). If you're used to Redux reducers, you're done writing them for your data. You're done writing mapStateToProps, writing mapDispatchToProps and that sort of thing. You can stop writing boileplate functions and know this is an extremely optimized way of organizing your data.

    Installation

    npm install --save reactiverecord
    

    Prerequisites

    This library was made to solve problems in our project stack at Rentalutions (insert buzz words: React/Redux/Webpack/ES6). The only real assumptions are:

    • You use Redux (a single store) to manage your state
    • You use React, and React Redux
    • Your JavaScript build can transpile ES6 to current JavaScript.

    If you're coming from a Ruby-on-Rails background, this library is for you. It's somewhat opinionated, and borrows a lot of the same method names from Active Record. It borrows schema definitions from the Mongoose, for those of you who have worked with MongoDB.

    Minimum Setup

    Defining Models

    /* In a file like /models/Story.js */
    import ReactiveRecord, { Model } from "reactiverecord"
    class Story extends Model {
      static schema = {
        title: String,
        body: String,
        status: {
          default: "published",
          tyle: String
        },
        userId: String,
        _timestamps: true
      }
    }
    export default ReactiveRecord.model("Story", Story);
    

    In your reducers setup

    // In a file like /reducers.js
    import { combineReducers } from "redux"
    import ReactiveRecord, { reducer } from "reactiverecord"
    ReactiveRecord.setAPI({ prefix: "/api" }) /* optional */
    import "models"
    export default combineReducers({
      models: reducer.call(ReactiveRecord) /* call it models or anything */
      ...yourOtherReducers
    })
    

    In your store setup

    // In a file like /store.js
    import { createStore, applyMiddleware, compose } from "redux"
    import reducer from "./reducers"
    import ReactiveRecord, { middleware } from "reactiverecord"
    export default createStore(
      reducer,
      compose(
        applyMiddleware(
          middleware.call(ReactiveRecord),
          ...yourOtherMiddlewares
        )
      )
    );
    

    In your app

    import ReactiveRecord from "reactiverecord";
    const Story = ReactiveRecord.model("Story"),
    
    const newStory = new Story;
    newStory.save().then(savedRecord=>(this.setState({ ...savedRecord }));
    // Also works ...
    Story.create({ title: "A working title", body: "Once upon a time..."})  // Makes an API request
      .then(savedRecord=>(this.setState({ ...savedRecord }));  // Returns a promise ... as do the following methods
    newStory.updateAttribute("title", "A working title") // Makes an API request
    newStory.updateAttributes({ title: "A working title", body: "Once upon a time..."})  // Makes an API request
    
    newStory.destroy() // Makes an API request
    
    Story.all() // Makes an API request to the model's index, returns array of records
    Story.find("583132c8edc3b79a853b8d69") // Makes an API request to this resource, returns single record
    
    // Passing extra URL query parameters
    Story.all({month:"05", year:2017}) // Makes an API request to /stories?month=05&year=2017
    Story.all("?month=05&year=2017") // Also works
    Story.find("first-post", { include_comments: true }) // Makes an API request to /stories/first-post?include_comments=true
    Story.find("first-post", "?include_comments=true") // Also works
    // Use cases for extra query params
    Search.load({q: "Am I being detained?"}) // Generates /search?q=Am%20I%20being%20detained%3F
    

    API

    Why isn't there a v1.0 yet?

    Once we fully document this API, we'll release version 1.

    ReactiveRecord

    Reactive Record's default export is a new instance (new ReactiveRecord()). It's also available as a named export ReactiveRecord, though it's much easier to just use the default export.

    ReactiveRecord.prototype.model()

    Define and retrieve Models with this method. A model must be registered with ReactiveRecord in order to access it later.

    /* Save a User model */
    class User extends Model {}
    ReactiveRecord.model("User", User)
    
    /* Retrieve the User model */
    const User = ReactiveRecord.model("User")
    

    ReactiveRecord.prototype.setAPI()

    Reactive Record uses fetch as its remote backend. You can register these settings:

    • prefix (default: "") You are able to set a prefix for all API requests. At Rentalutions, we use /api/v2/landlords or /api/v2/tenants as our prefix. So depending on what kind of user you are, your lease index will make a request to /api/v2/tenants/leases
    • delimiter(default: "-") The difference between bank_accounts and bank-accounts in your URLs. If you have a mix of the two, you can use the default delimiter (kebob case), and manually write snake case URLs in your model definitions.
    • headers (default: { "Accept": "application/json", "Content-Type": "application/json" }). Pass in the new headers you'd like to send with every request.
    • patchMode (default: true) This assumes you'd like to only send the changed fields in your update (PUT) requests to a resource. If you only changed a user's first name, no need to send the entire record. Turning this off will send the entire record every time regardless of changes.

    Model

    Model.store

    Model.schema

    Model.create

    Model.destroy

    Model.find

    Model.all

    Model.load

    Model.prototype.diff

    Model.prototype.changedAttributes

    Model.prototype.isPristine

    Model.prototype.isDirty

    Model.prototype.attributeChanged

    Model.prototype.routeFor

    Model.prototype.routeAttributes

    Model.prototype.updateAttributes

    Model.prototype.updateAttribute

    Model.prototype.save

    Model.prototype.destroy

    Model.prototype.reload

    Model.prototype.ReactiveRecord

    Model.prototype.serialize

    reducer

    middleware

    Reactive Record Components

    <Member />

    <Collection />

    <Form />

    combineFormBuilders()

    validated(WrappedComponent)

    Validator

    Sugar

    =================================================== // use React hooks, get rid of Redux and React-Redux // change the way validations work .. make it where the resource holds the // state of everything in forms and is the thing that's validated // use a more declarative component interface, to define routes to instantiate things // make the library way smaller // implement tests // finish documentation

    import ReactiveRecord from 'reactiverecord' ReactiveRecord.model

    Install

    npm i reactiverecord

    DownloadsWeekly Downloads

    261

    Version

    0.8.11

    License

    MIT

    Unpacked Size

    155 kB

    Total Files

    25

    Last publish

    Collaborators

    • kyleramirez
    • cmwilson88