At last, just Ids

As I'm using AIRport APIs I'm realizing that the existing records passed into AIRport APIs need to be verified as such. This is leading me to finalize the Id API for AIRport.

Duality of Ids

Id validation is usually taken care of automatically. If you are doing an update operation and the key for the updated or referenced entity is not found, the update operation will fail in the database.

AIRport stores all records in memory (in Web version and in app server caches). To save on the RAM (required to store tables and indexes) AIRport uses local numeric Ids (or just local ids) to identify all of the objects within the local database.

For AIRport Clients and Apps each object contains a computed GUID field (previously described as "uuId"). The Client is expected to use GUIDs and ignore local Ids.  This will cause to bugs if inexperienced developers use local Ids. This is a likely scenario since currently local ids are named "id".

Renaming Ids

To reduce developer confusion the "id" field is now renamed to "_localId".  This accurately describes the purpose of this field - it is there to link records together in the local database (often in memory).  The name also doesn't immediately stand out as something to be used as an identifier. The "actorRecordId" is also numeric but is unique for an actor within a repository and hence is globally unique. It is now renamed to "_actorRecordId" to signify its "internal usage" nature.

To make things clear the GUID  field is now renamed to be "id". It is globally unique for all Entity records and naming it "id" clearly indicates to the user that it is what should be used as the identifier.

Checking Entity Existence

The renaming "GUID" to just "id" also clarifies record existence checks. AIRport will automatically perform this functionality (just like raw relational databases), at the cost of making additional queries:

On save - TODO

AIRport will create an in-memory cache for the top level transaction (also used by all nested transactions). All objects passed into "save" operations (including nested objects) will be added to this cache. At the time of "save" operation, AIRport will scan the passed in object graph and mark all objects not yet proven to already exist. It then will query for those objects by GUIDs and update numeric ids in the passed in object graph (with what is present in the local database). If there are non-existing objects the "save" operation will throw an Error.

As an additional bonus, this will verify that all referenced repositories (that are pulled in) are loaded into the local database.

On query - done (updated 7/4/2022)

All entity query operations now find all all of the Repositories and Actors (along with Users and their locations, since that is likely to be used in UIs) present in the passed-in object graph. That's just two distinct queries ( regardless of the side of the object graph) and won't have a significat impact on AIRport performance.