Pylon

https://pylon.cronit.io/docs
Admin
Pylon is a code-first GraphQL API development framework that automatically generates GraphQL schemas...
Tokens:24,484
Snippets:297
Trust Score:5.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://pylon.cronit.io/docs/contributing/how-to-contribute

Navigate to the project directory and install required dependencies.

```bash
cd pylon
npm install
```

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

### Install prisma-extended-models

Source: https://pylon.cronit.io/docs/integrations/databases

Install the package using the bun package manager.

```bash
bun add @getcronit/prisma-extended-models
```

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

### Start the development server

Source: https://pylon.cronit.io/docs/getting-started

Commands to enter the project directory and launch the local development environment.

```bash
cd my-pylon
npm run dev
```

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

### Install Pylon Dependencies

Source: https://pylon.cronit.io/docs/guides/convert-from-hono-guide

Commands to install Pylon development and runtime dependencies.

```bash
bun add -D @getcronit/pylon-dev
bun add @getcronit/pylon
```

```bash
npm install --save-dev @getcronit/pylon-dev
bun add @getcronit/pylon
```

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

### Starting the Development Server

Source: https://pylon.cronit.io/docs/guides/convert-from-hono-guide

Commands to launch the application server using either Bun or Node package managers.

```bash
bun run dev
```

```bash
npm run dev
```

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

### Initialize Pylon with GQty

Source: https://pylon.cronit.io/docs/integrations/gqty

The interactive CLI setup process for creating a new Pylon project with GQty client generation enabled.

```text
create-pylon version 1.0.0                                                                                                                                                                                                 4:55:00 PM
? Target directory my-pylon
? Which runtime would you like to use? Bun.js (https://bunjs.dev)
? Which template would you like to use? Default
? Would you like to install dependencies? no
◐ Creating pylon in /Users/schettn/Documents/my-pylon                                                                                                                                          4:55:11 PM
✔ Pylon created                                                                                                                                                                                                           4:55:11 PM
? Would you like to enable client generation? (https://pylon.cronit.io/docs/integrations/gqty) yes
? Path to the root where the client should be generated .
? Path to generate the client to gqty/index.ts
? Port of the pylon server to generate the client from 3000
◐ Updating pylon dev script to generate client                                                                                                                                                                             4:55:20 PM
✔ Pylon dev script updated                                                                                                                                                                                                4:55:20 PM
 
 ╭───────────────────────────────────────────╮
 │                                           │
 │  Pylon successfully created in my-pylon.  │
 │                                           │
 │  Happy coding!                            │
 │                                           │
 ╰───────────────────────────────────────────╯
```

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

### Implement Pylon GraphQL Server with Interfaces

Source: https://pylon.cronit.io/docs/release-notes/v2.3

A complete example demonstrating how to use TypeScript interfaces and unions within a Pylon application.

```typescript
import {app, ID} from '@getcronit/pylon'
 
type Node = User | Post
 
interface User {
  id: ID
  name: string
}
 
interface Post {
  id: ID
  title: string
}
 
const nodes: Node[] = [
  {id: '1', name: 'John Doe'},
  {id: '2', name: 'Jane Doe'},
  {id: '3', title: 'Hello, World!'},
  {id: '4', title: 'Hello, Pylon!'}
]
 
export const graphql = {
  Query: {
    node: (id: ID): Node => {
      const node = nodes.find(node => node.id === id)
      if (!node) throw new Error('Node not found')
      return node
    }
  }
}
 
export default app
```

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

### Project Structure

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/integrating-prisma

The recommended directory structure after installing and configuring Prisma in a Pylon project.

```text
my-pylon/
├── .pylon/
├── prisma/
│   ├── migrations/
│   ├── schema.prisma
├── src/
│   ├── index.ts
├── package.json
├── tsconfig.json
```

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

### Update start and build scripts

Source: https://pylon.cronit.io/docs/release-notes/migrating-from-v1-to-v2

Update package.json scripts to use the new pylon dev command and simplified build command.

```json
{
  "scripts": {
-    "develop": "bun run pylon develop"
+    "dev": "pylon dev -c 'bun run .pylon/index.js'"
  }
}
```

```json
{
  "scripts": {
-    "build": "bun run pylon build"
+    "build": "pylon build"
  }
}
```

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

### Test GraphQL Query

Source: https://pylon.cronit.io/docs/guides/testing

Example test file for verifying the GraphQL posts query.

```typescript
import {describe, expect, test} from 'bun:test'
// Make sure to run `bun run build` before running the tests
import app from './.pylon/index'
 
describe('GraphQL API', () => {
  test('Query.posts', async () => {
    const res = await app.request('/graphql', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        query: 'query { posts { id title content } }'
      })
    })
    expect(res.status).toBe(200)
    const data = await res.json<any>()
    expect(data).toEqual({
      data: {
        posts: [
          {
            id: 1,
            title: 'Hello, world!',
            content: 'This is the first post'
          },
          {
            id: 2,
            title: 'Hello, Pylon!',
            content: 'This is the second post'
          }
        ]
      }
    })
  })
})
```

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

### Configure Dockerfile for Prisma

Source: https://pylon.cronit.io/docs/integrations/databases

This Dockerfile template handles dependency installation, Prisma client generation, and production build steps for a Pylon project.

