chadstart 1.0.0

package/docs/validation.md

@@ -0,0 +1,115 @@
+---
+id: validation
+title: Validation
+description: Server-side validation for your user-generated content. Use many validators like "required", "minLength", "contains" or "matches" for every property.
+---
+
+# Validation
+
+## Introduction
+
+Implementing **server-side validation** is very easy with ChadStart.
+
+You can use the built-in **custom validators** to ensure that the data you are receiving is correctly formatted.
+
+## Syntax
+
+In your **chadstart.yaml**, you can add a _validation_ object that lists the properties and their validators:
+
+```yaml
+entities:
+  Dog:
+    properties:
+      - name
+      - { name: age, type: number }
+    validation:
+      name: { minLength: 3 } # The name should have at least 3 characters.
+      age: { min: 1, max: 30 } # Age should be a number between 1 and 30.
+```
+
+!!! tip "Tip"
+    **Type validation** is natively implemented with [property types](./entities.md#property-types). You do not need to set it.
+
+    Ex: sending a _string_ value for a [boolean](./entities.md#boolean) property type will throw an error.
+
+## Inline syntax
+
+If you want to keep it short you can simply pass the **validation** object to the **property object**:
+
+```yaml
+entities:
+  Author 🧑🏽‍🦱:
+    properties:
+      - name
+      - { name: email, type: email, validation: { isNotEmpty: true } }
+      - { name: bio, type: textarea, validation: { maxLength: 300 } }
+```
+
+Both syntaxes (block and inline) can be used simultaneously. In case of declaration conflict, the **inline** declaration will prevail.
+
+## Validate optional properties
+
+If you have some values that are optional **but** that need to be validated **if present**, you can add the `isOptional` validator. The value will be compared against validators only if not _undefined_ or _null_. Example:
+
+```yaml
+entities:
+  Employee:
+    properties:
+      - name
+      - {
+          name: email,
+          type: email,
+          validation: { contains: '@company.com', isOptional: true }
+        } #  If provided, the email should contain "@company.com"
+```
+
+## Validation response
+
+If the validation fails, the response will list the validation error(s) in its body:
+
+```http
+// Create a new Employee
+POST /api/dynamic/employees
+Content-Type: application/json
+{
+    "name": "John Doe",
+    "email": "john@chadstart.com"
+}
+
+// Response.
+[
+    {
+        "property": "email",
+        "constraints": {
+            "contains": "The value must contain @company.com"
+        }
+    }
+]
+```
+
+## Available validators
+
+| Validator        | Type    | Description                                                                          |
+| ---------------- | ------- | ------------------------------------------------------------------------------------ |
+| `required`       | boolean | Indicates whether the property must not be empty.                                    |
+| `isDefined`      | boolean | Checks if value is defined (!== undefined, !== null).                                |
+| `isOptional`     | boolean | Checks if given value is empty (=== null, === undefined) and ignores all validators. |
+| `equals`         | any     | Checks if value equals ("===") comparison.                                           |
+| `notEquals`      | any     | Checks if value not equal ("!==") comparison.                                        |
+| `isEmpty`        | boolean | Indicates whether the property can be empty.                                         |
+| `isNotEmpty`     | boolean | Indicates whether the property must not be empty. Alias for `required`               |
+| `isIn`           | array   | Checks if value is in an array of allowed values.                                    |
+| `isNotIn`        | array   | Checks if value not in an array of disallowed values.                                |
+| `min`            | number  | The minimum value or length allowed for the property.                                |
+| `max`            | number  | The maximum value or length allowed for the property.                                |
+| `contains`       | string  | Checks if string contains the seed.                                                  |
+| `notContains`    | string  | Checks if string does not contain the seed.                                          |
+| `isAlpha`        | boolean | Checks if the string contains only letters (a-zA-Z).                                 |
+| `isAlphanumeric` | boolean | Checks if the string contains only letters and numbers.                              |
+| `isAscii`        | boolean | Checks if the string contains ASCII chars only.                                      |
+| `isEmail`        | boolean | Checks if the string is an email.                                                    |
+| `isJSON`         | boolean | Checks if the string is valid JSON.                                                  |
+| `minLength`      | number  | Checks if the string's length is not less than given number.                         |
+| `maxLength`      | number  | Checks if the string's length is not more than given number.                         |
+| `matches`        | string  | Checks if string matches the pattern.                                                |
+| `isMimeType`     | boolean | Checks if the string matches to a valid MIME type format.                            |

package/docs/vue.md

@@ -0,0 +1,86 @@
+---
+id: vue
+title: Create a Full-Stack app with Vue and ChadStart
+description: Quick start guide to create a full-stack app using Vue as a frontend and ChadStart as a backend.
+---
+
+# Quick start with Vue
+
+Give a proper backend to your Vue.js app.
+
+!!! warning
+    This quick start guide focuses exclusively on the **frontend**. To ensure the functionality of this code, your ChadStart backend must be [up and running](./getting-started.md#install-chadstart) at `http://localhost:3000`.
+
+## 1. Create a Vue app
+
+If you already have a Vue app running, you can skip this step.
+
+We are using Vue.js v3 in this tutorial. You can replace `my-client` by the name of your front-end app
+
+```
+npm create vue@latest
+cd my-client // If you called your app "my-client" when asked in the previous step
+npm install
+npm run dev
+```
+
+## 2. Install ChadStart SDK
+
+Install the JS SDK from the root of your Vue app.
+
+```
+npm i @chadstart/sdk
+```
+
+## 3. Use it in your app
+
+In that example we are using a Cat entity [created previously](entities.md). Replace it by your own entity. This example uses TypeScript, you can remove the typing to have plain JS.
+
+```js
+<script lang="ts">
+import ChadStart from "@chadstart/sdk";
+
+interface Cat {
+  id: string;
+  name: string;
+  type: string;
+  image: string;
+}
+
+export default {
+  data() {
+    return {
+      cats: [] as Cat[],
+    };
+  },
+  mounted() {
+    this.fetchCat();
+  },
+  methods: {
+    async fetchCat() {
+
+      // Init SDK
+      const chadstart = new ChadStart();
+
+      // Fetch Cats from the backend.
+      chadstart.from("cats")
+        .find<Cat>()
+        .then((res) => {
+          // Store the response in the "cats" array
+          this.cats = res.data;
+        });
+    },
+  },
+};
+</script>
+
+<template>
+    <ul>
+        <li v-for="cat of cats">{{ cat.name }}</li>
+    </ul>
+</template>
+
+
+```
+
+Checkout the [SDK doc](./crud.md#using-the-javascript-sdk) to see more usages of the SDK.,

package/docs/webhooks.md

@@ -0,0 +1,87 @@
+---
+id: webhooks
+title: Webhooks
+description: Send requests to third-party applications using ChadStart webhooks. Choose URL, method and send custom headers.
+---
+
+# Webhooks
+
+## Introduction
+
+**Webhooks** are a way for an app to send automated real-time notifications to another app when a specific [event](./webhooks.md#hook-events) occurs. In ChadStart, there are 6 predefined events where you can hook HTTP requests.
+
+Webhooks are useful to connect other applications or to trigger a micro-service like notifying someone or updating a file.
+
+## Syntax
+
+```yaml title="chadstart.yaml"
+entities:
+  # You can attach one or several webhooks to each entity event.
+  Cat 😺:
+    properties:
+      - name
+    hooks:
+      beforeCreate:
+        - { url: 'https://my-webhook.com' }
+
+  Dog 🐶:
+    properties:
+      - name
+    hooks:
+      afterDelete:
+        # Pass .env variables with ${} interpolation.
+        - {
+            url: 'https://another-webhook.com',
+            headers: { authorization: 'Bearer ${API_KEY}' }
+          }
+        # Specific HTTP method.
+        - { url: 'https://another-one.com', method: 'PATCH' }
+```
+
+## Webhook params
+
+You can pass arguments using the long syntax:
+
+| Option      | Default | Type          | Description                                                                            |
+| ----------- | ------- | ------------- | -------------------------------------------------------------------------------------- |
+| **url\***   | -       | string        | The URL of your webhook                                                                |
+| **method**  | `POST`  | _HTTP Method_ | The HTTP method of the request                                                         |
+| **headers** | `{}`    | object        | Optional headers of the request. Use `${MY_DOTENV_VAR}` syntax to use dotenv variables |
+
+Available HTTP Methods are `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
+
+!!! note
+    ChadStart does not enforce HTTP request success or failure; the lifecycle process continues regardless.
+
+## Webhook body
+
+ChadStart attaches a **JSON body** with key information about the record concerned to the webhook HTTP request.
+
+The main structure of the body of the triggered HTTP requests will remain the same and only the `record` value will change: on _before_ events the `record` will contain your payload, whereas in _after_ requests, the `record` value will reflect the item after the operation.
+
+This is the structure of the body:
+
+```json title="HTTP request body (content-type is application/json)"
+{
+  "event": "beforeUpdate",
+  "createdAt": "2025-01-22T13:38:48.399Z",
+  "entity": "posts",
+  "record": {
+    "title": "my title",
+    "content": "my content"
+  }
+}
+```
+
+## Hook events
+
+This is the list and description of the 6 hook events available. All of them are related to an [entity](./entities.md).
+
+| Name             | Description              |
+| ---------------- | ------------------------ |
+| **beforeCreate** | Before creating a record |
+| **afterCreate**  | After creating a record  |
+| **beforeUpdate** | Before updating a record |
+| **afterUpdate**  | After updating a record  |
+| **beforeDelete** | Before deleting a record |
+| **afterDelete**  | After deleting a record  |

package/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+/**
+ * ChadStart — YAML-first Backend as a Service
+ *
+ * Programmatic API:
+ *   const { createServer, startServer } = require('chadstart');
+ *   await startServer('./chadstart.yaml');
+ */
+
+module.exports = require('./server/express-server');

package/locales/en/admin.json

@@ -0,0 +1,169 @@
+{
+  "page": {
+    "title": "ChadStart Admin"
+  },
+  "login": {
+    "title": "ChadStart Admin",
+    "collection_label": "Collection",
+    "collection_placeholder": "Admin collection name",
+    "change_collection": "Change collection",
+    "hide_collection": "Hide collection",
+    "email_label": "Email",
+    "email_placeholder": "admin@example.com",
+    "password_label": "Password",
+    "password_placeholder": "••••••••",
+    "sign_in": "Sign in",
+    "signing_in": "Signing in…",
+    "errors": {
+      "no_admin_collections": "No admin collections configured",
+      "all_fields_required": "All fields are required",
+      "collection_not_found": "Collection not found",
+      "login_failed": "Login failed",
+      "network_error": "Network error"
+    }
+  },
+  "sidebar": {
+    "subtitle": "Admin",
+    "collections": "Collections",
+    "entities": "Entities",
+    "admin": "Admin",
+    "config_editor": "⚙ Config Editor",
+    "api_keys": "🔑 API Keys",
+    "log_out": "Log out"
+  },
+  "header": {
+    "select_collection": "Select a collection",
+    "new_record": "+ New record"
+  },
+  "modal": {
+    "title_new": "New {{name}}",
+    "title_edit": "Edit {{name}} #{{id}}",
+    "cancel": "Cancel",
+    "save": "Save",
+    "saving": "Saving…"
+  },
+  "table": {
+    "no_records": "No records yet. Click + New record to create one.",
+    "actions": "Actions",
+    "edit": "Edit",
+    "delete": "Delete",
+    "delete_confirm": "Delete record #{{id}}?"
+  },
+  "toast": {
+    "failed_load_data": "Failed to load data",
+    "failed_load_schema": "Failed to load schema",
+    "record_created": "Record created",
+    "record_updated": "Record updated",
+    "record_deleted": "Record deleted",
+    "config_reloading": "Config saved — reloading server…",
+    "config_applied": "Config applied",
+    "config_saved": "Config saved successfully",
+    "config_reset": "Reset to last saved state",
+    "form_read_error": "Could not read form data",
+    "config_not_object": "Config must be a JSON object",
+    "invalid_json": "Invalid JSON: {{message}}",
+    "save_failed": "Save failed: {{message}}",
+    "config_load_failed": "Failed to load config: {{message}}"
+  },
+  "config": {
+    "tabs": {
+      "general": "General",
+      "entities": "Entities",
+      "functions": "Functions",
+      "files": "Files & Uploads",
+      "settings": "Settings",
+      "all": "All"
+    },
+    "descriptions": {
+      "general": "Application name, port, database path, and public static folder.",
+      "entities": "Entity definitions — properties, relations, and flags.",
+      "functions": "Custom function-based HTTP endpoint definitions (path, method, function).",
+      "files": "File bucket definitions for local uploads.",
+      "settings": "API rate limits and reusable property groups.",
+      "all": "Full configuration — all sections combined (raw JSON for advanced use)."
+    },
+    "save_btn": "Save Config",
+    "saving_btn": "Saving…",
+    "reset_btn": "Reset",
+    "editor_title": "Config Editor",
+    "json_label": "Full Configuration JSON",
+    "json_hint": "(read-only reference — switch to the All tab to edit directly)",
+    "json_label_edit": "Full Configuration JSON",
+    "json_hint_edit": "(edit directly — changes are saved on Save)",
+    "status": {
+      "loading": "Loading…",
+      "reloading": "Reloading…",
+      "applied": "✓ Config applied.",
+      "saved_reload": "✓ Saved — reload the page to see changes.",
+      "saved_restart": "✓ Saved — restart the server to apply changes."
+    },
+    "s3_note": {
+      "title": "S3 Storage",
+      "intro": "is configured via environment variables:",
+      "env_hint": "Set these in your",
+      "env_file": ".env",
+      "env_or": "file or deployment environment."
+    },
+    "general": {
+      "app_name": "App Name",
+      "port": "Port",
+      "port_hint": "Default: 3000",
+      "database": "Database path",
+      "database_placeholder": "data/chadstart.db",
+      "database_hint": "Path relative to the config file. Leave blank for the default.",
+      "public_folder": "Public folder",
+      "public_folder_placeholder": "public",
+      "public_folder_hint": "Folder for static files served at the root (HTML, CSS, JS, etc.)."
+    },
+    "entities": {
+      "entity_name": "Entity name",
+      "entity_placeholder": "Post",
+      "user_collection": "User collection",
+      "single": "Single",
+      "remove": "Remove",
+      "belongs_to": "Belongs to",
+      "belongs_to_hint": "(comma-separated)",
+      "belongs_to_placeholder": "User, Category",
+      "belongs_to_many": "Belongs to many",
+      "belongs_to_many_placeholder": "Tag",
+      "properties": "Properties",
+      "add_property": "+ Add property",
+      "add_entity": "+ Add entity",
+      "property_placeholder": "property name"
+    },
+    "functions": {
+      "name": "Name",
+      "name_placeholder": "sendEmail",
+      "path_label": "Path",
+      "path_placeholder": "/send-email",
+      "method": "Method",
+      "function": "Function",
+      "function_placeholder": "sendEmail.js",
+      "description": "Description",
+      "description_hint": "(optional)",
+      "description_placeholder": "What this endpoint does",
+      "remove": "Remove",
+      "add_endpoint": "+ Add endpoint"
+    },
+    "files": {
+      "name": "Name",
+      "name_placeholder": "images",
+      "path_label": "Path",
+      "path_placeholder": "uploads/images",
+      "public": "Public",
+      "remove": "Remove",
+      "add_bucket": "+ Add file bucket"
+    },
+    "settings": {
+      "rate_limits_hint": "Rate limits cap the number of API requests per time window.",
+      "name": "Name",
+      "name_placeholder": "api",
+      "max_requests": "Max requests",
+      "max_requests_placeholder": "200",
+      "window_ms": "Window (ms)",
+      "window_placeholder": "60000",
+      "remove": "Remove",
+      "add_rate_limit": "+ Add rate limit"
+    }
+  }
+}

package/mkdocs.yml

@@ -0,0 +1,82 @@
+site_name: ChadStart
+site_description: YAML-first Backend as a Service — define your entire backend in a single YAML file.
+site_url: https://saulmmendoza.github.io/chadstart.com/
+repo_url: https://github.com/saulmmendoza/chadstart.com
+repo_name: saulmmendoza/chadstart.com
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  custom_dir: docs/overrides
+  palette:
+    - scheme: default
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.copy
+  icon:
+    repo: fontawesome/brands/github
+
+extra_css:
+  - stylesheets/extra.css
+
+nav:
+  - Home: index.md
+  - Get Started: getting-started.md
+  - Core:
+    - Entities: entities.md
+    - CRUD: crud.md
+    - Authentication: auth.md
+    - Access Policies: access-policies.md
+    - Validation: validation.md
+    - Configuration: config.md
+  - Features:
+    - File & Image Uploads: upload.md
+    - S3 Storage: s3-storage.md
+    - Realtime: realtime.md
+    - Webhooks: webhooks.md
+    - Custom Endpoints: functions.md
+    - Middlewares: middlewares.md
+    - Groups: groups.md
+    - Security: security.md
+    - Telemetry: telemetry.md
+    - LLM Rules: llm-rules.md
+  - Admin UI: admin-ui.md
+  - CLI: cli.md
+  - Deploy:
+    - Deploy to Production: deploy.md
+    - Docker: docker.md
+  - Integrations:
+    - React: react.md
+    - Vue: vue.md
+    - Angular: angular.md
+    - Svelte: svelte.md
+    - Astro: astro.md
+  - Plugins: plugins.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - toc:
+      permalink: true

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "chadstart",
+  "version": "1.0.0",
+  "description": "YAML-first Backend as a Service — define your entire backend in one YAML file",
+  "main": "server/express-server.js",
+  "bin": {
+    "chadstart": "./cli/cli.js"
+  },
+  "scripts": {
+    "dev": "node cli/cli.js dev",
+    "start": "node cli/cli.js start",
+    "start:prod": "NODE_ENV=production node cli/cli.js start",
+    "build": "node cli/cli.js build",
+    "seed": "node cli/cli.js seed",
+    "test": "mocha --timeout 10000 'test/*.test.js'",
+    "test:coverage": "c8 --reporter=text --reporter=json-summary mocha --timeout 10000 'test/*.test.js'",
+    "test:browser": "playwright test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saulmmendoza/chadstart.com.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/saulmmendoza/chadstart.com/issues"
+  },
+  "homepage": "https://github.com/saulmmendoza/chadstart.com#readme",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1009.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/sdk-node": "^0.213.0",
+    "@sentry/node": "^10.43.0",
+    "@tailwindcss/browser": "4.2.1",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "animate.css": "4.1.1",
+    "bcryptjs": "^3.0.3",
+    "better-sqlite3": "^12.6.2",
+    "busboy": "^1.6.0",
+    "chokidar": "^5.0.0",
+    "cronstrue": "^3.13.0",
+    "execa": "^9.6.1",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.3.1",
+    "htmx.org": "2.0.4",
+    "jsonwebtoken": "^9.0.3",
+    "node-cron": "^4.2.1",
+    "sharp": "^0.34.5",
+    "swagger-ui-express": "^5.0.1",
+    "ws": "^8.19.0",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "c8": "^11.0.0",
+    "mocha": "^11.7.5"
+  },
+  "overrides": {
+    "serialize-javascript": "^7.0.3"
+  }
+}

package/playwright.config.js

@@ -0,0 +1,24 @@
+// @ts-check
+'use strict';
+
+const { defineConfig, devices } = require('@playwright/test');
+
+module.exports = defineConfig({
+  testDir: './test/browser',
+  timeout: 30000,
+  retries: 0,
+  workers: 1,
+  reporter: 'list',
+  globalSetup:    require.resolve('./test/browser/global-setup.js'),
+  globalTeardown: require.resolve('./test/browser/global-teardown.js'),
+  use: {
+    baseURL: process.env.TEST_BASE_URL || 'http://localhost:4321',
+    headless: true,
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});