Psychic

https://psychicframework.com/docs
Admin
Psychic is a modern, TypeScript-driven web framework built on Express that combines the MVC paradigm...
Tokens:133,181
Snippets:855
Trust Score:4.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Create New Psychic App with npx

Source: https://psychicframework.com/docs/installation

Initializes a new Psychic application with a specified name. This command prompts for configuration, sets up server and client dependencies, installs them, and initializes a git repository.

```bash
npx @rvoh/create-psychic howyadoin
```

--------------------------------

### Psychic Server Start Hook

Source: https://psychicframework.com/docs/config/hooks

The `server:start` hook is executed immediately after the web server has successfully started. It's a good place for post-startup tasks or simple logging.

```typescript
export default async (app: PsychicApp) => {
  app.on('server:start', (psychicServer: PsychicServer) => {
    console.log('hello world!')
  })
}
```

--------------------------------

### REPL Model Inspection Example (REPL)

Source: https://psychicframework.com/docs/cli/repl

An example of how to inspect database models within the Psychic Framework's REPL. It demonstrates fetching all users and accessing them.

```javascript
> u = await User.all()
```

--------------------------------

### Start WebSocket Server with socket.io Authentication (TypeScript)

Source: https://psychicframework.com/docs/plugins/websockets/config

This snippet demonstrates how to handle the `ws:start` event to initialize WebSocket connections using socket.io. It includes an example of authenticating users based on a token sent with the handshake and registering them for real-time communication. It requires the `PsychicAppWebsockets` type and uses `Encrypt` and `AppEnv` for decryption, along with a `User` model for data retrieval.

```typescript
export default (wsApp: PsychicAppWebsockets) => {
  // ...
  wsApp.on('ws:start', io => {
    // use socket.io to establish namespaced channels
    // for your app to communicate on
    io.of('/').on('connection', async socket => {
      // this is an example of how you might be handling
      // socket.io authentication. It would require extra
      // setup on both your frontend and backend clients,
      // but would enable you to emit to any user from anywhere
      // within the application.
      const token = socket.handshake.auth.token as string
      const userId = Encrypt.decrypt<string>(token, {
        algorithm: 'aes-256-gcm',
        key: AppEnv.string('APP_ENCRYPTION_KEY'),
      })!
      const user = await User.find(userId)

      if (user) {
        // this automatically fires the /ops/connection-success message
        await Ws.register(socket, user.id)
      }

      // establish socket routes using socket.on
    })
  })
}
```

--------------------------------

### Check Node.js and PostgreSQL Versions

Source: https://psychicframework.com/docs/tutorials/blog

Verifies the installed versions of Node.js and PostgreSQL to ensure compatibility with Psychic. This step is crucial before provisioning a new application.

```bash
which node  
# ~/.nodenv/shims/node  
  
node --version  
# v22.14.0  
  
postgres --version  
# postgres (PostgreSQL) 13.20  
```

--------------------------------

### OpenAPI Path and Response Schema Example

Source: https://psychicframework.com/docs/openapi/overview

An example illustrating the generated OpenAPI path and response schema for a 'get' request to '/places'. It shows how 'many: true' in the decorator translates to an array schema.

```json
"paths": {  
  "/places": {  
    "parameters": [],  
    "get": {  
      "tags": [],  
      "summary": "",  
      "responses": {  
        "200": {  
          "content": {  
            "application/json": {  
              "schema": {  
                "type": "array",  
                "items": {  
                  "$ref": "#/components/schemas/PlaceSummary"  
                }  
              }  
            }  
          },  
          "description": "index"  
        }  
      }  
    }  
  },  
}
```

--------------------------------

### Start Local REPL (Shell)

Source: https://psychicframework.com/docs/cli/repl

Command to launch the local REPL console for the Psychic Framework. This allows interactive database inspection and manipulation.

```shell
yarn console
```

--------------------------------

### Retrieving All Records

Source: https://psychicframework.com/docs/models/querying/overview

Explains how to fetch all records that match a query, including examples of retrieving all users and all active users. The `.all()` method is used to get a collection of records.

```javascript
// Get all users
const allUsers = await User.all()

// Get all active users
const activeUsers = await User.where({ active: true }).all()
```

--------------------------------

### Example .env File Configuration

Source: https://psychicframework.com/docs/tutorials/blog

Shows a sample `.env` file used for environment variables in a Psychic application. It includes database credentials, encryption keys, and CORS settings necessary for local development.

```env
DB_USER=fred # this may need to be changed  
DB_NAME=myblog_development  
DB_PORT=5432  
DB_HOST=localhost  
REPLICA_DB_PORT=5432  
REPLICA_DB_HOST=localhost  
DB_NO_SSL=1  
APP_ENCRYPTION_KEY="Paifn7F7cNToDs5zCgCR0/LGsj1Ar3c8WJz3VXXDioY="  
WEB_SERVICE=1  
WORKER_SERVICE=1  
CORS_HOSTS='["http://localhost:3000"]'  
TZ=UTC  
DREAM_PARALLEL_TESTS=3  
```

--------------------------------

### Generating Resources with Psychic CLI (Bash)

Source: https://context7.com/context7/psychicframework/llms.txt

Scaffolds complete CRUD functionality including models, controllers, migrations, and tests using the Psychic CLI. This command-line interface simplifies project setup by generating boilerplate code for various application resources. Examples include generating a model with associations, a full resource with a controller and routes, or a single table inheritance (STI) child model.

