chadstart 1.0.0

package/docs/deploy.md

@@ -0,0 +1,113 @@
+---
+id: deploy
+title: Deploy to Production
+description: Deploy your ChadStart backend to production in no time. Server, Databases and Storage options. Deploy on popular cloud providers and use Docker image.
+---
+
+# Deploy ChadStart
+
+## Introduction
+
+ChadStart is made to be **self-hosted**: backends can be deployed with ease wherever you want using different methods.
+
+We recommend using [Docker](#docker) to simplify deployments but you also can install ChadStart manually on a VM or on a bare-metal server.
+
+## System requirements
+
+The minimum system requirements to run a small ChadStart backend are **1vCPU** and **512 MB RAM**. It usually corresponds to one of the cheapest options on cloud providers.
+
+The server needs at least [Node.js v18 or more](https://nodejs.org/fr) and a process manager like [pm2](https://github.com/Unitech/pm2/).
+
+### Database
+
+ChadStart works by default in local with SQLite but we recommend to [switch to PostgreSQL](./config.md#database) for production deployments.
+
+All popular hosting providers have their managed PostgreSQL solutions and there are many DB-as-a-Service providers like [Neon](https://neon.tech/) that offer generous free-tier to get started. Here is a list of popular services:
+
+| Provider            | Service Name                                                                                          |
+| ------------------- | ----------------------------------------------------------------------------------------------------- |
+| **Amazon**          | [Amazon Aurora PostgreSQL](https://aws.amazon.com/rds/aurora/features/)                               |
+| **Google Cloud**    | [Cloud SQL for PostgreSQL](https://cloud.google.com/sql/docs/postgres)                                |
+| **Microsoft Azure** | [Azure Database for PostgreSQL](https://azure.microsoft.com/en-us/products/postgresql/)               |
+| **Neon**            | [Neon Database](https://neon.tech/)                                                                   |
+| **Crunchy Data**    | [Crunchy Bridge](https://www.crunchydata.com/products/crunchy-bridge)                                 |
+| **Aiven**           | [Aiven for PostgreSQL](https://aiven.io/postgresql)                                                   |
+| **DigitalOcean**    | [DigitalOcean Managed PostgreSQL](https://www.digitalocean.com/products/managed-databases-postgresql) |
+| **Heroku**          | [Heroku Postgres](https://heroku.com/postgres)                                                        |
+| **StackGres**       | [StackGres](https://stackgres.io/)                                                                    |
+| **Render.com**      | [Render PostgreSQL Database](https://render.com/docs/postgresql-creating-connecting)                  |
+
+!!! tip
+    While you could technically create a [Docker volume](https://docs.docker.com/engine/storage/volumes/) to ensure data persistence for your SQLite database, we found it easier to use any managed PostgreSQL service **even if you never used PostgreSQL**.
+
+### Storage
+
+ChadStart supports local storage and S3 storage.
+
+With **local storage**, files are saved on disk but will be lost when the container restarts if you are using [Docker](https://www.docker.com/).
+
+With **S3 storage**, files are stored externally, ensuring they are persistent and accessible.
+
+Follow the [S3 Storage documentation](./s3-storage.md) to set it up.
+
+### Environment variables
+
+You need to create a `.env` file at app root level with at least the following variables:
+
+```env title=".env"
+TOKEN_SECRET_KEY=%ReplaceByYourKey%
+NODE_ENV=production
+BASE_URL=https://my-backend.com
+```
+
+See more [environment variables](./config.md#general-variables) you may need.
+
+### Start script for production
+
+The `npm run start` script should only be used for **development** as it watches file changes.
+
+Go back to your codebase and open the `package.json` file and add a new **start:prod** script on the scripts list with the value `node node_modules/chadstart/dist/main.js` as following:
+
+```json title="package.json"
+"scripts": {
+    "start:prod": "node node_modules/chadstart/dist/main.js"
+    [...]
+}
+```
+
+After that you will be able to run ChadStart for production with `npm run start:prod` without watching file changes.
+
+## Docker
+
+[Docker](https://www.docker.com/) is a popular choice among developers. It uses containerization to ensure that the app will work well in any environment.
+
+```dockerfile title="Dockerfile"
+# Use the official Node.js image as a base
+FROM node:22-slim
+
+# Copy package.json and package-lock.json (if available)
+COPY package*.json ./
+
+# Install dependencies
+RUN npm install && npm cache clean --force && rm -rf /root/.npm && rm -rf /tmp/*
+
+# Copy the rest of your application code
+COPY . .
+
+# Set the NODE_ENV environment variable
+ENV NODE_ENV=production
+
+# Expose the port the app runs on (adjust as needed)
+EXPOSE 3000
+
+# Start the application
+CMD ["npm", "run", "start:prod"]
+```
+
+## Guides for popular app platform services
+
+Here are some quick guides to launch your app in a few minutes:
+
+- [Deploy ChadStart on DigitalOcean App Platform](https://chadstart.com/integrations/digital-ocean)
+- [Deploy ChadStart on Render.com](https://chadstart.com/integrations/render)
+- [Deploy ChadStart on Heroku](https://chadstart.com/integrations/heroku)

package/docs/docker.md

@@ -0,0 +1,59 @@
+# Docker
+
+ChadStart is available as a Docker image at `ghcr.io/saulmmendoza/chadstart.com`.
+
+## Run with `docker run`
+
+```bash
+docker run -p 3000:3000 \
+  -e JWT_SECRET=your-secret \
+  -v ./chadstart.yaml:/app/chadstart.yaml:ro \
+  -v ./chadstart.db:/app/chadstart.db \
+  ghcr.io/saulmmendoza/chadstart.com:latest
+```
+
+## Run with `docker compose`
+
+1. Create a `.env` file with your secrets:
+
+```bash
+echo "JWT_SECRET=$(openssl rand -hex 32)" > .env
+```
+
+2. Create a `docker-compose.yml` (or use the provided one):
+
+```yaml
+services:
+  chadstart:
+    image: ghcr.io/saulmmendoza/chadstart.com:latest
+    ports:
+      - "3000:3000"
+    environment:
+      JWT_SECRET: ${JWT_SECRET}
+    volumes:
+      - ./chadstart.yaml:/app/chadstart.yaml:ro
+      - ./chadstart.db:/app/chadstart.db
+```
+
+3. Start the service:
+
+```bash
+docker compose up
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JWT_SECRET` | dev-only default | JWT signing secret — **required in production** |
+| `JWT_EXPIRES` | `7d` | Token expiry duration |
+| `PORT` | `3000` | Server port |
+| `NODE_ENV` | `development` | Set to `production` in production |
+
+## Persistent Storage
+
+Mount a volume for the SQLite database to persist data across container restarts:
+
+```bash
+-v ./chadstart.db:/app/chadstart.db
+```

package/docs/entities.md

@@ -0,0 +1,385 @@
+---
+id: entities
+title: Entities
+descriptions: Entities are the foundation of ChadStart. Define your data structure in few lines and use 15+ real-world types for your properties.
+---
+
+# Entities
+
+## Introduction
+
+An entity is a model of objects linked to real-world concepts. Creating an entity in chadstart generates **CRUD endpoints** that can be used by the [REST API](./crud.md#using-the-rest-api) or the [SDK](./crud.md#using-the-javascript-sdk).
+
+All entities are located in the `chadstart.yaml` file under the **entities** property.
+
+There are 2 types of entities in ChadStart: [Collections](#collections) and [Singles](#singles). **Collections** are multiple instances of similar data, stored as a list. E.g., users, customers, videos, etc. Singles are unique, standalone data that are singular in nature. E.g., home content, about content, settings, logo...
+
+## Collections
+
+Let's see a simple example:
+
+```yaml title="chadstart.yaml"
+name: A pet app
+
+entities:
+  Cat 😺:
+    properties:
+      - name
+  Dog 🐶:
+    properties:
+      - name
+```
+
+This file will generate the **Cat** and **Dog** entity both with a `name` property. In ChadStart by default all entities have an **id** (UUID format) so you do not need to add it. They also have automatic **createdAt** and **updatedAt** columns that are not selected by default in the API requests.
+
+You can now add your own pets through the admin panel!
+
+To generate dummy data for all your entities, run the simple command:
+
+```
+npm run seed
+```
+
+!!! warning
+    The seed replaces the previous data by the new one and thus should never be used in production.
+
+### Entity params
+
+You can pass different arguments to configure your entities. Example:
+
+```yaml
+entities:
+  Member 👤:
+    seedCount: 200
+    mainProp: lastName
+    properties:
+      - firstName
+      - lastName
+      - email
+```
+
+| Option            | Default                    | Type     | Description                                                                                              |
+| ----------------- | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| **authenticable** | false                      | Boolean  | Whether the entity is [authenticable](auth.md#authenticable-entities) or not                             |
+| **mainProp**      | _first string field_       | String   | Identifier prop. Used widely on the admin panel                                                          |
+| **nameSingular**  | _singular lower case name_ | String   | The singular lowercase name of your entity. Used widely on the admin panel.                              |
+| **namePlural**    | _plural lowercase name_    | String   | The plural lowercase name of your entity. Used widely on the admin panel. |
+| **policies**      | -                          | Policies | The [access control policies](./access-policies.md) of your entity                                       |
+| **properties**    | `[]`                       | Array    | The [properties](./entities.md#properties) of your entity                                                |
+| **seedCount**     | `50`                       | Number   | The number of entities to seed when running the seed command.                                            |
+| **slug**          | _plural kebab-case name_   | String   | The kebab-case slug of the entity that will define API endpoints.                                        |
+
+## Singles
+
+Single entities differ a bit from [collections](#collections). A single entity is **singular in nature**, and there can be only one record of them. Examples are website dynamic elements, pages, standalone content or settings. They do not have [relations](./entities.md#relations).
+
+On single entities **Create** and **Delete** CRUD actions are disabled. Thus, the [REST API endpoints for single entities](./crud.md#singles) are different.
+
+```yaml
+ContactPage:
+  single: true
+  slug: contact
+  properties:
+    - { name: title, type: string }
+    - { name: content, type: text }
+    - { name: image, type: image }
+  validation:
+    title: { required: true }
+```
+
+You can generate dummy data for all your entities with the simple command:
+
+```
+npm run seed
+```
+
+### Entity params
+
+You can pass different arguments to configure your single entities. Example:
+
+```yaml
+entities:
+  Member 👤:
+    seedCount: 200
+    mainProp: lastName
+    properties:
+      - firstName
+      - lastName
+      - email
+```
+
+| Option           | Default                    | Type     | Description                                                                 |
+| ---------------- | -------------------------- | -------- | --------------------------------------------------------------------------- |
+| **nameSingular** | _singular lower case name_ | string   | The singular lowercase name of your entity. Used widely on the admin panel. |
+| **policies**     | -                          | Policies | The [access control policies](./access-policies.md) of your entity          |
+| **properties**   | `[]`                       | Array    | The [properties](./entities.md#properties) of your entity                   |
+| **slug**         | _plural dasherized name_   | string   | The kebab-case slug of the entity that will define API endpoints.           |
+
+
+## Properties
+
+Properties are the characteristics of your [entities](./entities.md). For example, a **Product** can have properties like `name`, `description`, `price`...
+
+### Syntax
+
+You can add the properties to your entities in the **chadstart.yaml file**
+
+```yaml title="chadstart.yaml"
+name: Blog about cats
+entities:
+  Post 📝:
+    properties:
+      - name # Short syntax for string type.
+      - { name: content, type: text } # Long syntax for other types.
+      - { name: publishedAt, type: date }
+      - { name: authorEmail, type: email, hidden: true } # Extra options.
+      - {
+          name: status,
+          type: choice,
+          options: { values: [draft, pending, published] },
+          default: draft # Default value if property not specified.
+        }
+```
+
+### Property params
+
+You can pass arguments using the long syntax:
+
+| Option         | Default  | Type       | Description                                                                                               |
+| -------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------- |
+| **type**       | "string" | _PropType_ | The [Property type](#property-types) (text, number, email, location...)                                   |
+| **hidden**     | `false`  | boolean    | If the property should be hidden in the API response                                                      |
+| **options**    | -        | Object     | Specific options depending on [property type](#property-types)                                            |
+| **validation** | -        | Object     | The [property validators](./validation.md) that each request compares against                             |
+| **helpText**   | -        | string     | Optional help text to display in admin UI                                                                 |
+| **default**    | -        | any        | The default value. When creating an item, if the property is not specified it will default to this value. |
+
+### Property types
+
+ChadStart vision of **property types** goes beyond software development typing and is already built-in for real world usages. For example, the [Money](#money) PropType is handier than [Number](#number) for managing amounts as it comes with a `currency` option that only allows 2 digits after the comma.
+
+Each PropType comes with built-in type [validation](./validation.md).
+
+Some of them have specific options. Here is a list of the available types:
+
+#### String
+
+A simple string.
+
+```yaml
+- { name: firstName, type: string }
+
+# Short syntax, same as above.
+- firstName
+```
+
+#### Textarea
+
+Textarea field for medium-size texts.
+
+```yaml
+- { name: description, type: text }
+```
+
+#### Rich text
+
+Rich text field for HTML content. The admin panel input can generate basic HTML tags like bold, italic, headings, links and bullet lists.
+
+```yaml
+- { name: description, type: richText }
+```
+
+#### Number
+
+A numerical value.
+
+```yaml
+- { name: age, type: number }
+```
+
+#### Link
+
+An URL that links to an external page.
+
+```yaml
+- { name: website, type: link }
+```
+
+#### Money
+
+A money field with a currency. Money properties can have up to 2 digits after the comma.
+
+```yaml
+- { name: price, type: money, options: { currency: 'EUR' } }
+```
+
+###### Parameters
+
+| Option       | Default | Type   | Description                                                                                      |
+| ------------ | ------- | ------ | ------------------------------------------------------------------------------------------------ |
+| **currency** | _USD_   | string | [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) |
+
+#### Date
+
+Basic date field.
+
+```yaml
+- { name: startDate, type: date }
+```
+
+#### Timestamp
+
+Timestamp field (ISO 8601 Format)
+
+```yaml
+- { name: acquiredAt, type: timestamp }
+```
+
+#### Email
+
+You can create one-to-many relationships or many-to-many relationships. Defining relationships in your entities allows you to load relations when you query them and also filter by relations.
+
+```yaml
+- { name: email, type: email }
+```
+
+#### Boolean
+
+For any field with a "true or false" value.
+
+```yaml
+- { name: isActive, type: boolean }
+```
+
+#### File
+
+A file upload. Read more in the [file upload doc](./upload.md#upload-a-file).
+
+```yaml
+- { name: document, type: file }
+```
+
+!!! note
+    ChadStart stores the **absolute paths** of uploaded files. Use the [`BASE_URL`](./upload.md#add-a-base_url-variable) environment variable to adapt it to your domain.
+
+#### Image
+
+An image upload. The different sizes should be provided to generate several sizes of it. Read more in the [image upload doc](./upload.md#upload-an-image).
+
+```yaml
+- {
+    name: photo,
+    type: image,
+    options:
+      { sizes: { small: { height: 90, width: 90 }, large: { width: 200 } } }
+  }
+```
+
+!!! note
+    ChadStart stores the **absolute paths** of uploaded images. Use the [`BASE_URL`](./upload.md#add-a-base_url-variable) environment variable to adapt it to your domain.
+
+###### Parameters
+
+| Option    | Default                                | Type             | Description                                                                                                                                                                                |
+| --------- | -------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **sizes** | _thumbnail (80x80)_ _medium (160x160)_ | ImageSizesObject | An object with each key being the name of each size and with `width`, `height` and `fit` optional props. The _fit_ options works as in [Sharp](https://sharp.pixelplumbing.com/api-resize) |
+
+#### Password
+
+Password field. Most of the time you do not need to implement passwords manually as [authenticable entities](./auth.md#authenticable-entities) have built-in `email` and `password` fields to log in.
+
+```yaml
+- { name: password, type: password }
+```
+
+!!! warning
+    When setting the type as `password`, ChadStart hashes automatically the value before storing it. Passwords should never be stored as clear text.
+
+#### Choice
+
+A given choice of options.
+
+```yaml
+- { name: sex, type: choice, options: { values: [male, female] } }
+
+# Sequential if the values are ordered in a logical sense..
+- {
+    name: status,
+    type: choice,
+    options: { values: [draft, submitted, published], sequential: true }
+  }
+```
+
+###### Parameters
+
+| Option         | Default   | Type     | Description                                            |
+| -------------- | --------- | -------- | ------------------------------------------------------ |
+| **values**     | _(empty)_ | String[] | An array of strings representing the available choices |
+| **sequential** | `false`   | boolean  | Specifies if the values are ordered in a logical sense |
+
+#### Location
+
+The location type consists in a object with `lat` and `lng` coordinates.
+
+```yaml
+- { name: location, type: location }
+```
+
+## Relations
+
+You can create **one-to-many** relationships or **many-to-many** relationships. Defining relationships in your entities allows you to [load relations](./crud.md#load-relations) when you query them and also [filter your query by relations](./crud.md#filter-by-relation).
+
+### Syntax
+
+The following example showcases the possibilities of **ChadStart relations**:
+
+```yaml title="chadstart.yaml"
+name: Basketball League 🏀
+
+entities:
+  Player 🤾:
+    properties:
+      - name
+    belongsTo:
+      - Team
+    belongsToMany:
+      - Skill
+
+  Team 👥:
+    properties:
+      - name
+
+  Skill 💪:
+    properties:
+      - name
+
+  Fixture 🏟️:
+    properties:
+      - { name: homeScore, type: number }
+      - { name: awayScore, type: number }
+    belongsTo:
+      - { name: homeTeam, entity: Team }
+      - { name: awayTeam, entity: Team }
+```
+
+In other words:
+
+- The **belongsTo** keyword creates a **many-to-one** relationship (and its opposite _one-to-many_)
+- The **belongsToMany** keyword creates a **many-to-many** bi-directional relationship
+- The **long syntax** (as in _Fixture.belongsTo_) is useful when we want to edit the name of the relationships
+
+!!! tip
+    All relationships are **bi-directional**, which means that you just have to specify them **in one side only** to work with them in both directions.
+
+    When you define a **belongsTo** relationship, it implicitly set the opposite _hasMany_ relationship and allow [querying relations](./crud.md#work-with-relations) in both directions.
+
+### Relation params
+
+You can pass arguments using the long syntax:
+
+| Option       | Default     | Type    | Description                                                                                                                      |
+| ------------ | ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| **name**     | Entity name | string  | The name of the relation                                                                                                         |
+| **entity**   | -           | string  | The class name of the entity that the relationship is with                                                                       |
+| **helpText** | -           | string  | Optional help text to display in admin UI                                                                                        |
+| **eager**    | `false`     | boolean | Whether the relationship should be eager loaded. Otherwise, you need to explicitly request the relation in the client SDK or API |