slender_data 0.5.0 → 0.6.0

data/app/assets/javascripts/slender_data/persistence_manager.coffee

@@ -1,271 +1,152 @@
-#= require slender_data/ajax_loader
-#= require slender_data/indexed_cache
+#= require slender_data/brest_loader
+#= require slender_data/entry_store
+#= require slender_data/query_cache
+#= require slender_data/parameterizable
 #= require slender_data/tools
 
-# Provides persistence services for data models.
+# Provides server-backed persistence services for JSON data models.
 #
-# This class operates against a standard RESTful data API, whole path is given in params.url.
-# In addition to the standard RESTful routes, the data API is expected to support these methods for performance reasons:
-# * DELETE /entries: Delete a whole batch of entries at once. The ids of the entries to delete are given as a JSON hash in the body of the request.
-# *
+# This class operates against a BRESTful data API.
 #
-# Terminology:
-# * "load" methods are high level public API. They try to satisfy the requests from the local cache, and load the data from the server on demand.
-# * "get" methods access only the local cache, and return their results synchronously.
-# * "fetch" methods encapsulate accessing remote resources.
-# * "create" creates a given entry on the server
-# * "add" adds the given entry to the clientside cache.
-class slender_data.PersistenceManager
+# Operations that act directly on entries, and are always given entries
+# (add_to_cache, create, update) are given the entries directly.
+# Operations that need to look up entries before doing something with them,
+# and don't necessarily need the full entry to do that, (delete, get, load)
+# are given queries.
+class slender_data.PersistenceManager extends slender_data.Parameterizable
 
   constructor: (params) ->
+    super params
 
-    # Copy of the data as it is on the server.
-    @server_data = new slender_data.IndexedCache
+    # Stores the data objects here on the client,
+    # and tracks changes that are made to them here.
+    @entry_store = new slender_data.EntryStore params
 
-    # Copy of the data as it is on the client.
-    @client_data = new slender_data.IndexedCache
+    # Loads/stores data to/from the server.
+    @server_api = new slender_data.BrestLoader params
 
-    # The base url on the server. Expected to be a fully RESTful API.
-    @base_url = params.url
 
-    # Name of the 'id' column for models.
-    @key = params.key or 'id'
+  # Adds the given serverside entry to the entry store.
+  # Does not update the server.
+  # Does not provide an editable version of the data.
+  # Call "get" to get one.
+  add_to_cache: (entry) ->
+    @entry_store.add entry
 
-    # Name of the model class (e.g. "user").
-    @model_name = params.model_name
 
