Tweak Approach for Resources + Skills

未关闭
#35 0 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
28/100
Issue 类型
文档
描述清晰度
需要澄清
活跃度
停滞
技术栈
javascript
领域
documentation

调研方向

首先查看 skills 和模板,包括清单中提到的 README.md 和 examplePeople.js 文件。比较两个 Product 示例以及所要求的 caching、routing、permission、response 和 target 演示,然后明确 skills 应该教授哪种方法。达成标准是:约定的示例和清单中剩余的项目都一致地反映在 skills 中。

由索引模型根据 Issue 内容生成。

描述

Two examples from @kriszyp that we can integrate into the skills:

import { tables, getContext, RequestTarget } from 'harper'; // used to be 'harperdb'

// If this is functionally the main endpoint accessing/updating products, we can use the same name for the class as the
// table and directly use/extend tables.Product to make it clear we are extending the table as the main table endpoint
export class Product extends tables.Product {
	// first define how this is externally accessed; any REST methods we want to override to define permission/access,
	// how we handle requests, any routing we want to do, and actions we want to perform:
	static async get(target: RequestTarget) {
		// checkPermissionForForGet()
		// or just open it up to the whole world
		target.checkPermission = false;
		// if we want to treat queries for a set of products differently than requests for a single product (by id), we can:
		if (target.isCollection) {
			target.limit ??= 100; // maybe put a reasonable limit here
			return super.get(target);
		} // else it is a request for a single product
		const record = await super.get(target);
		return {
			...record, // note that spreading the result of get() requires 5.0 (or loadAsInstance=false)
			price: new Date().getDay() == 5 ? record.price * 0.8 : record.price, // 20% off on Fridays!
		};
	}
	
	static async post(target: RequestTarget, data: Promise<any>) {
		// we can branch on URL paths, if we want:
		if (target.pathname === '/') {
			// it is generally good to do any custom authorization logic early in a static method
			checkPermissionForAddingAProduct(); 
			return super.create(target, await data);
		} else {
			checkPermissionForAddingImageToProduct();
			const product = await super.update(target); // get an updatable product instance
			if (!product.doesExist()) {
				return undefined; // 404 if it doesn't exist
			}
			const { imageToAdd } = await data;
			product.addImage(imageToAdd);
			return { message: 'Added image to product', product };
		}
	}
	
	static delete(target: RequestTarget) {
		checkPermissionForDelete();
		return super.delete(target);
	}
	// note that we are just inheriting put, patch, etc.; don't override a method if the default behavior works for us!
	// (or if the default restrictive permissions sufficiently protect it)
	
	// static put(target: RequestTarget, data: Promise<any>) ...
	// static patch(target: RequestTarget, data: Promise<any>) ...

	// Now we have defined all our entry points to the table, move on to define the data model for how each product
	// is updated (or created) and validated:

	addImage(imageToAdd) {
		this.image = imageToAdd; // assign a new image
	}

	// This is called before any transaction is committed, for put, patch, create
	validate(record, partial: boolean) {
		// add our own data "cleaning". Note that the record here is mutable! (at least for now, will soon be frozen)
		record.description = record.description.trim(); // trim leading/trailing spaces
		record.price = +record.price.toFixed(2); // only two decimal places
		// execute the default validation that ensures the record has the correct types matching the schema
		super.validate(record, partial);
		// and add our own custom validation
		if (record.price < 0) {
			let error = new Error('You can not have a negative price!');
			error.statusCode = 400;
			throw error;
		}
		if (isUglyAccordingToAI(this.image)) {
			throw new Error('We do not want an ugly product image!');
		}
	}
}

// an additional note here; we rarely sell standalone applications. We sell caching applications. Basically
// everything we sell is caching data from other sources. Good to include in examples when possible
Product.sourcedFrom({
	async get(productId) {
		return (await fetch(salesforceUrl + productId)).json();
	}
});

function checkPermissionForAddingAProduct() {
	const user = getContext().user; // ambient access to context and user through async context tracking
	if (user.role.name !== 'product-manager') {
		let error = new Error('You are not a product manager!');
		error.statusCode = 403;
		throw error;
	}
}

and another example splitting things up a bit more:

import { tables, getContext, RequestTarget } from 'harper'; // used to be 'harperdb'

// define an endpoint to return some HTML and do some stuff, only thing exposed to HTTP
export const product = {
  get() {
    return new Response({ headers: { Content-Type: 'text/html' }, body: '<html>...'});
  }
  async post(target, data) {
    let product: Product = await Product.update(target);
    product.addImage((await data).imageToAdd);
    product.save(); // would happen automatically on commit
  }
};

// just do a little data modeling here, but do *not* export or expose to HTTP
class Product extends tables.Product {

	addImage(imageToAdd) {
		this.image = imageToAdd; // assign a new image
	}

	// This is called before any transaction is committed, for any updates (including the one above)
	validate(record, partial: boolean) {
		// execute the default validation that ensures the record has the correct types matching the schema
		super.validate(record, partial);
		if (isUglyAccordingToAI(this.image)) {
			throw new Error('We do not want an ugly product image!');
		}
	}
}

Some things we should consider accomplishing:

  • Demonstrate caching from another external system which can give extreme speed-ups and load reduction. Product.sourcedFrom
  • Remove the various example files from the templates like examplePeople.js, and instead place a simple README.md that points to the relevant skills. This should help agents and humans perform better without placing a bunch of junk code in their way.
  • Shift to static, or straight objects, instead of instance methods.
  • Demonstrate returning response headers, status codes, and bodies.
  • Demonstrate how we do custom routing.
  • Turning off automatic permission checks (target.checkPermission = false).
  • Import from harper not harperdb
  • Look for other target examples we can make clear in the skills.
  • checkPermissionForAddingAProduct
主要语言
JavaScript
星标
3
派生
0
平均合并
3 天 4 小时
30 天内合并 PR
8

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

HarperFast/create-harper 的其他 Issue

查看 HarperFast/create-harper 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。