More updates to use updated Resource API

Author: kriszyp

docs/developers/applications/README.md

@@ -249,9 +249,13 @@ To define custom (JavaScript) resources as endpoints, we need to create a `resou
 const { Dog } = tables; // get the Dog table from the Harper provided set of tables (in the default database)
 
 export class DogWithHumanAge extends Dog {
-	get(query) {
-		this.humanAge = 15 + this.age * 5; // silly calculation of human age equivalent
-		return super.get(query);
+	static loadAsInstance = false;
+	async get(target) {
+		const record = await super.get(target);
+		return {
+			...record, // include all properties from the record
+			humanAge: 15 + record.age * 5 // silly calculation of human age equivalent
+		};
 	}
 }
 ```
@@ -269,16 +273,22 @@ type Breed @table {
 }
 ```
 
-And next we will use this table in our `get()` method. We will call the new table's (static) `get()` method to retrieve a breed by id. To do this correctly, we access the table using our current context by passing in `this` as the second argument. This is important because it ensures that we are accessing the data atomically, in a consistent snapshot across tables. This provides automatically tracking of most recently updated timestamps across resources for caching purposes. This allows for sharing of contextual metadata (like user who requested the data), and ensure transactional atomicity for any writes (not needed in this get operation, but important for other operations). The resource methods are automatically wrapped with a transaction (will commit/finish when the method completes), and this allows us to fully utilize multiple resources in our current transaction. With our own snapshot of the database for the Dog and Breed table we can then access data like this:
+And next we will use this table in our `get()` method. We will call the new table's (static) `get()` method to retrieve a breed by id. Harper will maintain the current context, ensuring that we are accessing the data atomically, in a consistent snapshot across tables. This provides automatic tracking of most recently updated timestamps across resources for caching purposes. This allows for sharing of contextual metadata (like user who requested the data), and ensure transactional atomicity for any writes (not needed in this get operation, but important for other operations). The resource methods are automatically wrapped with a transaction (will commit/finish when the method completes), and this allows us to fully utilize multiple resources in our current transaction. With our own snapshot of the database for the Dog and Breed table we can then access data like this:
 
 ```javascript
 //resource.js:
 const { Dog, Breed } = tables; // get the Breed table too
 export class DogWithBreed extends Dog {
-	async get(query) {
-		let breedDescription = await Breed.get(this.breed, this);
-		this.breedDescription = breedDescription;
-		return super.get(query);
+	static loadAsInstance = false;
+	async get(target) {
+		// get the Dog record
+		const record = await super.get(target);
+		// get the Breed record
+		let breedDescription = await Breed.get(record.breed);
+		return {
+			...record,
+			breedDescription
+		};
 	}
 }
 ```
@@ -289,9 +299,12 @@ Here we have focused on customizing how we retrieve data, but we may also want t
 
 ```javascript
 export class CustomDog extends Dog {
-	async post(data) {
-		if (data.action === 'add-trick')
-			this.tricks.push(data.trick);
+	static loadAsInstance = false;
+	async post(target, data) {
+		if (data.action === 'add-trick') {
+			const record = this.update(target);
+			record.tricks.push(data.trick);
+		}
 	}
 }
 ```
@@ -300,12 +313,22 @@ And a POST request to /CustomDog/ would call this `post` method. The Resource cl
 
 The `post` method automatically marks the current instance as being update. However, you can also explicitly specify that you are changing a resource by calling the `update()` method. If you want to modify a resource instance that you retrieved through a `get()` call (like `Breed.get()` call above), you can call its `update()` method to ensure changes are saved (and will be committed in the current transaction).
 
-We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this, but we may want to separate the logic so these methods can be called separately without authorization checks. The [Resource API](../../technical-details/reference/resource.md) defines `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete`, or to easily configure individual capabilities. For example, we might do this:
+We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this. For example, we might do this:
 
 ```javascript
 export class CustomDog extends Dog {
-	allowUpdate(user) {
-		return this.owner === user.username;
+	static loadAsInstance = false;
+	async post(target, data) {
+		if (data.action === 'add-trick') {
+			const context = this.getContext();
+			if (record.owner !== context.user?.username) {
+				throw new Error('Can not update this record');
+			}
+			// if we now want to skip the default permission checks, we can turn that off:
+			target.checkPermissions = false;  
+			const record = this.update(target);
+			record.tricks.push(data.trick);
+		}
 	}
 }
 ```
@@ -329,8 +352,8 @@ We can also directly implement the Resource class and use it to create new data
 ```javascript
 const { Breed } = tables; // our Breed table
 class BreedSource extends Resource { // define a data source
-	async get() {
-		return (await fetch(`http://best-dog-site.com/${this.getId()}`)).json();
+	async get(target) {
+		return (await fetch(`http://best-dog-site.com/${target}`)).json();
 	}
 }
 // define that our breed table is a cache of data from the data source above, with a specified expiration

docs/technical-details/reference/resource-migration.md

@@ -11,9 +11,8 @@ The updated Resource API is enabled on a per-class basis, by setting static `loa
   * A `target` property of `checkPermission` indicates that a method should check the permission before of request before proceeding. The default instance methods provide the default authorization behavior.
     * This supplants the need for `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete` methods, which shouldn't need to be used (and don't provide the id of the target record).
 * Any data from a POST, PUT, and PATCH request will be available in the second argument. This reverses the order of the arguments to `put`, `post`, and `patch` compared to the legacy Resource API.
-* Context is tracked using asynchronous context tracking, and will automatically be available to calls to other other resources.
-* The method will return a `Updatable` object (instead of a Resource instance), which provides properties mapped to a record, but these properties can be updated and changes will be saved when the transaction is committed.
-* The `update` methods will return an `Updatable` object (instead of a Resource instance), which provides properties mapped to a record, but these properties can be updated and changes will be saved when the transaction is committed.
+* Context is tracked using asynchronous context tracking, and will automatically be available to calls to other resources. This can be disabled by setting `static explicitContext = true`, which can improve performance. 
+* The `update` method will return an `Updatable` object (instead of a Resource instance), which provides properties mapped to a record, but these properties can be updated and changes will be saved when the transaction is committed.
 
 Here are examples of how to convert/upgrade to the non-instance binding Resource API:
 Previous code with a `get` method:
@@ -45,9 +44,9 @@ export class MyData extends tables.MyData {
       // we can retrieve another record from this table directly with this.get/super.get or with tables.MyData.get
       record = await super.get(idWithQuery);
     } else {
-      record = await super.get(target); // we can just directly use the query as well
+      record = await super.get(target); // we can just directly use the target as well
     }
-    // the record itself is frozen, but we can copy/assign to a new record with additional properties if we want
+    // the record itself is frozen, but we can copy/assign to a new object with additional properties if we want
     return { ...record, newProperty: 'value' };
   }
 }
@@ -74,6 +73,7 @@ export class MyData extends tables.MyData {
 		// to perform/call authorization explicitly in direct get, put, post methods rather than using allow* methods.
 		if (!this.getContext().user) throw new Error('Unauthorized');
 		target.checkPermissions = false; // authorization complete, no need to further check permissions below
+		// target.checkPermissions is set to true or left in place, this default get method will perform the default permissions checks
 		return super.get(target); // we can just directly use the query as well
 	}
 }
@@ -98,14 +98,13 @@ export class MyData extends tables.MyData {
 ```
 Updated code:
 ```javascript
-
 export class MyData extends tables.MyData {
   static loadAsInstance = false; // opt in to updated behavior
   // IMPORTANT: arguments are reversed:
   async post(target, data) {
     let record = await this.get(data.id);
     if (record) { // update a property
-      const updatable = await this.update(data.id);
+      const updatable = await this.update(data.id); // we can alternately pass a target to update
       updatable.someProperty = 'value';
       // or
       this.patch(data.id, { someProperty: 'value' }, this);