-    # For handling parallel requests to the server.
-    @loader = new slender_data.AjaxLoader { cache: no }
+  # Adds the given serverside entries to the entry store.
+  add_many_to_cache: (entries) ->
+    @entry_store.add_many entries
 
 
-  # Adds the given entry to the clientside caches.
-  # Returns the entry to be used by the client.
-  add: (entry) ->
-    @server_data.add entry
-    client_entry = slender_data.clone_hash entry
-    @client_data.add client_entry
-    client_entry
-
-
-  # Adds the given data objects to the server cache.
-  add_all: (entries) ->
-    @add(entry) for entry in entries
-
-
-  # Returns an array containing only the changed objects.
-  # Each object contains only the changed columns + key column.
-  changed_objects_columns: (objects) ->
-    slender_data.tap [], (result) =>
-      for object in objects
-        diff = slender_data.object_diff @server_data.get(object[@key]), object
-        continue if slender_data.object_length(diff) == 0
-        diff[@key] = object[@key]
-        result.push(diff)
-
-
-  # Returns the URL to access the collection of objects.
-  collection_url: ->
-    "#{@base_url}.json"
-
-
-  # Creates the given object on the server.
-  create: (obj, success_callback, error_callback) ->
-    data = {}
-    data[@model_name] = obj
-
-    jQuery.ajax
-      url: @collection_url()
-      type: 'POST'
-      data: data
-      success: (server_response) =>
-        server_obj = server_response[@model_name]
-        @server_data.add server_obj
-        success_callback server_obj
-      error: (xhr) =>
-        error_callback(xhr.responseText) if error_callback
-
-
-  # TODO: create_many
-
-
-  # Deletes the given object from the server.
-  delete: (obj, success_callback, error_callback) ->
-    @client_data.remove obj
-    @server_data.remove obj
-    jQuery.ajax
-      url: @entry_url(obj)
-      type: 'DELETE'
-      success: ->
-        success_callback() if success_callback?
-      error: (xhr) ->
-        error_callback(xhr.responseText) if error_callback
-
-
-  # Deletes the given objects from the server.
-  delete_many: (object_ids, success_callback, error_callback) ->
-    @client_data.remove_many object_ids
-    @server_data.remove_many object_ids
-    jQuery.ajax
-      url: @base_url
-      type: 'DELETE'
-      data: {ids: object_ids}
-      success: ->
-        success_callback() if success_callback?
-      error: (xhr) ->
-        error_callback(xhr.responseText) if error_callback
-
-
-  # Returns the url to access a single entry.
-  entry_url: (entry) ->
-    "#{@base_url}/#{entry[@key]}.json"
-
-
-  # Returns the url to access the collection of entries.
-  entries_url: ->
-    "#{@base_url}.json"
-
-
-  # Fetches the entry with the given key from the server.
-  # Adds it to the clientside cache.
-  fetch: (key, success_callback) ->
-    @loader.get "#{@base_url}/#{key}.json", (server_response) =>
-      client_entry = @add server_response[@model_name]
-      success_callback client_entry
-
-
-  # Loads all objects from the server.
-  # Provides the given params as parameters to the GET request.
-  fetch_many: (data, success_callback, error_callback) ->
-    data.ids = data.ids.join(' ') if data.ids
-    jQuery.ajax
-      url: @collection_url()
-      cache: no
-      data: data
-      success: (data) =>
-        @add_all data
-        success_callback(data) if success_callback
-      error: (xhr) ->
-        error_callback(xhr.responseText) if error_callback
-
+  # Creates the described object on the server.
+  #
+  # Returns nothing. Call "get" to get an editable copy of the object.
+  create: (entry, callback) ->
+    @server_api.create entry, (server_response) =>
+      server_entry = server_response[@entry_name]
+      @add_to_cache server_entry
+      callback(@get entry: server_entry) if callback
+
+  # Creates the described objects on the server.
+  #
+  # Returns nothing. Call "get_many" to get editable copies.
+  create_many: (entries, callback) ->
+    @server_api.create_many entries, (server_response) =>
+      @add_many_to_cache server_response[@entries_name]
+      callback() if callback
 
-  # Returns the cached object with the given key, if one exists in the cache.
-  # Returns undefined if no object with this key exists in the cache.
-  get: (key) =>
 
-    # Try to use client_data cache.
-    client_obj = @client_data.get key
-    return client_obj if client_obj
+  # Deletes the described entry from the server.
+  delete: (query, callback) ->
+    query = query
+    @server_api.delete query, (server_response) =>
+      @entry_store.delete server_response
+      callback(server_response) if callback
 
-    # No data in client cache --> try to use server cache.
-    server_obj = @server_data.get key
-    if server_obj
-      client_obj = slender_data.clone_hash server_obj
-      @client_data.add client_obj
-      return client_obj
 
-    # Object not found in client or server cache.
-    undefined
+  # Deletes the described entries from the server.
+  delete_many: (multi_query, callback) ->
+    @server_api.delete_many multi_query, (server_response) =>
+      @entry_store.delete_many server_response
+      callback(server_response) if callback
 
 
-  # Returns all entries that are in the cache,
-  # and the ids of all entries that are not cached.
-  get_many: (ids) ->
-    entries = []
-    missing_ids = []
-    for id in ids
-      if (entry = @get id)
-        entries.push entry
-      else
-        missing_ids.push id
-    [entries, missing_ids]
+  # Synchronously returns the described entry from the cache,
+  # or undefined if there is no cached entry.
+  # Does not query the server.
+  get: (query) =>
+    @entry_store.get query
 
 
-  # Returns the entry with the given key.
-  load: (key, success_callback) ->
+  # Synchronously returns all described entries that are found in the cache,
+  # and a MultiQuery for the entries that are not there.
+  get_many: (multi_query) ->
+    @entry_store.get_many multi_query
 
-    # Try to load from cache.
-    return success_callback(entry) if entry = @get key
 