```dockerfile
# use the official Bun image
# see all versions at https://hub.docker.com/r/oven/bun/tags
FROM oven/bun:1 as base
 
LABEL description="A Pylon project with Prisma"
LABEL org.opencontainers.image.source="https://github.com/cronitio/my-pylon-project"
LABEL maintainer="opensource@cronit.io"
 
WORKDIR /usr/src/pylon
 
# install dependencies into temp directory
# this will cache them and speed up future builds
FROM base AS install
ARG NODE_VERSION=20
RUN apt update \
    && apt install -y curl
RUN curl -L https://raw.githubusercontent.com/tj/n/master/bin/n -o n \
    && bash n $NODE_VERSION \
    && rm n \
    && npm install -g n
 
RUN mkdir -p /temp/dev
COPY package.json bun.lockb /temp/dev/
COPY prisma /temp/dev/prisma
 
RUN cd /temp/dev && bun install --frozen-lockfile
RUN cd /temp/dev && bun prisma generate
 
# install with --production (exclude devDependencies)
RUN mkdir -p /temp/prod
COPY package.json bun.lockb /temp/prod/
COPY prisma /temp/prod/prisma
 
RUN cd /temp/prod && bun install --frozen-lockfile --production
RUN cd /temp/prod && bun prisma generate
 
# copy node_modules from temp directory
# then copy all (non-ignored) project files into the image
FROM install AS prerelease
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
 
# [optional] tests & build
ENV NODE_ENV=production
 
# Create .pylon folder (mkdir)
RUN mkdir .pylon
# RUN bun test
RUN bun run pylon build
 
# copy production dependencies and asource code into final image
FROM base AS release
RUN apt-get update -y && apt-get install -y openssl
COPY --from=install /temp/prod/node_modules node_modules
COPY --from=prerelease /usr/src/pylon/.pylon .pylon
COPY --from=prerelease /usr/src/pylon/package.json .
COPY --from=prerelease /usr/src/pylon/prisma prisma
 
# run the app
USER bun
EXPOSE 3000/tcp
ENTRYPOINT [ "bun", "run", "./node_modules/.bin/pylon-server" ]
```

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

### Execute GraphQL Mutation

Source: https://pylon.cronit.io/docs/core-concepts/type-safety-and-type-integration

Example of a GraphQL mutation to update user information.

```graphql
mutation {
  updateUser(
    user: {
      id: 1
      name: "Jane Doe"
      age: 30
      address: {street: "456 Elm St", city: "Othertown", zipCode: "67890"}
    }
  ) {
    id
    name
    age
    address {
      street
      city
      zipCode
    }
  }
}
```

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

### Execute GraphQL Query

Source: https://pylon.cronit.io/docs/core-concepts/type-safety-and-type-integration

Example of a GraphQL query to fetch user details by ID.

```graphql
query {
  getUser(id: 1) {
    id
    name
    age
    address {
      street
      city
      zipCode
    }
  }
}
```

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

### Implement REST GET /posts Endpoint

Source: https://pylon.cronit.io/docs/guides/testing

Add a GET route to the Pylon application to return a list of posts.

```typescript
import {app} from '@getcronit/pylon'
 
const posts: {id: number; title: string; content: string}[] = [
  {
    id: 1,
    title: 'Hello, world!',
    content: 'This is the first post'
  },
  {
    id: 2,
    title: 'Hello, Pylon!',
    content: 'This is the second post'
  }
]
 
export const graphql = {
  // ... (previous code remains unchanged)
}
 
app.get('/posts', c => {
  return c.json(posts)
})
 
export default app
```

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

### Test REST API GET /posts

Source: https://pylon.cronit.io/docs/guides/testing

Verify the REST GET endpoint using the Bun test framework.

```typescript
import {describe, expect, test} from 'bun:test'
// Make sure to run `bun run build` before running the tests
import app from './.pylon/index'
 
describe('GraphQL API', () => {
  // ... (previous tests remains unchanged)
})
 
describe('REST API', () => {
  test('GET /posts', async () => {
    const res = await app.request('/posts')
    expect(res.status).toBe(200)
    const data = await res.json<any>()
    expect(data).toEqual([
      {
        id: 1,
        title: 'Hello, world!',
        content: 'This is the first post'
      },
      {
        id: 2,
        title: 'Hello, Pylon!',
        content: 'This is the second post'
      },
      {
        id: 3,
        title: 'New Post',
        content: 'This is a new post'
      }
    ])
  })
})
```

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

### Integrate Envelop Plugin in Pylon

Source: https://pylon.cronit.io/docs/core-concepts/plugins

Full example demonstrating the import, configuration, and usage of an Envelop error handler within a Pylon application.

```typescript
import {app, PylonConfig, ServiceError} from '@getcronit/pylon'
import {useErrorHandler} from '@envelop/core'
 
export const graphql = {
  Query: {
    hello: () => {
      throw new ServiceError('Hello, world!', {
        code: 'HELLO_WORLD',
        statusCode: 400
      })
    }
  },
  Mutation: {}
}
 
export const config: PylonConfig = {
  plugins: [
    useErrorHandler(({errors, context, phase}) => {
      console.error(errors)
    })
  ]
}
 
export default app
```

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

### Defining the Prisma Schema

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/integrating-prisma

Example Prisma schema models for Booking and BookingDates entities.

```prisma
model Booking {
  id              Int          @id @default(autoincrement())
  firstname       String
  lastname        String
  totalprice      Float
  depositpaid     Boolean
  bookingdates    BookingDates? @relation(fields: [bookingDatesId], references: [id])
  additionalneeds String?
 
  bookingDatesId Int
}
 
model BookingDates {
  id       Int    @id @default(autoincrement())
  checkin  String
  checkout String
 
  booking Booking[]
}
```

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

### Query paginated posts via GraphQL

