@nexa-stack/framework 1.0.0

package/docs/database.md

@@ -0,0 +1,396 @@
+# Database
+
+
+
+## SQLite (default)
+
+
+
+```env
+
+DB_PATH=./app.db
+
+```
+
+
+
+## PostgreSQL
+
+
+
+```env
+
+DATABASE_URL=postgresql://user:pass@localhost:5432/nexa
+
+```
+
+
+
+When `DATABASE_URL` is set, Nexa picks the driver from the URL scheme. Otherwise SQLite via `DB_PATH`.
+
+## MySQL / MariaDB
+
+```env
+DATABASE_URL=mysql://user:pass@localhost:3306/nexa
+```
+
+`mariadb://` URLs work the same way.
+
+| Driver | URL prefix | Default env |
+|--------|------------|-------------|
+| SQLite | file path | `DB_PATH=./app.db` |
+| PostgreSQL | `postgresql://` | `DATABASE_URL` |
+| MySQL / MariaDB | `mysql://` or `mariadb://` | `DATABASE_URL` |
+
+
+
+## Query from code
+
+
+
+```ts
+
+const db = getDb()!;
+
+
+
+// All
+
+await db.findAll("clients");
+
+
+
+// One
+
+await db.findById("clients", 1);
+
+
+
+// Insert
+
+await db.insert("clients", { name: "Ali", phone: "050..." });
+
+
+
+// SQL
+
+await db.query("SELECT * FROM clients WHERE city = ?", ["Damascus"]);
+
+```
+
+
+
+## Relations
+
+
+
+### belongsTo
+
+
+
+```ts
+
+resource("orders", {
+
+  client: belongsTo("clients").required(),
+
+});
+
+```
+
+
+
+API returns nested object: `{ client: { id: 1, name: "Ali" } }`
+
+
+
+### hasMany
+
+
+
+```ts
+
+resource("clients", {
+
+  name: string().required(),
+
+  orders: hasMany("orders"),
+
+});
+
+```
+
+
+
+API returns related records: `{ orders: [{ id: 1, ... }] }`
+
+
+
+Foreign key on child table: `client_id` (auto from parent table name).
+
+
+
+## File uploads
+
+
+
+Field types:
+
+
+
+```ts
+
+resource("products", {
+
+  name: string().required(),
+
+  photo: image(),
+
+  manual: file(),
+
+});
+
+```
+
+
+
+Upload endpoint (requires login):
+
+
+
+```
+
+POST /api/upload
+
+Content-Type: multipart/form-data
+
+
+
+file=<binary>
+
+type=image   # optional, validates image extensions
+
+```
+
+
+
+Response:
+
+
+
+```json
+
+{ "data": { "url": "/storage/uploads/uuid.jpg", "name": "photo.jpg" } }
+
+```
+
+
+
+Save the `url` in your resource field when creating/updating.
+
+
+
+## Policies
+
+
+
+Protect resources per action:
+
+
+
+```ts
+
+resource("invoices", { ... })
+
+  .policy({
+
+    view: "admin",
+
+    create: "admin",
+
+    update: (user) => user?.role === "manager",
+
+    delete: "admin",
+
+  });
+
+```
+
+
+
+`.auth("admin")` is shorthand for all actions requiring that role.
+
+
+
+## Events & Queue
+
+
+
+Events fire on CRUD:
+
+
+
+- `orders.created`
+
+- `orders.updated`
+
+- `orders.deleted`
+
+
+
+Listen:
+
+
+
+```ts
+
+import { on } from "./packages/core/src/index.js";
+
+
+
+on("orders.created", async (payload) => {
+
+  console.log("New order", payload);
+
+});
+
+```
+
+
+
+Queue jobs:
+
+
+
+```ts
+
+import { dispatch } from "./packages/core/src/index.js";
+
+
+
+await dispatch(getDb()!, "orders.created", { id: 1 });
+
+```
+
+
+
+Process jobs:
+
+
+
+```bash
+
+bun run nexa queue:work
+
+```
+
+
+
+## API — Search
+
+
+
+```
+
+GET /api/clients?search=ali
+
+```
+
+
+
+Searches all string/email/text fields.
+
+
+
+## API — Filter
+
+
+
+```
+
+GET /api/clients?city=Damascus
+
+GET /api/orders?status=paid
+
+```
+
+
+
+## API — Sort
+
+
+
+```
+
+GET /api/clients?sort=name&order=asc
+
+```
+
+
+
+## API — Pagination (Laravel format)
+
+
+
+```
+
+GET /api/clients?page=2&limit=20
+
+```
+
+
+
+Response:
+
+
+
+```json
+
+{
+
+  "data": [...],
+
+  "meta": {
+
+    "current_page": 2,
+
+    "last_page": 5,
+
+    "per_page": 20,
+
+    "total": 100,
+
+    "from": 21,
+
+    "to": 40
+
+  },
+
+  "links": {
+
+    "first": "...",
+
+    "last": "...",
+
+    "prev": "...",
+
+    "next": "..."
+
+  }
+
+}
+
+```
+
+
+
+## Combine
+
+
+
+```
+
+GET /api/clients?search=ali&city=Damascus&sort=name&order=asc&page=1&limit=10
+
+```
+