-    # No data on client --> load from server.
-    @fetch key, success_callback
+  # Returns the described entry from any available data source.
+  load: (query, callback) ->
+    query = @_querify_single query
+    if (entry = @get query)
+      callback entry
+    else
+      @server_api.read query, (server_response) =>
+        @add_to_cache server_response[@entry_name]
+        callback @get(server_response)
 
 
-  # Loads all entries with the given ids.
-  load_many: (ids, success_callback) ->
-    [cached_entries, missing_ids] = @get_many ids
-    if missing_ids.length == 0
+  # Loads all described entries from any available data source.
+  load_many: (multi_query, callback) ->
+    cache_result = @get_many multi_query
+    if cache_result.missing.empty()
       # All requested entries found in cache --> return them immediately.
-      success_callback(cached_entries)
+      callback cache_result.found
     else
-      # Entries missing --> load them from the server.
-      @fetch_many missing_ids, (server_snippets) ->
-        success_callback $.merge(cached_entries, server_snippets)
+      # Some entries were not found in the cache --> load them from the server.
+      @server_api.read_many cache_result.missing, (server_response) =>
+        @add_many_to_cache server_response[@entries_name]
+        $.merge cache_result.found, @get_many(server_response).found
+        callback cache_result.found
 
 
-  # Saves the given object.
-  # Does the right thing (create or update) dependent on
-  # whether the object already has a key parameter.
-  save: (obj, success_callback, error_callback) ->
-    if obj[@key]?
-      @update obj, success_callback, error_callback
-    else
-      @create obj, success_callback, error_callback
-
+  # Merges the entries described by the given ids
+  # into a new entry with the given data.
+  merge: (old_entry_ids, new_entry_data, callback) ->
+    @server_api.merge old_entry_ids, new_entry_data, (server_response) =>
+      @entry_store.delete_many ids: old_entry_ids
+      @entry_store.add server_response[@entry_name]
+      callback @get(server_response)
 
-  # TODO: save_many
 
   # Updates the given object.
   #
-  # The given object must exist on the server already,
-  # and have a proper value in the key attribute.
-  update: (obj, success_callback, error_callback) ->
-
-    # Handle updating several objects.
-    return @update_many(obj, success_callback, error_callback) if $.type(obj) == 'array'
-
-    # Create a new hash, containing only the changed attributes between obj and it's replica in @server_data.
-    diff_obj = slender_data.object_diff @server_data.get(obj[@key]), obj
-    if slender_data.object_length(diff_obj) == 0
-      success_callback obj if success_callback
-      return
-
-    # Send to server
-    data = {}
-    data[@model_name] = diff_obj
-    jQuery.ajax
-      url: @entry_url(obj)
-      type: 'PUT'
-      data: data
-      success: (server_response) =>
-        @client_entry = @add server_response[@model_name]
-        success_callback @client_entry if success_callback
-      error: (xhr) ->
-        error_callback(xhr.responseText) if error_callback
+  # The given object must already exist on the server,
+  # and have a proper value in the id attribute.
+  update: (entry, callback) ->
+    if (changes = @entry_store.entry_changes entry)
+      # There are changes --> update the server.
+      @server_api.update changes, (server_response) =>
+        @entry_store.add server_response[@entry_name]
+        callback(server_response) if callback
+    else
+      # No changes --> call the callback directly.
+      callback_data = {}
+      callback_data[@entry_name] = entry
+      callback(callback_data) if callback
 
 
   # Bulk-updates the given objects.
-  # All the existing objects must exist on the server already,
-  # and have a value in the key attribute.
-  update_many: (objects, success_callback, error_callback) ->
-
-    # Find all objects that have been changed on the client.
-    diff_objects = @changed_objects_columns objects
-
-    # Send to server
-    data = {}
-    data["#{@model_name}s"] = diff_objects
-    jQuery.ajax
-      url: @entries_url()
-      type: 'PUT'
-      data: data
-      success: (server_response) =>
-        server_objects = server_response["#{@model_name}s"]
-        client_objects = (for server_object in server_objects
-          @server_data.add server_object
-          client_object = slender_data.clone_hash server_object
-          @client_data.add client_object
-          client_object)
-        success_callback(client_objects) if success_callback
-      error: (xhr) ->
-        error_callback(xhr.responseText) if error_callback
+  # All the existing objects must already exist on the server,
+  # and have a value in the id attribute.
+  update_many: (entries, callback) ->
+    if (changes = @entry_store.entries_changes entries).length > 0
+      # There are changes --> update the server.
+      @server_api.update_many changes, (server_response) =>
+        @entry_store.add_many server_response[@entries_name]
+        callback(server_response) if callback
+    else
+      callback_data = {}
+      callback_data[@entries_name] = entries
+      callback(callback_data) if callback
 