Source: https://pylon.cronit.io/docs/integrations/databases

Example GraphQL query demonstrating the use of paginated connections and resolved relations.

```graphql
query {
  allPosts {
    edges {
      node {
        id
        title
        content
        author {
          id
          name
        }
      }
    }
  }
}
```

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

### Implement extended models in a Pylon service

Source: https://pylon.cronit.io/docs/integrations/databases

Example of using extended models for queries and mutations within a Pylon application.

```typescript
import {app} from '@getcronit/pylon'
import {Post} from '../repository/models'
 
export const graphql = {
  Query: {
    // Example query using extended Prisma models
    getPost: async (id: number) => {
      return await Post.get({
        id
      })
    },
    allPosts: async () => {
      return await Post.paginate()
    }
  },
  Mutation: {
    // Example mutation using extended Prisma models
    createPost: async (data: any) => {
      return await Post.create({
        data
      })
    }
  }
}
 
export default app
```

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

### Define GraphQL Resolver with ServiceError

Source: https://pylon.cronit.io/docs/core-concepts/plugins

Example of a GraphQL resolver that throws a ServiceError, which is then intercepted by the configured Envelop plugin.

```typescript
export const graphql = {
  Query: {
    hello: () => {
      throw new ServiceError('Hello, world!', {
        code: 'HELLO_WORLD',
        statusCode: 400
      })
    }
  },
  Mutation: {}
}
```

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

### Initialize a new Pylon project

Source: https://pylon.cronit.io/docs/getting-started

Use this command to scaffold a new project directory with the necessary configuration files.

```bash
npm create pylon my-pylon@latest
```

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

### Initialize Basic Pylon Application

Source: https://pylon.cronit.io/docs/guides/testing

Sets up the foundation for a Pylon application with an empty posts array.

```typescript
import {app} from '@getcronit/pylon'
 
const posts: {id: number; title: string; content: string}[] = []
 
export default app
```

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

### Build for production

Source: https://pylon.cronit.io/docs/getting-started

Compiles the project into the .pylon directory for production use.

```bash
npm run build
```

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

### Manual production deployment

Source: https://pylon.cronit.io/docs/getting-started

Commands to execute the production build using Node.js or Bun.

```bash
node .pylon/index.js
 
# Or, if you are using Bun:
bun run .pylon/index.js
```

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

### Deploy using Docker

Source: https://pylon.cronit.io/docs/getting-started

Commands to build and run the project within a Docker container.

```bash
docker build -t my-pylon .
docker run -p 3000:3000 my-pylon
```

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

### Run Tests

Source: https://pylon.cronit.io/docs/guides/testing

Command to execute the test suite.

```bash
bun test
```

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

### Initialize Pylon Application Instance

Source: https://pylon.cronit.io/docs/core-concepts/context-management

Import the Pylon app instance to define GraphQL resolvers and custom Hono routes.

```typescript
import {app} from '@getcronit/pylon'
 
export const graphql = {
  Query: {
    sum: (a: number, b: number) => a + b
  },
  Mutation: {
    divide: (a: number, b: number) => a / b
  }
}
 
app.get('/hello', (ctx, next) => {
  return new Response('Hello, world!')
})
 
export default app
```

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

### Build Pylon Application

Source: https://pylon.cronit.io/docs/guides/testing

Command to generate the GraphQL API schema.

```bash
bun run build
```

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

### Import Pylon app

Source: https://pylon.cronit.io/docs/core-concepts/automatic-graphql-api-generation

Initialize the Pylon application by importing the app instance.

```typescript
import {app} from '@getcronit/pylon'
```

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

### Configure Environment Variables

Source: https://pylon.cronit.io/docs/core-concepts/built-in-authentication-and-authorization

Set these variables in your project environment to enable OIDC authentication via ZITADEL.

```text
AUTH_ISSUER=https://test-0o6zvq.zitadel.cloud
AUTH_PROJECT_ID=<your_auth_project_id>
```

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

### Verify Project Directory Structure

Source: https://pylon.cronit.io/docs/guides/convert-from-hono-guide

Ensure your project follows the required file layout, specifically keeping index.ts directly under the src directory.

```text
my-pylon
│
├── .dockerignore
├── .gitignore
├── bun.lockb
├── Dockerfile
├── package.json
├── pylon.d.ts
├── tsconfig.json
│
└───src
    └──index.ts
```

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

### Initial Pylon index.ts Configuration

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/hardcoded-data

The default state of the index.ts file before integrating the new booking store methods.

```typescript
import {app} from '@getcronit/pylon'
 
export const graphql = {
  Query: {
    hello: () => 'Hello World'
  },
  Mutation: {}
}
 
export default app
```

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

### Define a hello query in Pothos

Source: https://pylon.cronit.io/docs/faq

Demonstrates the schema definition approach using Pothos with SchemaBuilder.

```typescript
import { createYoga } from 'graphql-yoga';
import { createServer } from 'node:http';
import SchemaBuilder from '@pothos/core';
 
const builder = new SchemaBuilder({});
 
builder.queryType({
  fields: (t) => ({
    hello: t.string({
      args: {
        name: t.arg.string(),
      },
      resolve: (parent, { name }) => `hello, ${name || 'World'}`,
    }),
  }),
});
 
...
```

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

### Clone the Repository

Source: https://pylon.cronit.io/docs/contributing/how-to-contribute

Use this command to clone your forked repository to your local machine.

```bash
git clone https://github.com/your-username/pylon.git
```

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

### Replace CLI and server dependencies

Source: https://pylon.cronit.io/docs/release-notes/migrating-from-v1-to-v2

