Skip to content

Version 5.0 API Changes

Jump to bottom
Kris Zyp edited this page Jan 26, 2026 · 5 revisions

This document is for planning potential changes for v5.0. We intend for the v5 to be the initial release of Harper that is "sourced" from this repository (as opposed to our old closed source repo). From a semantic versioning perspective, v5.0 isn’t necessarily a big release, but it is a chance to have “breaking” release, that could potentially change some APIs in non-backwards compatible ways. Of course we never want to gratuitously change APIs, and even in major version upgrade, we want to make upgrades as easy as possible. However, as accumulate some APIs or behaviors that are problematic, we may want to start a list of things that we might change in major version update.

  • Only enable SQL with configuration (disable by default). We may consider other ways of more strongly deprecating SQL usage.

  • Table.get() and instance.get() should return the read-only frozen record that has directly enumerable properties (unless explicit opt-out with loadAsInstance=true). And we should use Table.update() to get a mutable interface to the data.

  • Despite claims in the documentation, we will not make the static loadAsInstance=false signature for instance.post(target, data) and instance.put(target, data) the default.

  • Table.get() should have stricter arguments. Currently, Table.get(undefined) returns a query for all entries, which is an easy way to mistakenly trigger a query with something like Table.get(obj.propertyThatMightNotHaveaValue). Queries from Table.get() should be explicit.

  • Add a Table#save() instance method for saving the state of an updating instance.

  • Add getContext() (and possibly getCurrentUser()) function as a top-level function.

  • Having cache tables always resolve to the origin, whenever a record is accessed, has not been popular. Might want to rethink that.

  • Drop or deprecate the start/startOnMainThread functions for extensions (replace with handleComponent).

  • NATS support has already been removed, and is not in this repo.

  • Remove install_node_modules

  • Ensure that all operations return primary key instead of hash_attribute

  • Define sources as a property of the current/extended table class rather than the base Table resource (through closures)

  • Remove blob.save(). It only sets a flag, and misleading because it implies that is actively saving something.

Clone this wiki locally