```bash
# Generate model with migration
yarn psy g:dream User name:string email:string birthdate:date

# Generate model with belongs_to association
yarn psy g:dream Post user:belongs_to body:string

# Generate complete resource with controller and routes
yarn psy g:resource --owning-model=Host v1/host/places Place \
  name:citext \
  style:enum:place_styles:cottage,cabin,lean_to,treehouse,tent,cave \
  sleeps:integer \
  deleted_at:datetime:optional

# Generate STI child model
yarn psy g:sti-child PremiumUser User subscription_tier:string
```

--------------------------------

### Install JSON Snapshot Plugin

Source: https://psychicframework.com/docs/plugins/snapshot/usage

Installs the necessary package for JSON snapshot functionality using Yarn. This is the first step before integrating Snapshotable into your models.

```bash
yarn add @rvoh/dream-plugin-json-snapshot
```

--------------------------------

### Dockerfile for Psychic Framework AWS Deployment

Source: https://psychicframework.com/docs/deployment/server/aws

This Dockerfile provisions an environment for a Psychic framework application on AWS Fargate. It sets up production Node.js environment, installs dependencies, builds the application, configures SSL certificates, and prepares the instance for running as a web server, worker, or console. It relies on `yarn` for package management and `dumb-init` for process supervision.

```dockerfile
ARG NODE_IMAGE=node:22-alpine  
  
FROM $NODE_IMAGE AS dev  
USER node  
  
FROM $NODE_IMAGE AS base  
ENV NODE_ENV=production  
ENV DB_USE_SSL=1  
ENV PSYCHIC_LOG_PATH=/dev/shm  
ENV PSYCHIC_SSL_CERT_PATH=/home/node/app/cert/psychic-selfsigned.crt  
ENV PSYCHIC_SSL_KEY_PATH=/home/node/app/cert/psychic-selfsigned.key  
ENV COREPACK_HOME=/home/node/bin  
ENV YARN_VERSION=4.4.1  
ENV APP_NAME=myapp  
RUN apk -U upgrade  
RUN apk add dumb-init  
ARG INSTALL_PG_DUMP_RESTORE  
RUN if [ "$INSTALL_PG_DUMP_RESTORE" = '1' ] ; then apk add postgresql15 ; fi  
RUN mkdir -p /home/node/app && chown node:node /home/node/app  
RUN mkdir -p /home/node/.npm && chown node:node /home/node/.npm  
RUN mkdir -p /home/node/.yarn && chown node:node /home/node/.yarn  
WORKDIR /home/node/app  
RUN mkdir tmp  
  
FROM base AS dependencies  
COPY --chown=node:node ./package.json .  
COPY --chown=node:node ./yarn.lock .  
USER root  
RUN apk add git  
COPY --chown=node:node .yarnrc.yml .  
COPY --chown=node:node . .  
RUN mkdir ${COREPACK_HOME}  
RUN corepack enable --install-directory ${COREPACK_HOME} && corepack prepare yarn@${YARN_VERSION}  
# RUN corepack enable && corepack prepare yarn@${YARN_VERSION}  
  
# need types to build, so install dev dependencies  
RUN yarn workspaces focus --production  
RUN NODE_ENV=production yarn install --immutable  
RUN NODE_ENV=production yarn build  
# # now that we've built, we can install without dev dependencies  
RUN rm -rf node_modules  
RUN yarn workspaces focus --production  
  
RUN rm .yarnrc.yml  
RUN echo "nodeLinker: node-modules" > .yarnrc.yml  
  
FROM base AS sslsetup  
USER root  
RUN mkdir /home/node/cert && \  
    apk update && \  
    apk add --no-cache openssl && \  
    openssl req -x509 -nodes -days 365 \  
      -subj  "/C=CA/ST=SC/O=Wellos/CN=*.wellos.com" \  
      -newkey rsa:2048 -keyout /home/node/cert/psychic-selfsigned.key \  
      -out /home/node/cert/psychic-selfsigned.crt;  
  
FROM base AS production  
USER root  
COPY --chown=node:node --from=dependencies /home/node/app/ .  
COPY --chown=node:node --from=sslsetup /home/node/cert ./cert  
RUN mkdir ${COREPACK_HOME}  
RUN corepack enable --install-directory ${COREPACK_HOME} && corepack prepare yarn@${YARN_VERSION}  
  
USER node  
RUN echo 'alias yarn="corepack yarn"' >> /home/node/.profile  
  
EXPOSE 8443  
ENV PATH="${PATH}:/home/node/npm_global/bin"  
  
# pm2 is installed globally; specify where to install global npm packages  
RUN mkdir /home/node/npm_global  
ENV NPM_CONFIG_PREFIX=/home/node/npm_global  
  
#########################  
# non-readonly carveout  
#########################  
# /dev/shm is non-read-only on the servers, so anything that needs to  
# be able to write files on the server, needs write to /dev/shm  
RUN mkdir -p /dev/shm  
RUN ln -sf /dev/shm ../.npm  
RUN ln -sf /dev/shm ../.npm/_cacache  
RUN ln -sf /dev/shm ../.yarn  
RUN ln -sf /dev/shm ../app_tmp  
  
# pm2 needs to be able to write to disk (for logs and pid files), so set up a writeable directory for it  
# and set PM2_HOME to the writeable directory  
ENV PM2_HOME=/dev/shm/.pm2  
RUN mkdir ${PM2_HOME}  
#########################  
# end: non-readonly carveout  
#########################  
  
# you can use regular pm2 if you do not need websockets  
RUN npm install -g @socket.io/pm2  
  
COPY --chown=node:node ./migrate_and_serve.sh ./  
  
# Uncomment when want to get onto the repl and be able to import:  
# COPY --chown=node:node --from=build /home/node/app ./development  
RUN ["chmod", "+x", "./migrate_and_serve.sh"]  
CMD [ "dumb-init", "--", "./migrate_and_serve.sh" ]  
```