Remove the deprecated CLI and server packages and add @getcronit/pylon-dev.

```json
{
  "devDependencies": {
-    "@getcronit/pylon-cli": "^1.0.0",
-    "@getcronit/pylon-server": "^1.0.0"
+    "@getcronit/pylon-dev": "^2.0.0"
  }
}
```

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

### Define a hello query in Pylon

Source: https://pylon.cronit.io/docs/faq

Demonstrates the schema inference approach using Pylon where the schema is derived from TypeScript types.

```typescript
import {app} from '@getcronit/pylon'
 
export const graphql = {
  Query: {
    hello: (name: string) => {
      return `hello, ${name || 'World'}`
    }
  }
}
 
export default app
```

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

### Update Dockerfile entrypoint

Source: https://pylon.cronit.io/docs/release-notes/migrating-from-v1-to-v2

Update the Dockerfile to point to the new runtime index file.

```dockerfile
- ENTRYPOINT [ "bun", "run", "./node_modules/.bin/pylon-server" ]
+ ENTRYPOINT [ "bun", "run", "/usr/src/pylon/.pylon/index.js" ]
```

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

### Providing the Prisma Client

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/integrating-prisma

A singleton pattern for the Prisma client to ensure type safety and prevent multiple instances in development.

```typescript
import {PrismaClient} from '@prisma/client'
 
declare global {
  var prisma: PrismaClient | undefined
}
 
export const db = globalThis.prisma || new PrismaClient()
 
if (process.env.NODE_ENV !== 'production') globalThis.prisma = db
```

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

### Mocking dependencies with handler

Source: https://pylon.cronit.io/docs/guides/testing

Import the source index file directly to mock dependencies and manually configure the handler for GraphQL requests.

```typescript
import {handler} from '@getcronit/pylon'
 
import app, {graphql} from './src/index'
 
app.use(handler({graphql}))
 
... your tests here ...
```

```typescript
import {handler} from '@getcronit/pylon'
 
import app, {graphql, config} from './src/index'
 
app.use(handler({graphql, config}))
 
... your tests here ...
```

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

### Create a Branch

Source: https://pylon.cronit.io/docs/contributing/how-to-contribute

Create a new branch for your specific feature or fix.

```bash
git checkout -b feature-name
```

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

### Generate extended Prisma models

Source: https://pylon.cronit.io/docs/integrations/databases

Run the generator command to create extended models in the src/models directory.

```bash
bunx prisma-extended-models generate
```

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

### Expose Math Class

Source: https://pylon.cronit.io/docs/getting-started

Demonstrates exposing standard library classes directly through a mutation.

```typescript
import {app} from '@getcronit/pylon'
 
export const graphql = {
  Mutation: {
    math: Math
  }
}
 
export default app
```

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

### Define a Pylon service with Prisma

Source: https://pylon.cronit.io/docs/integrations/databases

Demonstrates how to integrate PrismaClient into a Pylon service for GraphQL queries and mutations. Note that relations are not resolved automatically without additional extensions.

```typescript
import {app} from '@getcronit/pylon'
import {PrismaClient} from '@prisma/client'
 
const prisma = new PrismaClient()
 
export const graphql = {
  Query: {
    // Example query using Prisma
    getUser: async (id: number) => {
      return await prisma.user.findUnique({
        where: {id}
      })
    }
  },
  Mutation: {
    // Example mutation using Prisma
    createUser: async (data: any) => {
      return await prisma.user.create({
        data
      })
    }
  }
}
 
export default app
```

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

### Update GQty client generation

Source: https://pylon.cronit.io/docs/release-notes/migrating-from-v1-to-v2

Update the dev script to include client generation flags.

```json
{
-  "pylon": {
-    "gqty": "./frontend/src/gqty/index.ts"
-  },
   "scripts": {
-    "dev": "pylon dev -c 'bun run .pylon/index.js'",
+    "dev": "pylon dev -c 'bun run .pylon/index.js' --client --client-path ./frontend/src/gqty/index.ts --client-port 3000",
   }
}
```

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

### Define Project Structure

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/external-api

Standard directory layout for a Pylon project containing the data store and service entry point.

```text
my-pylon/
├── .pylon/
├── src/
│   ├── bookingStore.ts
│   ├── index.ts
├── package.json
├── tsconfig.json
```

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

### Expose GraphQL Service

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/external-api

Integration of the booking store methods into the Pylon GraphQL service definition.

```typescript
import {app} from '@getcronit/pylon'
import bookingStore from './lib/bookingStore'
 
export const graphql = {
  Query: {
    bookings: bookingStore.getBookings,
    booking: bookingStore.getBookingById
  },
  Mutation: {
    addBooking: bookingStore.addBooking
  }
}
 
export default app
```

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

### Define Classes

Source: https://pylon.cronit.io/docs/core-concepts/type-safety-and-type-integration

Create object instances with properties and methods using classes.

```typescript
class Product {
  constructor(
    public id: number,
    public name: string,
    public price: number
  ) {}
}
```

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

### Implement BookingStore Class

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/external-api

In-memory data store implementation for managing booking entities with CRUD-like operations.

