diff --git a/.changeset/big-avocados-care.md b/.changeset/big-avocados-care.md new file mode 100644 index 0000000..80e3f32 --- /dev/null +++ b/.changeset/big-avocados-care.md @@ -0,0 +1,6 @@ +--- +'@solid-mediakit/authpc-plugin': patch +'@solid-mediakit/authpc': patch +--- + +feat: `cached` option & set default method to GET diff --git a/docs/Test.md b/docs/Test.md deleted file mode 100644 index 507b84d..0000000 --- a/docs/Test.md +++ /dev/null @@ -1,748 +0,0 @@ -## What Is AuthPC - -AuthPC is a utility library that combines both - -- Authentication (`Auth`) -- Better Solid'S RPC (`PC`) - -### Supports - -- AuthPC currently supports two Auth Providers: [Clerk](https://clerk.com/) & [AuthJS](https://authjs.dev/). -- AuthPC currently supports two Validators: [Zod](https://zod.dev/) & [ValiBot](https://valibot.dev/). - -AuthPC also allows you to throw type-safe errors, redirect the user, modify headers, set cookies and most importantly, you can choose to use either `GET` (allowing the use of HTTP cache-control headers) or `POST`. - -That means you can create server actions completly type safe, cached, auth/session protected and all in simple function declaration, many might think but wait this is very simple to achieve in other frameworks, what took you so long to create this one, In this doc i'm actually going to explain the behind the scenes of `AuthPC`. - -Everything here is type-safe, it also includes middlewares and allowed to be imported to any file thanks to the advance babel plugin. - -## Install - -First install both the plugin & the authpc package - -```bash -pnpm install @solid-mediakit/authpc@latest @solid-mediakit/authpc-plugin@latest @tanstack/solid-query@latest -``` - -### App Config - -Wrap your entire config with the `withAuthPC` method for typesafety: - -```ts -import { withAuthPC } from '@solid-mediakit/authpc-plugin' - -const config = withAuthPC({ - ssr: true, -}) - -// this is important: otherwise you cannot access the session$ property -declare module '@solid-mediakit/authpc' { - interface Settings { - config: typeof config - } -} - -export default config -``` - -### Note - -To use any auth provider, you need to follow the guides bellow, this is optional you don't have to use any auth provider with this library, if you don't use one, you will not be able to access the `session$` property. -**Also if you don't use any auth provider, you need to wrap your app with the AuthPCProvider** - -- I Want To Use Auth By Using AuthJS - [here](#authjs) -- I Want To Use Auth By Using Clerk - [here](#clerk) -- I Don't Use Any Auth - [here](#authpcprovider) - -## API - -- [createCaller](#createcaller) - - [Zod](#zod) - - [ValiBot](#valibot) - - [Client Error Handling](#error-handling) - - [Middlewares & .use](#use) - - [Optimistic Updates](#optimistic-updates) - - [Methods](#methods) - - [POST](#post) - - [GET](#get) - - [Function Types](#function-types) - - [Query](#query) - - [Mutation](#mutation) -- [Utils](#utils) - - [redirect$](#redirect) - - [response$](#response) - - [error$](#error) - -## createCaller - -Use this method to interact with the api, you can choose between a `query` or a `mutation` (default is query) and also choose to use either `GET`/`POST` as the request method (default is POST). - -### No Schema - -```ts -// server.ts -import { createCaller } from '@solid-mediakit/authpc' - -const myServerQuery = createCaller( - ({ session$ }) => { - console.log(session$, event$.request.headers.get('user-agent')) - return 'Who do i say hey to' - }, - { - method: 'GET', - }, -) - -// client.tsx -import { myServerQuery } from './server' -const query = myServerQuery() -``` - -### Zod - -```ts -// server.ts -import { createCaller } from '@solid-mediakit/authpc' -import { z } from 'zod' - -const mySchema = z.object({ name: z.string() }) - -export const myServerQuery = createCaller( - mySchema, - ({ input$, session$, event$ }) => { - console.log(session$, event$.request.headers.get('user-agent')) - return `Hey there ${input$.name}` - }, - { - method: 'GET', - }, -) - -// client.tsx -import { myServerQuery } from './server' -const query = myServerQuery(() => ({ name: 'Demo' })) -``` - -### Valibot - -```ts -// server.ts -import { createCaller } from '@solid-mediakit/authpc' -import * as v from 'valibot' - -const mySchema = v.object({ name: v.string() }) - -export const myServerQuery = createCaller( - mySchema, - ({ input$, session$, event$ }) => { - console.log(session$, event$.request.headers.get('user-agent')) - return `Hey there ${input$.name}` - }, - { - method: 'GET', - }, -) - -// client.tsx -import { myServerQuery } from './server' -const query = myServerQuery(() => ({ name: 'Demo' })) -``` - -### Error Handling - -Errors are thrown using the `AuthPClientError` class. When the server function has a schema defined, you can use the `isValidationError` to get the issues. - -```tsx -import { createEffect } from 'solid-js' -import { myServerQuery } from './server' - -const MyClient = () => { - const query = myServerQuery(() => ({ name: 'Demo' })) - - createEffect(() => { - if (query.error) { - if (query.error.isValidationError()) { - query.error.cause.fieldErrors.name // string[] - } else { - console.error('What is this', query.error.cause) - } - } - }) - - return (...) -} - -export default MyClient -``` - -### Methods - -You can choose any method (GET || POST), regardless of the function type (default is POST) - -#### GET - -```ts -import { createCaller, response$ } from '@solid-mediakit/authpc' - -export const getRequest = createCaller( - () => { - return response$( - { iSetTheHeader: true }, - { headers: { 'cache-control': 'max-age=60' } }, - ) - }, - { - method: 'GET', - }, -) -``` - -#### POST - -This is the default so you don't have to mention it - -```ts -import { createCaller, response$ } from '@solid-mediakit/authpc' - -export const postRequest = createCaller( - () => { - return response$({ iSetTheHeader: true }, { headers: { 'X-Testing': '1' } }) - }, - { - method: 'POST', - }, -) - -export const postRequest2 = createCaller(() => { - return response$({ iSetTheHeader: true }, { headers: { 'X-Testing': '1' } }) -}) -``` - -### Function Types - -In addition to methods, you can also choose a function type (the function type will not affect the request method). - -#### query - -This is the default, you don't have to specify this: - -```ts -import { createCaller } from '@solid-mediakit/authpc' - -const thisIsAQuery = createCaller(() => { - return 1 -}) - -const alsoIsAQuery = createCaller( - () => { - return 1 - }, - { - type: 'query', - }, -) - -// client side -const query = thisIsAQuery() -query.data // number -``` - -#### mutation - -You can either specify {type: 'action'} or use the `createAction` method - -```ts -import { createCaller, createAction } from '@solid-mediakit/authpc' - -const thisIsAMutation = createCaller( - () => { - return 1 - }, - { - type: 'action', - }, -) - -const alsoIsAMutation = createAction(() => { - return 1 -}) - -// client side -const mutation = thisIsAMutation() -mutation.mutate() -``` - -## .use - -This method allows you create a reuseable caller that contains your middlewares. -You can combine multiple callers / middlewares and import them to different files, take a look at this example. - -### file1.ts - -In this file we create a caller with a custom middleware and then export it so it could be use in other files as-well. - -```ts -import { createCaller } from '@solid-mediakit/authpc' - -export const withMw1 = createCaller.use(() => { - return { - myFile1: 1, - } -}) - -export const action1 = withMw1(({ ctx$ }) => { - return `hey ${ctx$.myFile1} ` -}) -``` - -[This Transforms To](#transforms) - -### file2.ts - -In this file we can actually import the caller we created and then add more middlewares to it or use it as is. - -```ts -import { withMw1 } from './file1' - -export const withMw2 = withMw1.use(({ ctx$ }) => { - return { - ...ctx$, - myFile2: 2, - } -}) - -export const action2 = withMw2(({ ctx$ }) => { - return `hey ${ctx$.myFile1} ${ctx$.myFile2}` -}) -``` - -## Utils - -AuthPC contains many utils out of the box, like redirection, erroring, setting cookies, etc. - -### redirect$ - -Use this function to **redirect the user** (this will not affect the function type): - -```ts -import { createCaller, redirect$ } from '@solid-mediakit/authpc' - -let redirect = false - -export const myQuery = createCaller(() => { - if (redirect) { - return redirect$('/login') - } - return 'yes' -}) -``` - -### error$ - -Use this function to **throw an error on the user side** (this will not affect the function type): - -```ts -import { createCaller, error$ } from '@solid-mediakit/authpc' - -let shouldError = false - -export const myQuery = createCaller(() => { - if (shouldError) { - return error$$('Why did i error') - } - return 'yes' -}) -``` - -### response$ - -Use this function to **return data & modify headers** (the return type is also infered from the data passed to response$): - -```ts -import { createCaller, response$ } from '@solid-mediakit/authpc' - -let setHeader = false - -export const myQuery = createCaller(() => { - if (setHeader) { - return response$(1, { - headers: { this: 'that' }, - }) - } - return 'yes' -}) - -// respone type: number | string -``` - -### Optimistic Updates - -Similiar to tRPC, each query function has a `useUtils` method, so lets say we import a server action we created using `createCaller` called `serverQuery1` - -```ts -import { serverQuery1, serverMutation1 } from '~/server/etc' - -const MyComponent = () => { - const listPostQuery = serverQuery1() - const serverQueryUtils = serverQuery1.useUtils() - - const postCreate = serverMutation1(() => ({ - async onMutate(newPost) { - // Cancel outgoing fetches (so they don't overwrite our optimistic update) - await serverQueryUtils.cancel() - - // Get the data from the queryCache - const prevData = serverQueryUtils.getData() - - // Optimistically update the data with our new post - serverQueryUtils.setData(undefined, (old) => [...old, newPost]) - - // Return the previous data so we can revert if something goes wrong - return { prevData } - }, - onError(err, newPost, ctx) { - // If the mutation fails, use the context-value from onMutate - serverQueryUtils.setData(undefined, ctx.prevData) - }, - onSettled() { - // Sync with server once mutation has settled - serverQueryUtils.invalidate() - }, - })) -} -``` - -## Setting up auth - -As mentioned, you can choose to use either Clerk or AuthJS. - -### Clerk - -First Install The Dependencies - -#### Install - -```bash -pnpm install clerk-solidjs@latest -``` - -### Env Variables - -Make sure to have this in your `.env` - -``` -VITE_CLERK_PUBLISHABLE_KEY= -CLERK_SECRET_KEY= -``` - -#### Wrap Your App With ClerkProvider - -`src/app.tsx` should be something like: - -```tsx -// @refresh reload -import './app.css' -import { MetaProvider, Title } from '@solidjs/meta' -import { Router } from '@solidjs/router' -import { FileRoutes } from '@solidjs/start/router' -import { Suspense } from 'solid-js' -import { QueryClient } from '@tanstack/solid-query' -import { AuthPCProvider } from '@solid-mediakit/authpc' -import { ClerkProvider } from 'clerk-solidjs' - -export default function App() { - const queryClient = new QueryClient() - return ( - ( - - SolidStart - Basic - - - {props.children} - - - - )} - > - - - ) -} -``` - -#### Creating A Middleware - -Head over to `src/middleware.ts` and make sure its something like: - -```ts -import { createMiddleware } from '@solidjs/start/middleware' -import { clerkMiddleware } from 'clerk-solidjs/start/server' - -export default createMiddleware({ - onRequest: [ - clerkMiddleware({ - publishableKey: process.env.VITE_CLERK_PUBLISHABLE_KEY, - secretKey: process.env.CLERK_SECRET_KEY, - }), - ], -}) -``` - -### Modifying app.config.ts - -This is it, you just need to modify `app.config.ts` - -```ts -import { withAuthPC } from '@solid-mediakit/authpc-plugin' - -const config = withAuthPC( - { - ssr: true, - }, - { - auth: 'clerk', - authCfg: { - middleware: './src/middleware.ts', - protectedMessage: 'You need to sign in first', - }, - }, -) - -export default config - -declare module '@solid-mediakit/authpc' { - interface Settings { - config: typeof config - } -} -``` - -### AuthJS - -First Install The Dependencies - -#### Install - -```bash -pnpm install @auth/core@0.35.0 @solid-mediakit/auth@latest -``` - -### Env Variables - -Make sure to have this in your `.env` - -``` -VITE_AUTH_PATH=/api/auth -DISCORD_ID= -DISCORD_SECRET= -``` - -#### Create Config - -After installing, head over to `server/auth.ts` and create the AuthJS config: - -```ts -import { type SolidAuthConfig } from '@solid-mediakit/auth' -import Discord from '@auth/core/providers/discord' - -declare module '@auth/core/types' { - export interface Session { - user: {} & DefaultSession['user'] - } -} - -export const authOpts: SolidAuthConfig = { - providers: [ - Discord({ - clientId: process.env.DISCORD_ID, - clientSecret: process.env.DISCORD_SECRET, - }), - ], - debug: false, - basePath: import.meta.env.VITE_AUTH_PATH, -} -``` - -### Create Auth API Endpoint - -Go to `src/routes/api/auth/[...solidauth].ts`: - -```ts -import { SolidAuth } from '@solid-mediakit/auth' -import { authOpts } from '~/server/auth' - -export const { GET, POST } = SolidAuth(authOpts) -``` - -#### Wrap Your App With SessionProvider - -`src/app.tsx` should be something like: - -```tsx -// @refresh reload -import './app.css' -import { MetaProvider, Title } from '@solidjs/meta' -import { Router } from '@solidjs/router' -import { FileRoutes } from '@solidjs/start/router' -import { Suspense } from 'solid-js' -import { QueryClient } from '@tanstack/solid-query' -import { AuthPCProvider } from '@solid-mediakit/authpc' -import { SessionProvider } from '@solid-mediakit/auth/client' - -export default function App() { - const queryClient = new QueryClient() - return ( - ( - - SolidStart - Basic - - - {props.children} - - - - )} - > - - - ) -} -``` - -### Modifying app.config.ts - -This is it, you just need to modify `app.config.ts` - -```ts -import { withAuthPC } from '@solid-mediakit/authpc-plugin' - -const config = withAuthPC( - { - ssr: true, - }, - { - auth: 'authjs', - authCfg: { - source: '~/server/auth', - configName: 'authOpts', - protectedMessage: 'You need to sign in first', - }, - }, -) - -export default config - -declare module '@solid-mediakit/authpc' { - interface Settings { - config: typeof config - } -} -``` - -### AuthPCProvider - -`src/app.tsx` should be something like: - -```tsx -// @refresh reload -import './app.css' -import { MetaProvider, Title } from '@solidjs/meta' -import { Router } from '@solidjs/router' -import { FileRoutes } from '@solidjs/start/router' -import { Suspense } from 'solid-js' -import { QueryClient } from '@tanstack/solid-query' -import { AuthPCProvider } from '@solid-mediakit/authpc' - -export default function App() { - const queryClient = new QueryClient() - return ( - ( - - SolidStart - Basic - - {props.children} - - - )} - > - - - ) -} -``` - -## Transforms - -### file1 - -File1 Transforms To: - -```ts -import { createCaller, callMiddleware$ } from '@solid-mediakit/authpc' - -export const withMw1 = createCaller - -export const action1 = createCaller( - async ({ input$: _$$payload }) => { - 'use server' - const ctx$ = await callMiddleware$(_$$event, _$$withMw1_mws) - if (ctx$ instanceof Response) return ctx$ - return `hey ${ctx$.myFile1} ` - }, - { - protected: false, - key: 'action1', - method: 'POST', - type: 'query', - }, -) - -export const _$$withMw1_mws = [ - () => { - return { - myFile1: 1, - } - }, -] -``` - -### file2 - -File2 Transforms To: - -````ts -import { createCaller, callMiddleware$ } from '@solid-mediakit/authpc' -import { withMw1, _$$withMw1_mws } from './file1' - -export const withMw2 = withMw1 - -export const action2 = createCaller( - async ({ input$: _$$payload }) => { - 'use server' - const ctx$ = await callMiddleware$(_$$event, _$$withMw2_mws) - if (ctx$ instanceof Response) return ctx$ - return `hey ${ctx$.myFile1} ${ctx$.myFile2}` - }, - { - protected: false, - key: 'action2', - method: 'POST', - type: 'query', - }, -) - -export const _$$withMw2_mws = [ - ..._$$withMw1_mws, - ({ ctx$ }) => { - return { - ...ctx$, - myFile2: 2, - } - }, -]``` -```` diff --git a/docs/src/content/docs/authpc/createcaller.mdx b/docs/src/content/docs/authpc/createcaller.mdx index 536f2e6..d43785c 100644 --- a/docs/src/content/docs/authpc/createcaller.mdx +++ b/docs/src/content/docs/authpc/createcaller.mdx @@ -3,7 +3,7 @@ title: 'createCaller' description: 'createCaller Method' --- -Use this method to interact with the api, you can choose between a `query` or a `mutation` (default is query) and also choose to use either `GET`/`POST` as the request method (default is POST). +Use this method to interact with the api, you can choose between a `query` or a `mutation` (default is query) and also choose to use either `GET`/`POST` as the request method (default is GET & wrapped with Solid's `cache` function). ### API @@ -124,10 +124,12 @@ export default MyClient ### Methods -You can choose any method (GET || POST), regardless of the function type (default is POST) +You can choose any method (GET || POST), regardless of the function type (default is GET & wrapped with Solid's `cache` function) #### GET +This is the default so you don't have to mention it + ```ts import { createCaller, response$ } from '@solid-mediakit/authpc' @@ -142,11 +144,32 @@ export const getRequest = createCaller( method: 'GET', }, ) + +export const getRequest2 = createCaller(() => { + return response$( + { iSetTheHeader: true }, + { headers: { 'cache-control': 'max-age=60' } }, + ) +}) + +// this will not be wrapped with solid's `cache` +export const notCached = createCaller( + () => { + return response$( + { iSetTheHeader: true }, + { headers: { 'cache-control': 'max-age=60' } }, + ) + }, + { + cached: false, + }, +) ``` #### POST -This is the default so you don't have to mention it +You can also use `POST` with queries. +When using `mutations` / `actions` you don't have to specify the method and the default will be `POST` ```ts import { createCaller, response$ } from '@solid-mediakit/authpc' @@ -160,9 +183,14 @@ export const postRequest = createCaller( }, ) -export const postRequest2 = createCaller(() => { - return response$({ iSetTheHeader: true }, { headers: { 'X-Testing': '1' } }) -}) +export const postRequest2 = createCaller( + () => { + return response$({ iSetTheHeader: true }, { headers: { 'X-Testing': '1' } }) + }, + { + type: 'action', + }, +) ``` ### Function Types diff --git a/examples/authpc/src/use/use.ts b/examples/authpc/src/use/use.ts index 3b00102..692edca 100644 --- a/examples/authpc/src/use/use.ts +++ b/examples/authpc/src/use/use.ts @@ -56,7 +56,6 @@ export const getRequest = createCaller( export const mutationTest3 = qfn( z.object({ ok: z.number(), test: z.object({ l: z.string() }) }), ({ input$ }) => { - return error$('test') return `${input$.ok}` }, { diff --git a/packages/authpc/plugin/src/compiler/babel.ts b/packages/authpc/plugin/src/compiler/babel.ts index 4c4e6e0..cbfaf3b 100644 --- a/packages/authpc/plugin/src/compiler/babel.ts +++ b/packages/authpc/plugin/src/compiler/babel.ts @@ -17,10 +17,6 @@ import { export const packageSource = `@solid-mediakit/authpc` export function createTransform$(opts?: AuthPCPluginOptions) { - const wrappedEles: { - source: string - name: string - }[] = [] return function transform$({ types: t, template: temp, @@ -145,12 +141,20 @@ export function createTransform$(opts?: AuthPCPluginOptions) { ) if (args._method === 'GET') { - importIfNotThere(path, t, 'GET', '@solidjs/start') + importIfNotThere( + path, + t, + args._cache ? 'cache' : 'GET', + args._cache ? '@solidjs/router' : '@solidjs/start', + ) } const wrappedArg = args._method === 'GET' - ? t.callExpression(t.identifier('GET'), [originFn]) + ? t.callExpression( + t.identifier(args._cache ? 'cache' : 'GET'), + [originFn], + ) : originFn const props = t.objectExpression([ @@ -166,10 +170,6 @@ export function createTransform$(opts?: AuthPCPluginOptions) { ), ]) if (nodeInfo.isWrapped) { - wrappedEles.push({ - name: nodeInfo.originalName!, - source: currentFileName!, - }) path.node.callee = t.identifier(nodeInfo.isGet) } path.node.arguments = [wrappedArg, props] diff --git a/packages/authpc/plugin/src/compiler/utils.ts b/packages/authpc/plugin/src/compiler/utils.ts index 2dd9c80..de50844 100644 --- a/packages/authpc/plugin/src/compiler/utils.ts +++ b/packages/authpc/plugin/src/compiler/utils.ts @@ -126,7 +126,6 @@ export const getNodeInfo = ( return t } } - return checkForEle((current.init as any).name, [...prev, name]) } return null @@ -200,6 +199,7 @@ export const getFunctionArgs = ( let _protected: null = null let _method: 'GET' | 'POST' = undefined! let _fnType: 'action' | 'query' = undefined! + let _cache = true const _opts = // method(schema,fn,opts) pArgs.length === 3 @@ -236,12 +236,13 @@ export const getFunctionArgs = ( _protected = getProp('protected') _fnType = getProp('type') _method = getProp('method') + _cache = getProp('cache') === false ? false : true } _fnType = nodeInfo.isGet === 'createAction' ? 'action' : !_fnType ? 'query' : _fnType if (!_method) { - _method = 'POST' + _method = _fnType === 'action' ? 'POST' : 'GET' } const key = t.isStringLiteral(_key) @@ -264,6 +265,7 @@ export const getFunctionArgs = ( zodSchema, _fnType, _method, + _cache, } } diff --git a/packages/authpc/solid/README.md b/packages/authpc/solid/README.md index e4b67dd..640648d 100644 --- a/packages/authpc/solid/README.md +++ b/packages/authpc/solid/README.md @@ -77,7 +77,7 @@ To use any auth provider, you need to follow the guides bellow, this is optional ## createCaller -Use this method to interact with the api, you can choose between a `query` or a `mutation` (default is query) and also choose to use either `GET`/`POST` as the request method (default is POST). +Use this method to interact with the api, you can choose between a `query` or a `mutation` (default is query) and also choose to use either `GET`/`POST` as the request method (default is GET & wrapped with Solid's `cache` function). ### No Schema @@ -182,10 +182,12 @@ export default MyClient ### Methods -You can choose any method (GET || POST), regardless of the function type (default is POST) +You can choose any method (GET || POST), regardless of the function type (default is GET & wrapped with Solid's `cache` function) #### GET +This is the default so you don't have to mention it + ```ts import { createCaller, response$ } from '@solid-mediakit/authpc' @@ -200,11 +202,32 @@ export const getRequest = createCaller( method: 'GET', }, ) + +export const getRequest2 = createCaller(() => { + return response$( + { iSetTheHeader: true }, + { headers: { 'cache-control': 'max-age=60' } }, + ) +}) + +// this will not be wrapped with solid's `cache` +export const notCached = createCaller( + () => { + return response$( + { iSetTheHeader: true }, + { headers: { 'cache-control': 'max-age=60' } }, + ) + }, + { + cached: false, + }, +) ``` #### POST -This is the default so you don't have to mention it +You can also use `POST` with queries. +When using `mutations` / `actions` you don't have to specify the method and the default will be `POST` ```ts import { createCaller, response$ } from '@solid-mediakit/authpc' @@ -218,9 +241,14 @@ export const postRequest = createCaller( }, ) -export const postRequest2 = createCaller(() => { - return response$({ iSetTheHeader: true }, { headers: { 'X-Testing': '1' } }) -}) +export const postRequest2 = createCaller( + () => { + return response$({ iSetTheHeader: true }, { headers: { 'X-Testing': '1' } }) + }, + { + type: 'action', + }, +) ``` ### Function Types diff --git a/packages/authpc/solid/src/types.ts b/packages/authpc/solid/src/types.ts index e9e4ee5..3671892 100644 --- a/packages/authpc/solid/src/types.ts +++ b/packages/authpc/solid/src/types.ts @@ -270,7 +270,15 @@ export type Create$Opts< protected?: IsProtected method?: RequestMethod type?: FnType -} +} & (FnType extends undefined + ? { + cache?: boolean + } + : FnType extends 'action' + ? {} + : { + cache?: boolean + }) export type OutputGet$< IsAction extends boolean,