Documentation fixes

Author: kriszyp

docs/developers/applications/README.md

@@ -321,12 +321,13 @@ export class CustomDog extends Dog {
 	async post(target, data) {
 		if (data.action === 'add-trick') {
 			const context = this.getContext();
+			// if we want to skip the default permission checks, we can turn off checkPermissions:
+			target.checkPermissions = false;
+			const record = this.update(target);
+			// and do our own/custom permission check: 
 			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);
 		}
 	}

docs/technical-details/reference/resource-instance-binding.md

@@ -1,17 +1,17 @@
 # Resource Class with Resource Instance Binding behavior
 
-This document describes the legacy behavior of the Resource class using the instance binding behavior. It is recommended that [updated behavior](./resource.md) instead, but this legacy API is preserved for backwards compatibility.
+This document describes the legacy behavior of the Resource class using the instance binding behavior. It is recommended that you use the [updated behavior of the Resource API](./resource.md) instead, but this legacy API is preserved for backwards compatibility.
 ## Resource Class
 
 ```javascript
 export class MyExternalData extends Resource {
 	static loadAsInstance = true;
-    async get() {
-        // fetch data from an external source, using our id
-        let response = await this.fetch(this.id);
-        // do something with the response
-    }
-    put(data) {
+	async get() {
+		// fetch data from an external source, using our id
+		let response = await this.fetch(this.id);
+		// do something with the response
+	}
+	put(data) {
 		// send the data into the external source
 	}
 	delete() {
@@ -138,8 +138,8 @@ The `query` argument is used to represent any additional query parameters that w
 
 ```javascript
 put(data, query) {
-    let param1 = query?.get?.('param1'); // returns 'value'
-    ...
+	let param1 = query?.get?.('param1'); // returns 'value'
+	...
 }
 ```
 
@@ -340,18 +340,18 @@ This will define the function to use for a computed attribute. To use this, the
 
 ```javascript
 MyTable.setComputedAttribute('computedAttribute', (record) => {
-    return record.attribute1 + record.attribute2;
+	return record.attribute1 + record.attribute2;
 });
 ```
 
 For a schema like:
 
 ```graphql
 type MyTable @table {
-    id: ID @primaryKey
-    attribute1: Int
-    attribute2: Int
-    computedAttribute: Int @computed
+	id: ID @primaryKey
+	attribute1: Int
+	attribute2: Int
+	computedAttribute: Int @computed
 }
 ```
 
@@ -382,7 +382,7 @@ If the source resource implements subscription support, real-time invalidation c
 This property can be set to force the direct URL request target to be mapped to the resource primary key. Normally, URL resource targets are parsed, where the path is mapped to the primary key of the resource (and decoded using standard URL decoding), and any query string parameters are used to query that resource. But if this is turned on, the full URL is used as the primary key. For example:
 ```javascript
 export class MyTable extends tables.MyTable {
-    static directURLMapping = true;
+	static directURLMapping = true;
 }
 ```
 ```http request

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