--------------------------------

### Psychic CLI Model Generation and Database Reset

Source: https://psychicframework.com/docs/installation

Demonstrates common Psychic CLI commands for generating models and resetting the database within a TypeScript project after integration.

```bash
npm run psy g:model User email:string
npm run psy db:reset
```

--------------------------------

### Dream CLI Model Generation and Database Reset

Source: https://psychicframework.com/docs/installation

Shows how to use the Dream CLI for generating models and resetting the database when only Dream is integrated into a TypeScript project.

```bash
npm run dream g:model User email:string
npm run dream db:reset
```

--------------------------------

### Global Setup and Teardown for Feature Specs (TypeScript)

Source: https://psychicframework.com/docs/specs/feature

This code defines the global setup and teardown functions for Psychic feature specs. It launches and stops a Vite development server for the client application, specifying the port and command to run. This is essential for ensuring the client app is running during end-to-end tests.

```typescript
// spec/features/setup/globalSetup.ts  
  
import '../../../src/conf/global.js'  
  
import { PsychicDevtools } from '@rvoh/psychic'  
  
export async function setup() {  
  await PsychicDevtools.launchDevServer('client', {  
    port: 3000,  
    cmd: 'yarn client:fspec',  
  })
}
  
export function teardown() {
  PsychicDevtools.stopDevServer('client')
}

```

--------------------------------

### Integrate Psychic into Generic TypeScript Project

Source: https://psychicframework.com/docs/installation

Integrates Psychic into an existing TypeScript project without Next.js. Assumes a package.json and tsconfig file already exist. The CLI installs dependencies and adds boilerplate files.

```bash
cd my-typescript-app
npx @rvoh/create-psychic init
```

--------------------------------

### Auto-launching Psychic Client Dev Server

Source: https://psychicframework.com/docs/intro

Automatically launches the client dev server when the Psychic app starts in development mode. It uses `PsychicDevtools.launchDevServer` for starting and `PsychicDevtools.stopDevServer` for stopping. This functionality can be extended to launch multiple servers.

```typescript
export default async (psy: PsychicApp) => {
  ...
  psy.on('server:start', async psychicServer => {
    if (AppEnv.isDevelopment && AppEnv.boolean('CLIENT')) {
      await PsychicDevtools.launchDevServer('client', { port: 3000, cmd: 'yarn client' })
    }
  })

  psy.on('server:shutdown', () => {
    if (AppEnv.isDevelopment && AppEnv.boolean('CLIENT')) {
      PsychicDevtools.stopDevServer('client')
    }
  })
}
```

--------------------------------

### Setup Node.js Environment

Source: https://psychicframework.com/docs/deployment/ci

Sets up the Node.js environment for the specified version. This action is crucial for running Node.js-based build and dependency management commands.

```yaml
uses: actions/setup-node@v4
with:
  node-version: '22'
```

--------------------------------

### Equivalent preloading using leftJoinPreload and leftJoinPreloadFor

Source: https://psychicframework.com/docs/models/querying/leftJoinPreloadFor

This example demonstrates the equivalence between manually specifying nested preloads using leftJoinPreload and the simplified approach using leftJoinPreloadFor with the 'detail' serializer.

```javascript
// manually loading everything necessary for serialization
const user = await User
  .leftJoinPreload('posts', 'comments', ['images', 'videos'])
  .leftJoinPreload('posts', ['likes', 'similarPosts'])
  .firstOrFail()

// or tap into leftJoinPreloadFor to do this with ease!
const user = await User.leftJoinPreloadFor('detail').firstOrFail()
```

--------------------------------

### Test Suite for PostsController API

Source: https://psychicframework.com/docs/tutorials/blog

This TypeScript code defines unit tests for the PostsController in the API version 1. It covers GET index, GET show, POST create, and PATCH update actions. The tests ensure that posts are correctly retrieved, created, and updated for the authenticated user, and that posts belonging to other users are appropriately handled (omitted or not found). It uses factory functions for creating test data and includes session management for authentication.