```typescript
interface Booking {
  id: number
  firstname: string
  lastname: string
  totalPrice?: number
  depositpaid: boolean
  bookingdates: {
    checkin: string
    checkout: string
  }
  additionalneeds?: string
}
 
class BookingStore {
  private bookings: Booking[] = [
    {
      id: 1,
      firstname: 'Sally',
      lastname: 'Brown',
      totalPrice: 111,
      depositpaid: true,
      bookingdates: {
        checkin: '2013-02-23',
        checkout: '2014-10-23'
      },
      additionalneeds: 'Breakfast'
    },
    {
      id: 2,
      firstname: 'John',
      lastname: 'Doe',
      totalPrice: 222,
      depositpaid: false,
      bookingdates: {
        checkin: '2013-02-23',
        checkout: '2014-10-23'
      },
      additionalneeds: 'Breakfast'
    },
    {
      id: 3,
      firstname: 'Jane',
      lastname: 'Smith',
      totalPrice: 333,
      depositpaid: true,
      bookingdates: {
        checkin: '2013-02-23',
        checkout: '2014-10-23'
      },
      additionalneeds: 'Breakfast'
    }
  ]
 
  constructor() {
    this.getBookings = this.getBookings.bind(this)
    this.getBookingById = this.getBookingById.bind(this)
    this.addBooking = this.addBooking.bind(this)
  }
 
  getBookings(): Booking[] {
    return this.bookings
  }
 
  getBookingById(bookingId: number): Booking | null {
    return this.bookings.find(booking => booking.id === bookingId) ?? null
  }
 
  addBooking(booking: Omit<Booking, 'id'>): Booking {
    const newBooking = {...booking, id: this.bookings.length + 1}
    this.bookings.push(newBooking)
    return newBooking
  }
}
 
const bookingStore = new BookingStore()
 
export default bookingStore
```

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

### Test GraphQL API with Bun

Source: https://pylon.cronit.io/docs/guides/testing

Use the Bun test framework to verify GraphQL query and mutation responses. Ensure `bun run build` is executed before running tests.

```typescript
import {describe, expect, test} from 'bun:test'
// Make sure to run `bun run build` before running the tests
import app from './.pylon/index'
 
describe('GraphQL API', () => {
  test('Query.posts', async () => {
    const res = await app.request('/graphql', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        query: 'query { posts { id title content } }'
      })
    })
    expect(res.status).toBe(200)
    const data = await res.json<any>()
    expect(data).toEqual({
      data: {
        posts: [
          {
            id: 1,
            title: 'Hello, world!',
            content: 'This is the first post'
          },
          {
            id: 2,
            title: 'Hello, Pylon!',
            content: 'This is the second post'
          }
        ]
      }
    })
  })
 
  test('Mutation.createPost', async () => {
    const res = await app.request('/graphql', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        query: `
          mutation {
            createPost(title: "New Post", content: "This is a new post") {
              id
              title
              content
            }
          }
        `
      })
    })
    expect(res.status).toBe(200)
    const data = await res.json<any>()
    expect(data).toEqual({
      data: {
        createPost: {
          id: 3,
          title: 'New Post',
          content: 'This is a new post'
        }
      }
    })
  })
})
```

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

### Define a Pylon service with TypeScript types

Source: https://pylon.cronit.io/docs/core-concepts/type-safety-and-type-integration

Demonstrates defining various TypeScript structures like interfaces, enums, and classes, and exposing them through Pylon's Query and Mutation objects.

```typescript
import {app} from '@getcronit/pylon'
 
// Define a type
type Address = {
  street: string
  city: string
  zipCode: string
}
 
// Define an interface
interface User {
  id: number
  name: string
  age: number
  address: Address
}
 
// Define an enum
enum Status {
  ACTIVE = 'ACTIVE',
  INACTIVE = 'INACTIVE'
}
 
// Define a class
class Product {
  constructor(public id: number, public name: string, public price: number) {}
}
 
export const graphql = {
  Query: {
    getUser: (id: number): User => {
      return {
        id,
        name: 'John Doe',
        age: 25,
        address: {street: '123 Main St', city: 'Anytown', zipCode: '12345'}
      }
    },
    getProduct: (id: number): Product => {
      return new Product(id, 'Example Product', 99.99)
    },
    getStatus: (): Status => {
      return Status.ACTIVE
    }
  },
  Mutation: {
    updateUser: (user: User): User => {
      return {...user, name: 'Updated Name'}
    },
    updateProduct: (product: Product): Product => {
      product.price = 79.99
      return product
    }
  }
}
 
export default app
```

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

### Push Changes

Source: https://pylon.cronit.io/docs/contributing/how-to-contribute

Push your local branch to your forked repository.

```bash
git push origin feature-name
```

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

### Define the BookingStore class

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/hardcoded-data

Initializes the class with a private array of hardcoded booking objects.

```typescript
class BookingStore {
  private bookings: Booking[] = [
    {
      id: 1,
      firstname: 'Sally',
      lastname: 'Brown',
      totalPrice: 111,
      depositpaid: true,
      bookingdates: {
        checkin: '2013-02-23',
        checkout: '2014-10-23'
      },
      additionalneeds: 'Breakfast'
    },
    {
      id: 2,
      firstname: 'John',
      lastname: 'Doe',
      totalPrice: 222,
      depositpaid: false,
      bookingdates: {
        checkin: '2013-02-23',
        checkout: '2014-10-23'
      },
      additionalneeds: 'Breakfast'
    },
    {
      id: 3,
      firstname: 'Jane',
      lastname: 'Smith',
      totalPrice: 333,
      depositpaid: true,
      bookingdates: {
        checkin: '2013-02-23',
        checkout: '2014-10-23'
      },
      additionalneeds: 'Breakfast'
    }
  ]
}
```

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

### Exporting a Singleton Instance

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/hardcoded-data

Create and export a singleton instance of the BookingStore class to ensure consistent state across requests.

