diff --git a/README.md b/README.md index f896e53..2f75dc6 100644 --- a/README.md +++ b/README.md @@ -15,19 +15,30 @@ Following quick start guide gives a three part setup approach for `Relay`, `Rela First thing we need is a relay instance, this is where our base procedure configuration is defined. This space should be environment agnostic meaning we should be able to import our relay instance in both back end front end environments. ```ts -import { Relay, procedure } from "@valkyr/relay"; +import { Relay, rpc, route } from "@valkyr/relay"; -export const relay = new Relay([ - procedure - .method("user:create") - .params( - z.object({ - name: z.string(), - email: z.string().check(z.email()), - }) - ) - .result(z.string()), -]); +export const relay = new Relay({ + user: { + create: rpc + .method("user:create") + .params( + z.object({ + name: z.string(), + email: z.string().check(z.email()), + }), + ) + .result(z.string()), + update: route + .put("/users/:userId") + .params({ userId: z.uuid() }) + .body( + z.object({ + name: z.string().optional(), + email: z.string().optional() + }), + ), + } +}); ``` As we can see in the above example we are defining a new `method` procedure with an expected `params` and `result` contracts defined using zod schemas. @@ -41,22 +52,25 @@ import { RelayApi, NotFoundError } from "@valkyr/relay"; import { relay } from "@project/relay"; -export const api = new RelayApi({ - routes: [ - relay - .method("user:create") - .handle(async ({ name, email }) => { - const user = await db.users.insert({ name, email }); - if (user === undefined) { - return new NotFoundError(); - } - return user.id; - }), - ], -}); +export const api = new RelayApi([ + relay + .method("user:create") + .handle(async ({ name, email }) => { + const user = await db.users.insert({ name, email }); + if (user === undefined) { + return new NotFoundError(); + } + return user.id; + }), + relay + .put("/users/:userId") + .handle(async ({ userId }, { name, email }) => { + await db.users.update({ name, email }).where({ id: userId }); + }), +]); ``` -With the above example we now have a `method` handler for the `user:create` method. +With the above example we now have a `method` handler for the `user:create` method, and a `put` handler for the `/users/:userId` route path. ### Web @@ -69,12 +83,12 @@ import { relay } from "@project/relay"; const client = relay.client({ adapter: new HttpAdapter("http://localhost:8080") -}) +}); const userId = await client.user.create({ name: "John Doe", email: "john.doe@fixture.none" }); -console.log(userId); // => string +await client.user.update({ userId }, { name: "Jane Doe", email: "jane.doe@fixture.none" }); ``` diff --git a/libraries/route.ts b/libraries/route.ts index d307cc5..4b58c5f 100644 --- a/libraries/route.ts +++ b/libraries/route.ts @@ -192,7 +192,39 @@ export class Route { /** * Server handler callback method. * + * Handler receives the params, query, body, actions in order of definition. + * So if your route has params, and body the route handle method will + * receive (params, body) as arguments. + * * @param handle - Handle function to trigger when the route is executed. + * + * @examples + * + * ```ts + * relay + * .post("/foo/:bar") + * .params({ bar: z.string() }) + * .body(z.tuple([z.string(), z.number()])) + * .handle(async ({ bar }, [ "string", number ]) => {}); + * ``` + * + * ```ts + * const prefix = actions + * .make("prefix") + * .input(z.string()) + * .output({ prefixed: z.string() }) + * .handle(async (value) => ({ + * prefixed: `prefix_${value}`; + * })) + * + * relay + * .post("/foo") + * .body(z.object({ bar: z.string() })) + * .actions([prefix, (body) => body.bar]) + * .handle(async ({ bar }, { prefixed }) => { + * console.log(prefixed); => prefixed_${bar} + * }); + * ``` */ handle>(handle: THandleFn): Route & { handle: THandleFn }> { return new Route({ ...this.state, handle }); diff --git a/mod.ts b/mod.ts index e0bb905..42559a4 100644 --- a/mod.ts +++ b/mod.ts @@ -5,3 +5,4 @@ export * from "./libraries/errors.ts"; export * from "./libraries/procedure.ts"; export * from "./libraries/relay.ts"; export * from "./libraries/request.ts"; +export * from "./libraries/route.ts"; diff --git a/tests/mocks/relay.ts b/tests/mocks/relay.ts index dfef1c4..0cd16c6 100644 --- a/tests/mocks/relay.ts +++ b/tests/mocks/relay.ts @@ -12,7 +12,7 @@ export const relay = new Relay({ .method("user:create") .params(UserSchema.omit({ id: true, createdAt: true })) .result(z.string()), - get: rpc.method("user:get").params(z.string().check(z.uuid())).result(UserSchema), + get: rpc.method("user:get").params(z.uuid()).result(UserSchema), update: rpc.method("user:update").params( z.tuple([ z.string(), @@ -22,7 +22,7 @@ export const relay = new Relay({ }), ]), ), - delete: rpc.method("user:delete").params(z.string().check(z.uuid())), + delete: rpc.method("user:delete").params(z.uuid()), }, numbers: { add: rpc @@ -47,7 +47,7 @@ export const relay = new Relay({ email: z.string().check(z.email()).optional(), }), ), - delete: route.delete("/users/:userId").params({ userId: z.string().check(z.uuid()) }), + delete: route.delete("/users/:userId").params({ userId: z.uuid() }), }, numbers: { add: route