```typescript
// api/spec/unit/controllers/Api/V1/PostsController.spec.ts  
  
import { UpdateableProperties } from '@rvoh/dream'  
import Post from '../../../../../src/app/models/Post.js'  
import User from '../../../../../src/app/models/User.js'  
import createPost from '../../../../factories/PostFactory.js'  
import createUser from '../../../../factories/UserFactory.js'  
import { session, SpecRequestType } from '../../../helpers/authentication.js'  
  
describe('Api/V1/PostsController', () => {  
  let request: SpecRequestType  
  let user: User  
  
  beforeEach(async () => {  
    user = await createUser()  
    request = await session(user)  
  })  
  
  describe('GET index', () => {  
    const subject = async <StatusCode extends 200 | 400>(expectedStatus: StatusCode) => {  
      return request.get('/api/v1/posts', expectedStatus)  
    }  

    it('returns the index of Posts', async () => {  
      const post = await createPost({ user })  

      const { body } = await subject(200)  

      expect(body).toEqual([  
        expect.objectContaining({  
          id: post.id,  
        }),  
      ])  
    })  

    context('Posts created by another User', () => {  
      it('are omitted', async () => {  
        await createPost()  

        const { body } = await subject(200)  

        expect(body).toEqual([])  
      })  
    })  
  })  
  
  describe('GET show', () => {  
    const subject = async <StatusCode extends 200 | 400 | 404>(post: Post, expectedStatus: StatusCode) => {  
      return request.get('/api/v1/posts/{id}', expectedStatus, {  
        id: post.id,  
      })  
    }  

    it('returns the specified Post', async () => {  
      const post = await createPost({ user })  

      const { body } = await subject(post, 200)  

      expect(body).toEqual(  
        expect.objectContaining({  
          id: post.id,  
          title: post.title,  
          body: post.body,  
        }),  
      )  
    })  

    context('Post created by another User', () => {  
      it('is not found', async () => {  
        const otherUserPost = await createPost()  

        await subject(otherUserPost, 404)  
      })  
    })  
  })  
  
  describe('POST create', () => {  
    const subject = async <StatusCode extends 201 | 400>(  
      data: UpdateableProperties<Post>,  
      expectedStatus: StatusCode  
    ) => {  
      return request.post('/api/v1/posts', expectedStatus, { data })  
    }  

    it('creates a Post for this User', async () => {  
      const { body } = await subject({  
        title: 'The Post title',  
        body: 'The Post body',  
      }, 201)  

      const post = await user.associationQuery('posts').firstOrFail()  
      expect(post.title).toEqual('The Post title')  
      expect(post.body).toEqual('The Post body')  

      expect(body).toEqual(  
        expect.objectContaining({  
          id: post.id,  
          title: post.title,  
          body: post.body,  
        }),  
      )  
    })  
  })  
  
  describe('PATCH update', () => {  
    const subject = async <StatusCode extends 204 | 400 | 404>(  
      post: Post,  
      data: UpdateableProperties<Post>,  
      expectedStatus: StatusCode  
    ) => {  
      return request.patch('/api/v1/posts/{id}', expectedStatus, {  
        id: post.id,  
        data,  
      })  
    }  

    it('updates the Post', async () => {  
      const post = await createPost({ user })  

      await subject(post, {  
        title: 'Updated Post title',  
        body: 'Updated Post body',  
      }, 204)  

      await post.reload()  
      expect(post.title).toEqual('Updated Post title')  
      expect(post.body).toEqual('Updated Post body')  
    })  

    context('a Post created by another User', () => {  
      it('is not updated', async () => {  
        const post = await createPost()  
        const originalTitle = post.title  
        const originalBody = post.body  

        await subject(post, {  
          title: 'Updated Post title',  
          body: 'Updated Post body',  
        }, 404)  

        await post.reload()  
        expect(post.title).toEqual(originalTitle)  
        expect(post.body).toEqual(originalBody)  
      })  
    })  

```

--------------------------------

### Clone Dream Project Repository

Source: https://psychicframework.com/docs/contributing/dream

This command clones the dream project from its GitHub repository to your local machine. It requires Git to be installed.

```bash
git clone https://github.com/rvohealth/dream
```

--------------------------------

### Psychic App Provisioning Prompts

Source: https://psychicframework.com/docs/tutorials/blog

Illustrates the interactive prompts encountered during the Psychic application provisioning process, showing example user selections for setting up a React client and disabling admin apps and background workers.

```bash
what package manager would you like to use?  
 > yarn  
   pnpm  
   npm  
  
what primary key type would you like to use?  
 > bigserial  
   serial  
   uuid  
  
Would you like a monorepo?  
For more info, see https://psychicframework.com/docs/monorepo  
 > yes  
   no  
  
which front end client would you like to use?  
   nextjs  
 > react  
   vue  
   nuxt  
   none  
  
which front end client would you like to use for your admin app?  
   nextjs  
   react  
   vue  
   nuxt  
 > none  
  
background workers?  
   yes  
 > no  
  
websockets? (beta)  
 > no  
   yes  
```

--------------------------------

### Add Globals to REPL Context with repl:start (TypeScript)

Source: https://psychicframework.com/docs/config/hooks

This code snippet shows how to add custom global variables to the REPL context when it starts. By listening to the 'repl:start' lifecycle hook and attaching properties to the provided context object, these globals become available in the REPL session. This example adds the 'chalupas' global.

```typescript
export default async function (app: DreamApp) {
  app.on('repl:start', context => {
    context.chalupas = 'delicious'
  })
}
```

```shell
yarn console
> chalupas
// 'delicious'
```

--------------------------------

### Provision New Psychic Application using npx

Source: https://psychicframework.com/docs/tutorials/blog

Initializes a new Psychic application named 'myblog' using the npx command. This command prompts for configuration details like package manager, primary key type, monorepo setup, and front-end client choices.

```bash
cd ~/Sites  
npx @rvoh/create-psychic myblog  
```

--------------------------------

### Scoping Routes Without Strict Folder Enforcement

Source: https://psychicframework.com/docs/routing/namespacing

Demonstrates the 'scope' method, which functions like 'namespace' but does not enforce the path segment in the controller's location. This example expects `UsersController` at `app/controllers/UsersController.ts` for the route `GET api/v1/users/hi`.

```typescript
r.scope('api', (r) => {  
  r.scope('v1', (r) => {  
    r.scope('users', (r) => {  
      r.get('hi')  
    })  
  })  
})
```

--------------------------------

### Sync OpenAPI to Redux using Psychic CLI

Source: https://psychicframework.com/docs/tutorials/blog