```typescript
const bookingStore = new BookingStore()
 
export default bookingStore
```

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

### Pylon project directory structure

Source: https://pylon.cronit.io/docs/getting-started

Standard layout for a Pylon project, including source code and build directories.

```text
my-pylon/
├── .pylon/
├── src/
│   ├── index.ts
├── package.json
├── tsconfig.json
```

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

### Configure Dockerfile for Pylon

Source: https://pylon.cronit.io/docs/guides/convert-from-hono-guide

Use these Dockerfiles to containerize your Pylon application for production environments.

```dockerfile
# use the official Bun image
# see all versions at https://hub.docker.com/r/oven/bun/tags
FROM oven/bun:1 as base
 
LABEL description="Offical docker image for Pylon services (Bun)"
LABEL org.opencontainers.image.source="https://github.com/getcronit/pylon"
LABEL maintainer="office@cronit.io"
 
WORKDIR /usr/src/pylon
 
# install dependencies into temp directory
# this will cache them and speed up future builds
FROM base AS install
RUN mkdir -p /temp/dev
COPY package.json bun.lockb /temp/dev/
RUN cd /temp/dev && bun install --frozen-lockfile
 
# install with --production (exclude devDependencies)
RUN mkdir -p /temp/prod
COPY package.json bun.lockb /temp/prod/
RUN cd /temp/prod && bun install --frozen-lockfile --production
 
# copy node_modules from temp directory
# then copy all (non-ignored) project files into the image
FROM install AS prerelease
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
 
# [optional] tests & build
ENV NODE_ENV=production
 
# Create .pylon folder (mkdir)
RUN mkdir -p .pylon
# RUN bun test
RUN bun run pylon build
 
# copy production dependencies and source code into final image
FROM base AS release
COPY --from=install /temp/prod/node_modules node_modules
COPY --from=prerelease /usr/src/pylon/.pylon .pylon
COPY --from=prerelease /usr/src/pylon/package.json .
 
# run the app
USER bun
EXPOSE 3000/tcp
ENTRYPOINT [ "bun", "run", "/usr/src/pylon/.pylon/index.js" ]
```

```dockerfile
# Use the official Node.js 20 image as the base
FROM node:20-alpine as base
 
LABEL description="Offical docker image for Pylon services (Node.js)"
LABEL org.opencontainers.image.source="https://github.com/getcronit/pylon"
LABEL maintainer="office@cronit.io"
 
WORKDIR /usr/src/pylon
 
# install dependencies into a temp directory
# this will cache them and speed up future builds
FROM base AS install
RUN mkdir -p /temp/dev
COPY package.json package-lock.json /temp/dev/
RUN cd /temp/dev && npm ci
 
# install with --production (exclude devDependencies)
RUN mkdir -p /temp/prod
COPY package.json package-lock.json /temp/prod/
RUN cd /temp/prod && npm ci --only=production
 
# copy node_modules from temp directory
# then copy all (non-ignored) project files into the image
FROM install AS prerelease
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
 
# [optional] tests & build
ENV NODE_ENV=production
 
# Create .pylon folder (mkdir)
RUN mkdir -p .pylon
# RUN npm test
RUN npm run pylon build
 
# copy production dependencies and source code into final image
FROM base AS release
COPY --from=install /temp/prod/node_modules node_modules
COPY --from=prerelease /usr/src/pylon/.pylon .pylon
COPY --from=prerelease /usr/src/pylon/package.json .
 
# run the app
USER node
EXPOSE 3000/tcp
ENTRYPOINT [ "node", "/usr/src/pylon/.pylon/index.js" ]
```

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

### View generated models structure

Source: https://pylon.cronit.io/docs/integrations/databases

The directory structure for generated models and the Prisma client instance.

```text
my-pylon-project/
├── src/
│   ├── repository/
│   │   ├── models/
│   │   │   ├── Post.ts
│   │   │   ├── Author.ts
│   │   │   └── User.ts
│   │   ├── .generated.ts
│   │   └── client.ts
```

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

### Create a custom decorator

Source: https://pylon.cronit.io/docs/core-concepts/decorators

Use createDecorator from @getcronit/pylon to define logic that executes when a service function is called.

```typescript
import {app, createDecorator} from '@getcronit/pylon'
 
const log = createDecorator(async () => {
  console.log('Executing service function')
})
 
class Foo {
  @log
  foo = async () => {
    return 'foo'
  }
}
 
export default app
```

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

### Create pylon.d.ts

Source: https://pylon.cronit.io/docs/guides/convert-from-hono-guide

Declaration file for Pylon type definitions.

```typescript
import '@getcronit/pylon'
 
declare module '@getcronit/pylon' {
  interface Bindings {}
 
  interface Variables {}
}
```

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

### Integrate MongoDB with Pylon

Source: https://pylon.cronit.io/docs/integrations/databases

Connect to a MongoDB instance and define GraphQL resolvers for queries and mutations. Ensure proper type definitions are used to avoid security vulnerabilities associated with the 'any' type.

```typescript
import {app} from '@getcronit/pylon'
import {MongoClient} from 'mongodb'
 
const uri = 'mongodb://localhost:27017'
const client = new MongoClient(uri)
 
// Define MongoDB collections
let usersCollection: any
 
;(async () => {
  await client.connect()
  const database = client.db('myDatabase')
  usersCollection = database.collection('users')
})()
 
export const graphql = {
  Query: {
    // Example query using MongoDB
    getUser: async (id: string) => {
      return await usersCollection.findOne({_id: id})
    }
  },
  Mutation: {
    // Example mutation using MongoDB
    createUser: async (user: any) => {
      await usersCollection.insertOne(user)
      return user
    }
  }
}
 
export default app
```

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