@@ -6,10 +6,10 @@ The updated Resource API is enabled on a per-class basis, by setting static `loa
 * The `get` method (both static and instance) will directly return the record, a frozen enumerable object with direct properties, instead of a Resource instance.
 * When instance methods are called, there will not be any record preloaded beforehand. And the resource instance will not have properties mapped to a record.
 * All instance methods accept a `target`, an instance of `RequestTarget`, as the first argument, which identifies the target record or query.
-  * The `target` will have an `id` property identifying the target resource, along with target information. The `getId()` method will return `undefined`.
-  * The `target` will provide access to query parameters, search operators, and other directives.
-  * 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).
+	* The `target` will have an `id` property identifying the target resource, along with target information. The `getId()` method will return `undefined`.
+	* The `target` will provide access to query parameters, search operators, and other directives.
+	* 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 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.
@@ -18,37 +18,37 @@ Here are examples of how to convert/upgrade to the non-instance binding Resource
 Previous code with a `get` method:
 ```javascript
 export class MyData extends tables.MyData {
-  async get(query) {
-    let id = this.getId(); // get the id
-    if (query?.size > 0) { // check number of query parameters
-      let idWithQuery = id + query.toString(); // add query parameters
-      let resource = await tables.MyData.get(idWithQuery, this); // retrieve another record
-      resource.newProperty = 'value'; // assign a new value to the returned resource instance
-      return resource;
-    } else {
-      this.newProperty = 'value'; // assign a new value to this instance
-      return super.get(query);
-    }
-  }
+	async get(query) {
+		let id = this.getId(); // get the id
+		if (query?.size > 0) { // check number of query parameters
+			let idWithQuery = id + query.toString(); // add query parameters
+			let resource = await tables.MyData.get(idWithQuery, this); // retrieve another record
+			resource.newProperty = 'value'; // assign a new value to the returned resource instance
+			return resource;
+		} else {
+			this.newProperty = 'value'; // assign a new value to this instance
+			return super.get(query);
+		}
+	}
 }
 ```
 Updated code:
 ```javascript
 export class MyData extends tables.MyData {
-  static loadAsInstance = false; // opt in to updated behavior
-  async get(target) {
-    let id = target.id; // get the id
-    let record;
-    if (target.size > 0) { // check number of query parameters
-      let idWithQuery = target.toString(); // this is the full target with the path query parameters
-      // 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 target as well
-    }
-    // the record itself is frozen, but we can copy/assign to a new object with additional properties if we want
-    return { ...record, newProperty: 'value' };
-  }
+	static loadAsInstance = false; // opt in to updated behavior
+	async get(target) {
+		let id = target.id; // get the id
+		let record;
+		if (target.size > 0) { // check number of query parameters
+			let idWithQuery = target.toString(); // this is the full target with the path query parameters
+			// 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 target as well
+		}
+		// the record itself is frozen, but we can copy/assign to a new object with additional properties if we want
+		return { ...record, newProperty: 'value' };
+	}
 }
 ```
 Here is an example of the preferred approach for authorization: 
@@ -83,34 +83,34 @@ Here is an example of how to convert/upgrade an implementation of a `post` metho
 Previous code with a `post` method:
 ```javascript
 export class MyData extends tables.MyData {
-  async post(data, query) {
-    let resource = await tables.MyData.get(data.id, this);
-    if (resource) { // update a property
-      resource.someProperty = 'value';
-      // or
-      tables.MyData.patch(data.id, { someProperty: 'value' }, this);
-    } else { // create a new record
-      MyData.create(data, this);
-    }
-  }
+	async post(data, query) {
+		let resource = await tables.MyData.get(data.id, this);
+		if (resource) { // update a property
+			resource.someProperty = 'value';
+			// or
+			tables.MyData.patch(data.id, { someProperty: 'value' }, this);
+		} else { // create a new record
+			MyData.create(data, this);
+		}
+	}
 }
 
 ```
 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); // we can alternately pass a target to update
-      updatable.someProperty = 'value';
-      // or
-      this.patch(data.id, { someProperty: 'value' }, this);
-    } else { // create a new record
-      MyData.create(data, this);
-    }
-  }
+	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); // we can alternately pass a target to update
+			updatable.someProperty = 'value';
+			// or
+			this.patch(data.id, { someProperty: 'value' });
+		} else { // create a new record
+			this.create(data);
+		}
+	}
 }
 ```

docs/technical-details/reference/resource.md

@@ -32,12 +32,12 @@ You can create classes that extend `Resource` to define your own data sources, t
 ```javascript
 export class MyExternalData extends Resource {
 	static loadAsInstance = false; // enable the updated API
-    async get(target) {
-        // fetch data from an external source, using our id
-        let response = await this.fetch(target.id);
-        // do something with the response
-    }
-    put(target, data) {
+	async get(target) {
+		// fetch data from an external source, using our id
+		let response = await this.fetch(target.id);
+		// do something with the response
+	}
+	put(target, data) {
 		// send the data into the external source
 	}
 	delete(target) {
@@ -136,7 +136,6 @@ The `target` object represents the target of a request and can be used to access
 class extends Resource {
 	static loadAsInstance = false;
 	get(target) {
-		// note that query will only exist (as an object) if there is a query string
 		let param1 = target.get('param1'); // returns 'value'
 		let id = target.id; // returns 'some-id'
 		let path = target.pathname; // returns /some-id
@@ -351,18 +350,18 @@ This will define the function to use for a computed attribute. To use this, the
 
 ```javascript
 MyTable.setComputedAttribute('computedAttribute', (record) => {
-    return record.attribute1 + record.attribute2;
+	return record.attribute1 + record.attribute2;
 });
 ```
 
 For a schema like:
 
 ```graphql
 type MyTable @table {
-    id: ID @primaryKey
-    attribute1: Int
-    attribute2: Int
-    computedAttribute: Int @computed
+	id: ID @primaryKey
+	attribute1: Int
+	attribute2: Int
+	computedAttribute: Int @computed
 }
 ```
 
@@ -393,7 +392,7 @@ If the source resource implements subscription support, real-time invalidation c
 This property can be set to force the direct URL request target to be mapped to the resource primary key. Normally, URL resource targets are parsed, where the path is mapped to the primary key of the resource (and decoded using standard URL decoding), and any query string parameters are used to query that resource. But if this is turned on, the full URL is used as the primary key. For example:
 ```javascript
 export class MyTable extends tables.MyTable {
-    static directURLMapping = true;
+	static directURLMapping = true;
 }
 ```
 ```http request
@@ -646,7 +645,7 @@ export class CustomProduct extends Product {
 	post(target, data) {
 		let record = this.update(target);
 		record.name = data.name;
-    	record.description = data.description;
+		record.description = data.description;
 		// both of these changes will be saved automatically as this transaction commits
 	}
 }