A command-line instruction to initiate the setup process for synchronizing OpenAPI specifications with Redux using the `openapi-redux` bridge within the Psychic framework. This command prompts the user for configuration details.

```bash
yarn psy setup:sync:openapi-redux

```

--------------------------------

### Troubleshooting: tsconfig CompilerOptions

Source: https://psychicframework.com/docs/installation

Specifies essential compiler options for the tsconfig file to prevent build failures when integrating Psychic or Dream. Ensures correct project compilation.

```json
{
  "compilerOptions": {
    ...
    "strictPropertyInitialization": false,
  }
}
```

--------------------------------

### POST /sign-up

Source: https://psychicframework.com/docs/tutorials/blog

Allows a new user to sign up for an account. It takes an email and password in the request body. If the email is already in use, it returns a conflict error.

```APIDOC
## POST /sign-up

### Description
Allows a new user to sign up for an account. It takes an email and password in the request body. If the email is already in use, it returns a conflict error.

### Method
POST

### Endpoint
/sign-up

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **email** (string) - Required - The email address of the user.
- **password** (string) - Required - The password for the user.

### Request Example
```json
{
  "email": "user@example.com",
  "password": "securepassword123"
}
```

### Response
#### Success Response (204)
- The request was successful, and no content is returned.

#### Error Response (409 Conflict)
- Returned if the email address is already in use.

#### Response Example (Success)
(No content)

#### Response Example (Conflict)
```json
{
  "message": "Email address already in use."
}
```
```

--------------------------------

### Install Psychic Workers Package using Yarn

Source: https://psychicframework.com/docs/plugins/workers/installation

This command installs the `@rvoh/psychic-workers` package and its dependencies using the Yarn package manager. Ensure Yarn is installed and configured in your project.

```bash
yarn add @rvoh/psychic-workers
```

--------------------------------

### Initiate and Use Database Transaction

Source: https://psychicframework.com/docs/models/transactions

Demonstrates how to start a database transaction using `ApplicationModel.transaction` and apply it to subsequent queries by passing the transaction object to model methods via `.txn(txn)`.

```javascript
await ApplicationModel.transaction(async txn => {
  const user = await User.txn(txn).create({ ... });
  await UserSettings.txn(txn).create({ user });
});
```

--------------------------------

### Install Dependencies with yarn

Source: https://psychicframework.com/docs/deployment/ci

Installs project dependencies using 'yarn install --immutable'. The --immutable flag ensures that the exact versions specified in the lock file are installed, promoting reproducible builds.

```shell
run: yarn install --immutable
```

--------------------------------

### POST /sign-in

Source: https://psychicframework.com/docs/tutorials/blog

Allows a user to sign in to the system using their email and password. It validates credentials and establishes a session.

```APIDOC
## POST /sign-in

### Description
This endpoint allows users to authenticate by providing their email and password. Upon successful authentication, a session cookie is set, and a 204 No Content response is returned. If authentication fails due to invalid credentials or an unknown email, a 401 Unauthorized response is returned.

### Method
POST

### Endpoint
/sign-in

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "data": {
    "email": "how@yadoin",
    "password": "mypassword"
  }
}
```

### Response
#### Success Response (204)
No content is returned upon successful sign-in. A session cookie is set in the response headers.

#### Error Response (401)
- **error** (string) - Description of the authentication failure (e.g., 'Unauthorized').

#### Response Example (Success)
(No JSON body, check Set-Cookie header for session information)

#### Response Example (Error)
```json
{
  "error": "Unauthorized"
}
```
```

--------------------------------

### Install Dependencies with Yarn

Source: https://psychicframework.com/docs/deployment/ci

Installs project dependencies using 'yarn install --immutable' for both the API and client directories. The '--immutable' flag ensures that the installation uses the exact versions specified in the lock file.

```yaml
- run: yarn install --immutable
- run: yarn install --immutable
    working-directory: ./client
```

--------------------------------

### Database Creation Confirmation

Source: https://psychicframework.com/docs/tutorials/blog

Output indicating the successful creation of 'myblog_test' and 'myblog_development' PostgreSQL databases by the Psychic CLI.

```bash
✺ ┌ creating myblog_test...  
  └ complete  
✺ ┌ creating myblog_development...  
  └ complete  
```

--------------------------------

### Create Development and Test Databases

Source: https://psychicframework.com/docs/tutorials/blog

Command to create new PostgreSQL databases for development and testing environments using the Psychic CLI. Ensures the correct `NODE_ENV` is set before execution.

```bash
# always make sure you are in the api folder before running any psy commands  
cd api  
  
NODE_ENV=test yarn psy db:create  
NODE_ENV=development yarn psy db:create  
```

--------------------------------

### Test Authenticated Endpoint in JavaScript

Source: https://psychicframework.com/docs/specs/unit

This JavaScript example tests an authenticated endpoint by simulating user sign-in and subsequent requests. It uses Psychic's testing helpers to create a user, initialize the server, establish a session, and then make a GET request to a protected route ('/api/v1/users/me'), expecting a 200 status. Dependencies include '@rvoh/psychic' and '@rvoh/psychic-spec-helpers'.

```javascript
describe('an authed user attempts to hit an authed route', () => {
  beforeEach(async () => {
    await createUser({ email: 'how@yadoin', password: 'password' })
    await request.init(PsychicServer)
  })

  it('returns 200', async () => {
    const session = await request.session('/api/v1/signin', 204, {
      data: { email: 'how@yadoin', password: 'password' },
    })
    await session.get('/api/v1/users/me').expect(200)
  })
})
```

--------------------------------

### Initialize Psychic App with Websockets (TypeScript)

Source: https://psychicframework.com/docs/plugins/websockets/config

TypeScript code to integrate websockets initialization into the main Psychic application setup. This involves importing necessary classes and calling `PsychicAppWebsockets.init`.

```typescript
import { PsychicApp, PsychicAppInitOptions } from '@rvoh/psychic'  
import { PsychicAppWebsockets } from '@rvoh/psychic-websockets'  
import psychicConf from '../../conf/app'  
import dreamConf from '../../conf/dream'  
import websocketsConf from '../../conf/websockets'  
  