### Import Envelop Plugin

Source: https://pylon.cronit.io/docs/core-concepts/plugins

Importing a specific Envelop plugin from the @envelop/core package.

```typescript
import {useErrorHandler} from '@envelop/core'
```

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

### Implement REST POST /posts Endpoint

Source: https://pylon.cronit.io/docs/guides/testing

Add a POST route to handle form data and create new posts.

```typescript
import {app} from '@getcronit/pylon'
 
const posts: {id: number; title: string; content: string}[] = [
  {
    id: 1,
    title: 'Hello, world!',
    content: 'This is the first post'
  },
  {
    id: 2,
    title: 'Hello, Pylon!',
    content: 'This is the second post'
  }
]
 
export const graphql = {
  // ... (previous code remains unchanged)
}
 
app.get('/posts', c => {
  return c.json(posts)
})
 
app.post('/posts', async c => {
  let body: FormData
  try {
    body = await c.req.formData()
  } catch (e) {
    return new Response('Invalid form data', {
      status: 400
    })
  }
 
  const title = body.get('title')?.toString()
  const content = body.get('content')?.toString()
 
  if (!title || !content) {
    return new Response('Title and content are required', {
      status: 400
    })
  }
 
  const post = {
    id: posts.length + 1,
    title,
    content
  }
 
  posts.push(post)
 
  return c.json(post, 201, {
    'X-Custom': 'Thanks for creating!'
  })
})
 
export default app
```

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

### Implement a booking creation mutation

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/integrating-prisma

A function to create a new booking record, including nested booking dates, with error handling.

```typescript
export async function addBooking(
  firstname: string,
  lastname: string,
  totalprice: number,
  depositpaid: boolean,
  checkin: string,
  checkout: string,
  additionalNeeds?: string
): Promise<Booking | null> {
  try {
    const res = await db.booking.create({
      data: {
        firstname,
        lastname,
        totalprice,
        depositpaid,
        additionalneeds: additionalNeeds,
        bookingdates: {
          create: {
            checkin: checkin,
            checkout: checkout
          }
        }
      }
    })
    return res
  } catch (e) {
    return null
  }
}
```

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

### Configure Pylon Plugins

Source: https://pylon.cronit.io/docs/core-concepts/plugins

Adding an Envelop plugin to the plugins array within the Pylon configuration object.

```typescript
export const config: PylonConfig = {
  plugins: [
    useErrorHandler(({errors, context, phase}) => {
      console.error(errors)
    })
  ]
}
```

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

### Define Data Models

Source: https://pylon.cronit.io/docs/guides/convert-from-hono-guide

Define your TypeScript types for User and Blog entities.

```typescript
type User = {
  id: string
  name: string
  email: string
  age: number
  posts: string[]
  blogs: () => Promise<Blog[]>
}
 
type Blog = {
  id: string
  title: string
  content: string
  authorId: string
}
```

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

### Mount Sub-Router to Pylon App

Source: https://pylon.cronit.io/docs/core-concepts/context-management

Register the sub-router using app.route to integrate it into the main application.

```typescript
import {app} from '@getcronit/pylon'
import authRouter from './authRouter'
 
app.route('/auth', authRouter)
 
export const graphql = {...}
 
export default app
```

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

### Implement GraphQL Query for Posts

Source: https://pylon.cronit.io/docs/guides/testing

Updates the application to include a GraphQL query for fetching posts.

```typescript
import {app} from '@getcronit/pylon'
 
const posts: {id: number; title: string; content: string}[] = [
  {
    id: 1,
    title: 'Hello, world!',
    content: 'This is the first post'
  },
  {
    id: 2,
    title: 'Hello, Pylon!',
    content: 'This is the second post'
  }
]
 
export const graphql = {
  Query: {
    posts
  }
}
 
export default app
```

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

### Set Environment Variable in .env

Source: https://pylon.cronit.io/docs/guides/bindings-and-variables

Define the secret value in your environment configuration file.

```text
SECRET=your-secret
```

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

### Define HonoJS Service

Source: https://pylon.cronit.io/docs/guides/convert-from-hono-guide

A sample HonoJS application with REST endpoints for users and blogs.

```typescript
import { Hono } from 'hono'
const app = new Hono()
 
const getUserById = async (id: string) => ({
  id,
  name: 'John Doe',
  email: `john.doe${id}@example.com`,
  age: 30,
  posts: ['1', '2']
})
const getBlogById = async (id: string) => ({
  id,
  title: 'Hello World',
  content: 'This is a blog post',
  authorId: '1'
})
const createBlog = async (id: string, title: string, content: string, authorId: string) => ({
  id,
  title,
  content,
  authorId
})
 
app.get('/users', async(c) => {
  const id = c.req.query('id')
  if (!id) {
    c.status(400)
    return c.json({})
  }
  const user = await getUserById(id)
  return c.json(user)
})
 
app.get('/blog', async(c) => {
  const id = c.req.query('id')
  if (!id) {
    c.status(400)
    return c.json({})
  }
  const blog = await getBlogById(id)
  return c.json(blog)
})
 
app.post('/blogs', async(c) => {
  const {title, content, authorId} = await c.req.json()
  if (!title || !content || !authorId) {
    c.status(400)
    return c.json({})
  }
  const blog = await createBlog('1', title, content, authorId)
  c.status(201)
  return c.json(blog)
})
 
app.post('/post', (c) => {
  return c.json({message: 'a route that you want to keep'})
})
 
export default app
```

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