package/docs/installation.md

@@ -0,0 +1,57 @@
+# Installation
+
+## Requirements
+
+- [Node.js](https://nodejs.org) ≥ 20  
+- Optional: PostgreSQL or MySQL for production  
+- Optional: Redis for `CACHE_DRIVER=redis`
+
+## In this repo
+
+```bash
+cd F:\framework
+npm install
+npm run serve
+```
+
+- Admin: http://localhost:3333/admin  
+- Docs: http://localhost:3333/docs  
+- API: http://localhost:3333/api  
+
+Login: `admin@nexa.dev` / `123456`
+
+## As a package
+
+```bash
+npx @nexa-stack/framework new my-shop
+cd my-shop
+npm install
+npm run serve
+```
+
+## Language
+
+Default is **English** (`APP_LOCALE=en`).
+
+```env
+APP_LOCALE=en   # default
+# APP_LOCALE=ar # Arabic UI + RTL in admin
+```
+
+## Hostinger
+
+1. Create a MySQL database in hPanel  
+2. Node.js app (Node ≥ 20)  
+3. `.env`:
+
+```env
+DATABASE_URL=mysql://USER:PASS@localhost:3306/DBNAME
+APP_SECRET=change-me-to-a-long-random-string
+NODE_ENV=production
+PORT=3333
+APP_LOCALE=en
+```
+
+4. Start: `npx nexa serve`
+
+SQLite uses **sql.js** (WASM) — no Visual Studio / node-gyp. Prefer MySQL in production.

package/docs/localization.md

@@ -0,0 +1,47 @@
+# Localization
+
+Default language is **English** (`APP_LOCALE=en`).
+
+## Resource labels
+
+```ts
+resource("clients", { ... }, { labelKey: "clients" }).admin();
+```
+
+`lang/en.json`:
+
+```json
+{
+  "clients": "Clients",
+  "products": "Products",
+  "ui": { "login": "Login", "add": "Add" }
+}
+```
+
+Optional `lang/ar.json`:
+
+```json
+{
+  "clients": "العملاء",
+  "products": "المنتجات",
+  "ui": { "login": "دخول", "add": "إضافة" }
+}
+```
+
+## Admin language
+
+EN / عربي toggle in the admin UI, or:
+
+```
+GET /api/schema?lang=en
+GET /api/schema?lang=ar
+```
+
+## Default locale
+
+```env
+APP_LOCALE=en
+# APP_LOCALE=ar
+```
+
+See also [LANGUAGE.md](./LANGUAGE.md).

package/docs/resources.md

@@ -0,0 +1,75 @@
+# Resources
+
+A **resource** = database table + REST API + optional admin page.
+
+```ts
+import { resource, string, money, belongsTo } from "@nexa-stack/framework";
+// or: from "./packages/core/src/index.js"
+
+resource("products", {
+  name: string().required(),
+  price: money().required(),
+  supplier: belongsTo("suppliers"),
+}, { labelKey: "products" })
+  .admin()
+  .auth()
+  .softDeletes();
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `label` | Display name (admin) |
+| `labelKey` | Key in `lang/ar.json` / `lang/en.json` |
+
+## Chain methods
+
+| Method | Effect |
+|--------|--------|
+| `.admin()` | Show in `/admin` sidebar + **soft delete by default** |
+| `.auth(role?)` | Require login (default role `admin`) |
+| `.policy({...})` | Per-action rules: view/create/update/delete |
+| `.softDeletes()` | Soft delete + restore (already on with `.admin()`) |
+| `.hardDeletes()` | Permanent DELETE instead of soft |
+
+## Field builders
+
+| Builder | Column | Notes |
+|---------|--------|-------|
+| `string()` | TEXT | |
+| `text()` | TEXT | long text |
+| `number()` | number | |
+| `money()` | number | money amounts |
+| `email()` | TEXT | validated |
+| `boolean()` | bool/int | returns **true/false** in JSON |
+| `file()` / `image()` | TEXT | stores URL |
+| `belongsTo("table")` | `{name}_id` | nested on GET |
+| `hasMany("table")` | — | nested list on GET |
+| `belongsToMany("table")` | pivot auto | e.g. `post_tag` |
+
+Modifiers: `.required()` · `.min(n)` · `.max(n)`
+
+## Auto API
+
+For `resource("products", ...)`:
+
+| Method | URL |
+|--------|-----|
+| GET | `/api/products` |
+| GET | `/api/products/:id` |
+| POST | `/api/products` |
+| PUT | `/api/products/:id` |
+| DELETE | `/api/products/:id` |
+| GET | `/api/products/export?format=csv` |
+| POST | `/api/products/:id/restore` | if softDeletes |
+
+## Query params (list)
+
+```
+?search=ali&city=Damascus&sort=name&order=asc&page=1&limit=20
+?trashed=only   # soft-deleted only
+?trashed=with   # include deleted
+```
+
+See [database.md](./database.md) for pagination response shape.

package/docs/routing.md

@@ -0,0 +1,59 @@
+# Routing
+
+You do **not** write routes. Nexa registers them from resources.
+
+## Built-in endpoints
+
+### Framework
+
+| Method | URL | Description |
+|--------|-----|-------------|
+| GET | `/api` | List endpoints |
+| GET | `/api/schema?lang=ar` | Admin schema |
+| GET | `/api/dashboard` | Stats |
+
+### Auth
+
+| Method | URL |
+|--------|-----|
+| POST | `/api/auth/register` |
+| POST | `/api/auth/login` |
+| POST | `/api/auth/forgot-password` |
+| POST | `/api/auth/reset-password` |
+| GET/POST | `/api/auth/verify-email` |
+| POST | `/api/auth/resend-verification` |
+
+### Other
+
+| Method | URL |
+|--------|-----|
+| POST | `/api/upload` | multipart `file` |
+| GET | `/api/notifications` | unread (auth) |
+| POST | `/api/notifications/:id/read` | |
+| POST | `/api/notifications/read-all` | |
+| GET | `/storage/uploads/...` | served files |
+
+### Pages
+
+| URL | Page |
+|-----|------|
+| `/admin` | Admin UI |
+| `/docs` | Documentation |
+| `/cashier` | Demo (if present) |
+
+## Custom middleware
+
+```ts
+import { use } from "@nexa-stack/framework";
+
+use(async (req, user, next) => {
+  // before
+  const res = await next();
+  // after
+  return res;
+});
+```
+
+Default on `start()`: CORS + rate limit.
+
+See [advanced.md](./advanced.md).

package/docs/seeding.md

@@ -0,0 +1,33 @@
+# Seeding
+
+Put seeders in `database/seeders/*.ts`.
+
+```ts
+// database/seeders/erp.ts
+import type { Database } from "../../packages/database/src/database.js";
+
+export default async function seed(db: Database) {
+  if ((await db.findAll("clients")).length > 0) return;
+
+  await db.insert("clients", {
+    name: "Al Noor",
+    phone: "0502222222",
+    email: "n@corp.com",
+    city: "Damascus",
+  });
+}
+```
+
+## Run
+
+```bash
+bun run nexa db:seed
+```
+
+Also runs automatically on `nexa serve` after migrations.
+
+## Tips
+
+- Check if data exists before inserting (idempotent)
+- Seed order: parents before children (suppliers → products → orders)
+- Default admin user is created by the framework (`admin@nexa.dev`)