export default async function initializePsychicApp(opts: PsychicAppInitOptions = {}) {  
  const psychicApp = await PsychicApp.init(psychicConf, dreamConf, opts)  
  await PsychicAppWebsockets.init(psychicApp, websocketsConf)  
  // ...  
  return psychicApp  
}
```

--------------------------------

### Register Websocket Connections with Ws Class - TypeScript

Source: https://psychicframework.com/docs/plugins/websockets/overview

This snippet demonstrates how to register websocket connections using the `Ws.register` method within the `conf/app.ts` file. It captures a token from the socket handshake, decrypts it to get a user ID, finds the user, and then registers the socket with the user if found. This setup is crucial for enabling targeted message emission to specific users.

```typescript
// conf/app.ts  

export default async (psy: PsychicApp) => {  
  ...

  psy.on('ws:start', io => {  
    io.of('/').on('connection', async socket => {  
      const token = socket.handshake.auth.token as string
      const userId = Encrypt.decrypt(token, {  
        algorithm: 'aes-256-gcm',
        key: AppEnv.string('APP_ENCRYPTION_KEY'),
      })
      const user = await User.find(userId)

      if (user) {
        await Ws.register(socket, user)
      }
    })
  })

  ...
})
```

--------------------------------

### Run Database Migrations with Psychic CLI

Source: https://psychicframework.com/docs/tutorials/blog

Commands to execute database migrations. It shows how to set the NODE_ENV to 'test' or 'development' before running the migrate command using the Psychic CLI, ensuring the database schema is updated.

```bash
NODE_ENV=test yarn psy db:migrate
```

```bash
NODE_ENV=development yarn psy db:migrate
```

--------------------------------

### Create Websocket Singleton (TypeScript)

Source: https://psychicframework.com/docs/plugins/websockets/config

TypeScript example demonstrating how to create a singleton instance of the `Ws` class for simplified websocket integration within your application. Defines a constant for WebSocket routes.

```typescript
import { Ws } from '@rvoh/psychic-websockets'  
  
export const WS_ROUTES = ['/ops/connection-success'] as const  
  
const ws = new Ws(WS_ROUTES)  
  
export default ws
```

--------------------------------

### Generated Project Structure Overview

Source: https://psychicframework.com/docs/tutorials/blog

Displays the basic directory structure created after provisioning a Psychic application, highlighting the 'api' folder for the Psychic app and the 'client' folder for the isolated React application.

```tree
├── myblog  
│   ├── api                 # this is where your Psychic app lives  
│   ├── client              # this is where your React app lives  
```

--------------------------------

### Configure Redux Store with RTK Query

Source: https://psychicframework.com/docs/tutorials/blog

Sets up the Redux store using configureStore from Redux Toolkit, integrating the reducer and middleware for the myblogApi generated by RTK Query.

```typescript
// client/src/store.ts

import { configureStore } from '@reduxjs/toolkit'
import appReducer from './reducers/appReducer'
import { myblogApi } from './api/myblogApi'

export const store = configureStore({
  reducer: {
    app: appReducer,
    [myblogApi.reducerPath]: myblogApi.reducer,
  },
  middleware: gDM => gDM().concat(myblogApi.middleware),
})

export type AppStore = typeof store
export type RootState = ReturnType<AppStore['getState']>
export type AppDispatch = AppStore['dispatch']

```

--------------------------------

### Show Help for Psychic Generators

Source: https://psychicframework.com/docs/models/generating

These commands display the help information for the various Psychic code generation commands, providing details on their options and usage. This is useful for understanding the full capabilities of each generator.

```bash
yarn psy g:model  --help  
yarn psy g:sti-child  --help  
yarn psy g:resource  --help  
```

--------------------------------

### Instantiate and Format Dates with Dream's DateTime and CalendarDate

Source: https://psychicframework.com/docs/utils/date-time

Demonstrates the correct way to instantiate and manipulate date and time objects using Dream's DateTime and CalendarDate. It highlights the avoidance of JavaScript's native Date class and shows examples of getting the current time, today's date, formatting, and performing date arithmetic. Requires importing from '@rvoh/dream'.

```javascript
// ❌ DON'T DO THIS  
const badDate = new Date()  
const badParsed = new Date('2024-01-15')  
  
// ✅ DO THIS INSTEAD - Built-in math and formatting  
import { DateTime, CalendarDate } from '@rvoh/dream'  
const goodDateTime = DateTime.now()  
const goodDate = CalendarDate.today()  
const formatted = goodDateTime.toFormat('yyyy-MM-dd HH:mm')  
const tomorrow = goodDate.plus({ days: 1 })  
```

--------------------------------

### Create Signup Page Component

Source: https://psychicframework.com/docs/tutorials/blog

This snippet demonstrates the creation of a simple signup page component (`client/src/pages/unauthed/SignupPage.tsx`). It includes state management for email and password using `useState` and a basic form structure with input fields and a submit button. The submission logic is a placeholder, awaiting backend integration.

```tsx
// client/src/pages/unauthed/SignupPage.tsx