### Include pylon.d.ts in tsconfig.json

Source: https://pylon.cronit.io/docs/guides/bindings-and-variables

Ensure the declaration file is included in your TypeScript configuration.

```json
{
  "include": ["pylon.d.ts", "src/**/*.ts"]
}
```

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

### Expose Booking IDs via GraphQL

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/external-api

Registers the booking service method within the Pylon application's Query object to make it accessible via GraphQL.

```typescript
import {app} from '@getcronit/pylon'
import bookingStore from './lib/bookingStore'
 
export const graphql = {
  Query: {
    bookingIds: bookingStore.getBookingIds
  },
  Mutation: {}
}
 
export default app
```

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

### Update custom routes and middleware

Source: https://pylon.cronit.io/docs/release-notes/migrating-from-v1-to-v2

Define routes and middleware directly on the app instance instead of using configureApp.

```typescript
import {PylonAPI} from '@getcronit/pylon'
 
export const configureApp: PylonAPI['configureApp'] = app => {
  app.get('/hello', (ctx, next) => {
    return new Response('Hello, world!')
  })
}
```

```typescript
import {app} from '@getcronit/pylon'
 
app.get('/hello', (ctx, next) => {
  return new Response('Hello, world!')
})
```

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

### Implement data retrieval methods

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/hardcoded-data

Adds methods to the class to fetch all bookings or a specific booking by ID.

```typescript
getBookings(): Booking[] {
    return this.bookings;
}
 
getBookingById(bookingId: number): Booking | null {
    return this.bookings.find((booking) => booking.id === bookingId) ?? null;
}
```

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

### Implement GraphQL Mutation

Source: https://pylon.cronit.io/docs/guides/testing

Updates the application to include a GraphQL mutation for creating posts.

```typescript
import {app} from '@getcronit/pylon'
 
const posts: {id: number; title: string; content: string}[] = [
  {
    id: 1,
    title: 'Hello, world!',
    content: 'This is the first post'
  },
  {
    id: 2,
    title: 'Hello, Pylon!',
    content: 'This is the second post'
  }
]
 
export const graphql = {
  Query: {
    posts
  },
  Mutation: {
    createPost: (title: string, content: string) => {
      const post = {
        id: posts.length + 1,
        title,
        content
      }
      posts.push(post)
      return post
    }
  }
}
 
export default app
```

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

### Define Custom Hono Routes

Source: https://pylon.cronit.io/docs/core-concepts/context-management

Use the app instance to register custom routes for handling HTTP requests.

```typescript
app.get('/hello', (ctx, next) => {
  return new Response('Hello, world!')
})
```

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

### Execute GraphQL query

Source: https://pylon.cronit.io/docs/core-concepts/automatic-graphql-api-generation

Perform a query operation against the generated API.

```graphql
query {
  sum(a: 5, b: 3)
}
```

```json
{
  "data": {
    "sum": 8
  }
}
```

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

### Fetch Booking IDs with Optional Parameters

Source: https://pylon.cronit.io/docs/guides/building-with-pylon/external-api

Implements a method to query an external booking API by appending optional firstname, lastname, checkin, and checkout parameters to the URL.

```typescript
async getBookingIds(firstname?: string, lastname?: string, checkin?: string, checkout?: string): Promise<{ bookingid: number }[] | null> {
    try {
        const url = new URL('https://restful-booker.herokuapp.com/booking');
        if (firstname) url.searchParams.append('firstname', firstname);
        if (lastname) url.searchParams.append('lastname', lastname);
        if (checkin) url.searchParams.append('checkin', checkin);
        if (checkout) url.searchParams.append('checkout', checkout);
 
        const response = await fetch(url.toString());
        const data = await response.json();
        return data;
    } catch {
        return null;
    }
}
```

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

### Implement polymorphic queries

Source: https://pylon.cronit.io/docs/core-concepts/interfaces-and-unions

Use the base interface in query return types to allow fetching different content types through a single endpoint.

```typescript
export const graphql = {
  Query: {
    getContent: (id: ID): Content => {
      // Implementation to fetch any type of content
    }
  }
}
```

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

### Configure pylon.d.ts for Type Definitions

Source: https://pylon.cronit.io/docs/guides/bindings-and-variables

Define the Bindings and Variables interfaces to provide type safety for your project.

```typescript
// pylon.d.ts
import '@getcronit/pylon'
 
declare module '@getcronit/pylon' {
  interface Bindings {}
 
  interface Variables {}
}
```

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

### Apply Basic Auth Decorator as Middleware

Source: https://pylon.cronit.io/docs/core-concepts/decorators

Creates a custom decorator using basicAuth and applies it to a specific route handler.

```typescript
import {app, createDecorator, getContext} from '@getcronit/pylon'
import {basicAuth} from 'hono/basic-auth'
 
const requireBasicAuth = createDecorator(async () => {
  const ctx = getContext()
 
  await basicAuth({
    username: 'admin',
    password: 'password'
  })(ctx, async () => {})
})
 
export const graphql = {
  Query: {
    hello: 'Hello World!'
  }
}
 
app.get(
  '/',
  requireBasicAuth(async (c, next) => {
    return new Response('Hello World')
  })
)
```

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

### Replace Hono with Pylon

Source: https://pylon.cronit.io/docs/guides/convert-from-hono-guide

Update your index.ts file to use the Pylon app instance instead of Hono.

```typescript
import { Hono } from 'hono'
const app = new Hono()
```

```typescript
import {app} from '@getcronit/pylon'
```
Tokens:
Raw