data/app/assets/javascripts/slender_data/queries/base_query.coffee

@@ -0,0 +1,32 @@
+#= require slender_data/parameterizable
+
+
+# Abstract base class for queries.
+class slender_data.BaseQuery extends slender_data.Parameterizable
+
+  # query_data: a hash containing the data of the query.
+  constructor: (query_data, params) ->
+    super params
+
+    # Whether to return only full entries.
+    #
+    # If false, partial entries are also permitted as results.
+    @full = query_data.full
+
+    # The query that was given in the constructor.
+    @given_query = query_data
+
+
+  # Returns the key used in the given query.
+  selector_name: ->
+    @_selector_name_result or= Object.keys(@given_query)[0]
+
+
+  # Returns the given selector value.
+  selector_value: ->
+    @given_query[@selector_name()]
+
+
+  # Returns the hash representation of this query.
+  to_hash: ->
+    @given_query

data/app/assets/javascripts/slender_data/queries/multi_query.coffee

@@ -0,0 +1,91 @@
+#= require slender_data/queries/base_query
+#= require slender_data/queries/single_query
+
+
+# Represents a query for multiple entries at once.
+class slender_data.MultiQuery extends slender_data.BaseQuery
+
+  constructor: (query, params) ->
+    super query, params
+
+    # Cache for the currently known entry ids of this query.
+    # If undefined, this value will be calculated later on demand.
+    #
+    # Don't use this field directly. Use ids() to access it.
+    @_ids_value = undefined
+
+    # Cache for the currently known entries of this query.
+    # If undefined, this value will be calculated later on demand.
+    #
+    # Don't use this field directly. Use entries() to access it.
+    @_entries_value = undefined
+
+    @_store_multi_query query
+
+    # Allows to access the entries through their domain name,
+    # i.e. @users()
+    @[@entries_name] = @entries
+
+    # Allows to access the entry ids through their domain name,
+    # i.e. usernames()
+    @[@ids_name] = @ids
+
+
+  # Returns whether this multi-query describes no entries.
+  empty: ->
+    @ids().length is 0
+
+
+  # Returns the corresponding entries for this query.
+  entries: ->
+    @_entries_value or throw new Error("Cannot provide #{@entries_name} for a #{@ids_name} query")
+
+
+  # Returns the ids for this query.
+  ids: ->
+    @_ids_value or= (entry[@id_name] for entry in @entries())
+
+
+  # Creates a new MultiQuery with the same configuration as this one,
+  # but the given selector value.
+  replicate: (new_selector_value) ->
+    replica_query = slender_data.clone_hash @given_query
+    replica_query[@selector_name()] = new_selector_value
+    new @multi_query_class replica_query, @params
+
+
+  # Converts the given multi-key name into the corresponding single key name.
+  single_selector_name: ->
+    unless @_single_selector_name_result
+      if @selector_name() is @entries_name
+        @_single_selector_name_result = @entry_name
+      else
+        @_single_selector_name_result = @selector_name().substring 0, @selector_name().length-1
+    @_single_selector_name_result
+
+
+  # Stores the given data.
+  _store_multi_query: (multi_query) ->
+    switch @selector_name()
+      when 'entries'
+        @_entries_value = multi_query.entries
+      when @entries_name
+        @_entries_value = multi_query[@entries_name]
+      when 'ids'
+        @_ids_value = multi_query.ids
+      when @ids_name
+        @_ids_value = multi_query[@ids_name]
+      else
+        throw new Error("Unknown multi-query key name: #{@selector_name()}")
+
+
+  # Converts the given multi-query into an array of single queries.
+  transpose: ->
+    result = []
+    for selector in @selector_value()
+      single_query = {}
+      single_query[@single_selector_name()] = selector
+      single_query.full = yes if @full
+      result.push new @single_query_class(single_query, @params)
+    result
+