import { useState } from "react"

export default function SignupPage() {
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')

  return (
    <div>
      <input id="email" onChange={e => setEmail(e.target.value)} />
      <input id="password" onChange={e => setPassword(e.target.value)}/>
      <button
        onClick={() => {
          // submit login
        }}
      >Submit</button>
    </div>
  )
}

```

--------------------------------

### Check Chrome and ChromeDriver Installation

Source: https://psychicframework.com/docs/deployment/ci

Verifies that Google Chrome and ChromeDriver are installed and accessible in the CI environment. This is typically required for browser automation tasks.

```yaml
- name: 'Check chrome and chromedriver are installed'
  run: |
    google-chrome --version
    which google-chrome
    chromedriver --version
    which chromedriver
```

--------------------------------

### Create User Table Migration with Kysely

Source: https://psychicframework.com/docs/tutorials/blog

Defines the database migration for creating the 'users' table. It specifies columns for ID, email, password digest, and timestamps. Includes functions for both applying (up) and reverting (down) the migration.

```typescript
// src/db/migrations/1750783840641-create-user.ts  
  
import { Kysely, sql } from 'kysely'  
  
// eslint-disable-next-line @typescript-eslint/no-explicit-any  
export async function up(db: Kysely<any>): Promise<void> {  
  await db.schema  
    .createTable('users')  
    .addColumn('id', 'bigserial', col => col.primaryKey())  
    .addColumn('email', 'varchar(255)', col => col.notNull())  
    .addColumn('password_digest', 'varchar(255)', col => col.notNull())  
    .addColumn('created_at', 'timestamp', col => col.notNull())  
    .addColumn('updated_at', 'timestamp', col => col.notNull())  
    .execute()  
}  
  
// eslint-disable-next-line @typescript-eslint/no-explicit-any  
export async function down(db: Kysely<any>): Promise<void> {  
  await db.schema.dropTable('users').execute()  
}
```

--------------------------------

### Feature Spec for Showing a Post (TypeScript)

Source: https://psychicframework.com/docs/tutorials/blog

This TypeScript spec defines the behavior for showing a blog post. It uses factory functions to create users and posts, signs in a user, navigates to the post index, clicks a post title, and asserts that the post's title is displayed on the show page. It relies on helper functions like `createUser`, `createPost`, `signIn`, `clickLink`, and `expect`. The initial run is expected to fail due to missing navigation elements.

```typescript
import createPost from '../../factories/PostFactory.js'
import createUser from '../../factories/UserFactory.js'
import signIn from '../helpers/signIn.js'

describe('show Post', () => {
  it('allows a user to show a Post', async () => {
    const user = await createUser()
    await createPost({ user, title: 'my post title' })
    await signIn(user)

    await clickLink('Posts')
    await clickLink('my post title')
    await expect(page).toHaveSelector('h1::-p-text("my post title")')
  })
})
```

--------------------------------

### Install Passport and Session Dependencies with Yarn

Source: https://psychicframework.com/docs/tutorials/passport

Installs the necessary packages for Passport.js local authentication and express-session. This includes Passport, passport-local, their type definitions, express-session, and its type definitions.

```bash
yarn add passport passport-local @types/passport @types/passport-local express-session @types/express-session  
```

--------------------------------

### Generate User Model with Psychic CLI

Source: https://psychicframework.com/docs/tutorials/blog

Command to generate a new User model, including its associated files like model, spec, factory, serializer, and migration. This sets up the basic structure for user authentication in a blog application.

```bash
yarn psy g:dream User email:string passwordDigest:string
```

--------------------------------

### Serializer Chain Example

Source: https://psychicframework.com/docs/models/querying/loadFor

Defines a nested serializer chain including UserSerializer, PostSerializer, and CommentSerializer to illustrate the complexity that loadFor can simplify. This example shows how associations are rendered and delegated.

```typescript
const UserSerializer = (user: User) => DreamSerializer(User, user)
  .rendersMany('posts')

const PostSerializer = (post: Post) => DreamSerializer(Post, post)
  .rendersMany('comments')
  .rendersMany('likes')
  .rendersMany('similarPosts')

const CommentSerializer = (post: Post) => DreamSerializer(Post, post)
  .rendersMany('images')
  .rendersMany('videos')

class User extends ApplicationModel {
  public get serializers() {
    return {
      // ...
      detail: UserSerializer,
    } as const
  }
}
```

--------------------------------

### Install and Enable Corepack

Source: https://psychicframework.com/docs/deployment/ci

Installs the 'corepack' package manager globally using npm and then enables it. Corepack provides a way to manage different package managers like Yarn and pnpm.

```shell
run: npm install -g corepack
run: corepack enable
```

--------------------------------

### Configure Redux Store and Type Definitions

Source: https://psychicframework.com/docs/tutorials/blog

Sets up the Redux store using `configureStore` from Redux Toolkit, combining reducers. It also defines TypeScript types for the store, root state, and dispatch for better type safety.

```ts
import { configureStore } from '@reduxjs/toolkit'
import appReducer from './reducers/appReducer'

export const store = configureStore({
  reducer: {
    app: appReducer,
  }
})

// Get the type of our store variable
export type AppStore = typeof store
// Infer the `RootState` and `AppDispatch` types from the store itself
export type RootState = ReturnType<AppStore['getState']>
// Inferred type: {posts: PostsState, comments: CommentsState, users: UsersState}
export type AppDispatch = AppStore['dispatch']

```

--------------------------------

### Integrate Psychic into Next.js Project

Source: https://psychicframework.com/docs/installation

Adds Psychic and/or Dream to an existing Next.js project. Navigates to the project root and uses the create-psychic CLI. It automatically handles dependencies and provides a sidecar for launching the Psychic server with the Next.js dev server.

```bash
cd my-nextjs-app
npx @rvoh/create-psychic init --template=nextjs
```

--------------------------------

### Implement AuthSessionController for Sign-up - TypeScript

Source: https://psychicframework.com/docs/tutorials/blog

This code implements the AuthSessionController, including the 'signUp' method. It uses OpenAPI decorators to define the endpoint's expected request body and response status (204 No Content). It handles user creation and returns a conflict response if the email already exists.

```typescript
// api/src/app/controllers/AuthSessionController.ts  
  
import { OpenAPI } from '@rvoh/psychic'
import AuthedController from './AuthedController.js'
import User from '../models/User.js'
  
const openApiTags = ['auth-session']  
  
export default class AuthSessionController extends AuthedController {
  @OpenAPI(User, {
    status: 204,
    tags: openApiTags,
    requestBody: {
      only: ['email', 'password']
    }
  })
  public async signUp() {
    const email = this.castParam('email', 'string')
    const password = this.castParam('password', 'string')
    try {
      await User.create({ email, password })
    } catch {
      this.conflict()
    }

    this.noContent()
  }
}

```

--------------------------------

### Integrate Dream Only into TypeScript Project

Source: https://psychicframework.com/docs/installation

Integrates only the Dream ORM into an existing TypeScript project, excluding Psychic dependencies. It installs necessary dependencies for Dream and provides a separate CLI command for Dream operations.

```bash
cd my-typescript-app
npx @rvoh/create-psychic init --dream-only
```

--------------------------------

### Post Index Page Implementation (React)

Source: https://psychicframework.com/docs/tutorials/blog

This React component renders the index page for blog posts. It uses a custom hook `useGetApiV1PostsQuery` to fetch posts and displays them. Each post is rendered as a div containing a `react-router` `Link` component, which provides navigation to the individual post's show page based on its ID and title. It includes a loading state if posts are not yet available.

```javascript
import { Link } from 'react-router-dom'
import { useGetApiV1PostsQuery } from '../../../api/myblogApi'

export default function PostsIndexPage() {
  const { data: posts } = useGetApiV1PostsQuery()
  if (!posts) return <div>loading...</div>

  return (
    <div>
      {posts.map(post => (
        <div key={post.id}>
          <Link to={`/posts/${post.id}`}>{post.title}</Link>
        </div>
      ))}
    </div>
  )
}
```

--------------------------------

### Psychic Framework: AfterCreate Hook Example

Source: https://psychicframework.com/docs/models/hooks

The AfterCreate hook runs after a new record has been successfully saved to the database. Similar to BeforeCreate, it uses a decorator pattern. This example shows hashing a password post-creation.

```typescript
export default class Post extends Dream {
  public readonly get table() {
    return 'posts' as const
  }

  public id: number
  public content: string | null
  ...

  @deco.AfterCreate()
  public async hashPassword() {
    if (this.password)
      this.password_digest = await Hash.gen(this.password)
    this.password = undefined
  }
}
```

--------------------------------

### Sign-in Helper Function (TypeScript)

Source: https://psychicframework.com/docs/tutorials/blog

Defines a reusable asynchronous helper function `signIn` to handle user authentication. It abstracts the steps of visiting the sign-in page, filling in credentials, submitting the form, and verifying successful login. Dependencies include 'User' model and Psychic's testing utilities.

```typescript
// api/spec/features/helpers/signIn.ts  
  
import User from '../../../src/app/models/User.js'  
  
export default async function signIn(user: User, password: string = 'abc123') {  
  await visit('/')  
  await clickLink('Sign in')  
  await fillIn('#email', user.email)  
  await fillIn('#password', password)  
  await clickButton('Submit')  
  await expect(page).toMatchTextContent('Dashboard')  
}  

```

--------------------------------

### Vitest Unit Test Setup Hooks (TypeScript)

Source: https://psychicframework.com/docs/specs/unit

These setup hooks are executed during Vitest unit test runs. They provide necessary matchers, initialize the Psychic app, and truncate the database before each test to ensure isolation.

```typescript
// api/spec/unit/setup/hooks.ts  
  
provideDreamViteMatchers()
  
beforeAll(async () => {
  await initializePsychicApp()
})
  
beforeEach(async () => {
  await truncate(DreamApp)
})

```

--------------------------------

### Commit Changes with Git

Source: https://psychicframework.com/docs/tutorials/blog

Standard Git commands to stage all modified files and commit them with a descriptive message. This is used after successfully generating and migrating the User model to save the progress.

```bash
git add --all
git commit -m 'Add User model'
```

--------------------------------

### Define Basic Route with GET Verb in Psychic Framework

Source: https://psychicframework.com/docs/routing/overview

Demonstrates how to define a simple GET route for a health check using the PsychicRouter. This requires importing PsychicRouter and defining a default export function that accepts the router instance.

```typescript
import { PsychicRouter } from 'psychic'  
  
export default (r: PsychicRouter) => {  
  r.get('/health-check')  
}
```
Tokens:
Raw