@nilejs/nile 0.0.4 → 0.0.5

package/README.md

@@ -1,369 +1,92 @@
-# 🌊 Nile
+# @nilejs/nile
 
 [![NPM Version](https://img.shields.io/npm/v/@nilejs/nile.svg)](https://www.npmjs.com/package/@nilejs/nile)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 
-![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
-![Hono](https://img.shields.io/badge/Hono-E36002?logo=hono&logoColor=white)
-![Zod](https://img.shields.io/badge/Zod-3E67B1?logo=zod&logoColor=white)
-![Drizzle](https://img.shields.io/badge/Drizzle-C5F74F?logo=drizzle&logoColor=black)
-
-TypeScript-first, service and actions oriented backend framework for building modern, fast, safe and AI-ready backends with simplest developer experience possible.
-
-You define actions, group them into services, and get a predictable API with validation, error handling, and schema export, no route definitions, no controllers, no middleware chains and rest api conventions to care about, just your business logic. And it's all AI agent-ready out of the box, progressively discoverable and tool calling ready with validation.
+The core framework package for Nile, a TypeScript-first, service and actions oriented backend framework.
 
 ## Install
 
-> Or View Full Docs -> [nile-js.github.io/nile](https://nile-js.github.io/nile)
-
-### Scaffold a project (recommended)
-
-The fastest way to start is with the CLI. It creates a working project with services, database, and dev tooling pre-configured:
-
-```bash
-npx @nilejs/cli new my-app
-```
-
-```bash
-cd my-app && bun install && bun run dev
-```
-
-The CLI also includes generators for adding services, actions, and extracting Zod schemas with TypeScript types. See [`@nilejs/cli`](./cli/README.md) for details.
-
-### Manual install
-
 ```bash
 bun add @nilejs/nile zod slang-ts
 ```
 
-```bash
-npm install @nilejs/nile zod slang-ts
-```
-
 If using the database layer (`createModel`, `getZodSchema`):
 
 ```bash
 bun add drizzle-orm drizzle-zod
 ```
 
-## Quick Start
+## What's in this package
 
-### 1. Define an action
+This package provides the server runtime, engine, and all core utilities:
+
+- **`createNileServer`** - Server factory that wires up services, hooks, and REST transport
+- **`createService` / `createServices`** - Service definition factories
+- **`createAction` / `createActions`** - Action definition factories with Zod validation
+- **`createModel`** - Type-safe CRUD model factory for Drizzle tables
+- **`getContext`** - Access the shared NileContext (dependency injection, resources, sessions)
+- **Engine** - Pipeline execution with before/after hooks, validation, and Result-based flow
+- **REST layer** - Single-endpoint `POST /services` transport built on Hono
+- **CORS** - Configurable origin control with per-route rules
+- **Logging** - Structured log persistence with chunking support
+- **Error handling** - `handleError` utility with Result pattern enforcement
+
+## Quick example
 
 ```typescript
-// services/tasks/create.ts
+import { createNileServer, createAction } from "@nilejs/nile";
 import { Ok } from "slang-ts";
 import z from "zod";
-import { createAction, type Action } from "@nilejs/nile";
-
-const createTaskSchema = z.object({
-  title: z.string().min(1, "Title is required"),
-  status: z.enum(["pending", "in-progress", "done"]).default("pending"),
-});
-
-const createTaskHandler = (data: Record<string, unknown>) => {
-  const task = {
-    id: crypto.randomUUID(),
-    title: data.title as string,
-    status: (data.status as string) ?? "pending",
-  };
-  return Ok({ task });
-};
 
-export const createTaskAction: Action = createAction({
-  name: "create",
-  description: "Create a new task",
-  validation: createTaskSchema,
-  handler: createTaskHandler,
+const greet = createAction({
+  name: "greet",
+  description: "Say hello",
+  validation: z.object({ name: z.string() }),
+  handler: (data) => Ok({ message: `Hello, ${data.name}!` }),
 });
-```
-
-### 2. Group actions into a service
-
-```typescript
-// services/config.ts
-import { type Services } from "@nilejs/nile";
-import { createTaskAction } from "./tasks/create";
-import { listTaskAction } from "./tasks/list";
-
-export const services: Services = [
-  {
-    name: "tasks",
-    description: "Task management",
-    actions: [createTaskAction, listTaskAction],
-  },
-];
-```
-
-### 3. Start the server
-
-```typescript
-// server.ts
-import { createNileServer } from "@nilejs/nile";
-import { services } from "./services/config";
 
 const server = createNileServer({
   serverName: "my-app",
-  services,
-  rest: {
-    baseUrl: "/api",
-    port: 8000,
-  },
+  services: [{ name: "hello", description: "Greeting service", actions: [greet] }],
+  rest: { baseUrl: "/api", port: 8000 },
 });
 
 if (server.rest) {
-  const { fetch } = server.rest.app;
-  Bun.serve({ fetch, port: 8000 });
-  console.log("Server running at http://localhost:8000");
-}
-```
-
-### 4. Call it
-
-```bash
-curl -X POST http://localhost:8000/api/services \
-  -H "Content-Type: application/json" \
-  -d '{
-    "intent": "execute",
-    "service": "tasks",
-    "action": "create",
-    "payload": { "title": "Ship it", "status": "pending" }
-  }'
-```
-
-```json
-{
-  "status": true,
-  "message": "Action 'tasks.create' executed",
-  "data": {
-    "task": {
-      "id": "a1b2c3d4-...",
-      "title": "Ship it",
-      "status": "pending"
-    }
-  }
-}
-```
-
-## Why Nile
-
-**You write business logic. Nile handles the rest.**
-
-Most backend frameworks make you think about HTTP verbs, route trees, middleware ordering, and error serialization before you write a single line of domain logic. Nile removes that ceremony. You define actions, plain functions that take data and return results, and they become callable over a single POST endpoint or other protocols such as web sockets or rpc within your codebase.
-
-**Nothing crashes silently.** Every action handler returns `Ok(data)` or `Err(message)` using the Result pattern from [Slang Ts](github.com/Hussseinkizz/slang) Functional programming utilities library. So no unhandled exceptions, no try-catch spaghetti, no mystery 500s. Your control flow is predictable by design and safe.
-
-**AI agents can call your API without adapters.** Every action with a Zod validation schema automatically exports its parameters as JSON Schema. An LLM can discover your services, read the schemas, and make tool calls, no custom integration code required.
-
-**Your database, your choice.** Nile doesn't own your data layer. When you want structured DB access, nile works with drizzle orm and any databases it supports, postgres, pglite or sqlite and more, but also provides utilities like `createModel` for simplifying type-safe CRUD operations for any Drizzle table with auto-validation, error handling, and pagination built in to reduce boilerplate. You can also use any other database library or raw queries in your action handlers, it's all up to you.
-
-**There's more to Nile** than just the core server, you get service and action based architecture, powerful hook system, structured logging and enforced error handling, rate limiting, CORS control, uploads, single context for dependency injection or sharing, and more. And you don't need a Phd to understand how to use any of them.
-
-## Core Concepts
-
-Nile uses a single POST endpoint for everything. Instead of mapping HTTP verbs to routes, you send a JSON body with an **intent** that tells the server what you want to do.
-
-Every request has the same shape:
-
-```typescript
-{
-  intent: "explore" | "execute" | "schema",
-  service: string,    // service name, or "*" for all
-  action: string,     // action name, or "*" for all
-  payload: object     // data for the action (use {} when not needed)
+  Bun.serve({ fetch: server.rest.app.fetch, port: 8000 });
 }
 ```
 
-Every response has the same shape:
+## Project structure
 
-```typescript
-{
-  status: boolean,    // true = success, false = error
-  message: string,    // human-readable description
-  data: object        // result payload, or {} on error
-}
 ```
-
-### Explore, discover what's available
-
-List all services:
-
-```bash
-curl -X POST http://localhost:8000/api/services \
-  -H "Content-Type: application/json" \
-  -d '{ "intent": "explore", "service": "*", "action": "*", "payload": {} }'
+packages/nile/
+  index.ts          # Public API exports
+  engine/           # Service registry, action pipeline, hook execution
+  nile/             # Server factory, context management
+  rest/             # Hono-based REST transport, intent handlers, middleware
+  cors/             # CORS configuration and resolution
+  logging/          # Structured log creation and retrieval
+  utils/            # Error handling, diagnostics, DB model utilities
 ```
 
-```json
-{
-  "status": true,
-  "message": "Available services",
-  "data": {
-    "result": [
-      {
-        "name": "tasks",
-        "description": "Task management",
-        "actions": ["create", "list"]
-      }
-    ]
-  }
-}
-```
-
-Drill into a service to see its actions:
+## Development
 
 ```bash
-curl -X POST http://localhost:8000/api/services \
-  -H "Content-Type: application/json" \
-  -d '{ "intent": "explore", "service": "tasks", "action": "*", "payload": {} }'
-```
-
-```json
-{
-  "status": true,
-  "message": "Actions for 'tasks'",
-  "data": {
-    "result": [
-      {
-        "name": "create",
-        "description": "Create a new task",
-        "isProtected": false,
-        "validation": true
-      }
-    ]
-  }
-}
-```
-
-### Execute, call an action
-
-This is the same call shown in Quick Start. Send `"intent": "execute"` with the service, action, and payload. The action's Zod schema validates the payload before the handler runs. If validation fails, you get a clear error:
-
-```json
-{
-  "status": false,
-  "message": "Validation failed: title - Required",
-  "data": {}
-}
-```
-
-### Schema, get JSON Schema for actions
-
-Fetch the validation schema for any action as JSON Schema. This is what makes Nile AI-ready, an agent can read these schemas to know exactly what parameters an action accepts.
-
-```bash
-curl -X POST http://localhost:8000/api/services \
-  -H "Content-Type: application/json" \
-  -d '{ "intent": "schema", "service": "tasks", "action": "create", "payload": {} }'
-```
-
-```json
-{
-  "status": true,
-  "message": "Schema for 'tasks.create'",
-  "data": {
-    "create": {
-      "type": "object",
-      "properties": {
-        "title": { "type": "string", "minLength": 1 },
-        "status": { "type": "string", "enum": ["pending", "in-progress", "done"], "default": "pending" }
-      },
-      "required": ["title"]
-    }
-  }
-}
-```
-
-Use `"service": "*", "action": "*"` to get schemas for every action across all services in one call.
-
-### Hooks, intercept and transform
+# Run tests
+bun run test:run
 
-Hooks let you run logic before or after an action executes. They work at two levels:
+# Build
+bun run build
 
-**Per-action hooks** point to other registered actions. A hook definition is just a reference, `{ service, action, isCritical }`, so any action can serve as a hook for any other action.
-
-```typescript
-export const createTaskAction: Action = createAction({
-  name: "create",
-  description: "Create a new task",
-  validation: createTaskSchema,
-  handler: createTaskHandler,
-  hooks: {
-    before: [
-      { service: "audit", action: "logAccess", isCritical: false }
-    ],
-    after: [
-      { service: "notifications", action: "notify", isCritical: false }
-    ]
-  },
-});
+# Lint and format
+bun run check && bun run fix
 ```
 
-Before hooks run sequentially and chain, each hook's output becomes the next hook's input. After hooks work the same way, receiving the handler's result.
-
-When `isCritical` is `true`, a hook failure stops the pipeline. When `false`, failures are logged and skipped.
-
-**Global hooks** run on every action. Define them in your server config:
-
-```typescript
-const server = createNileServer({
-  serverName: "my-app",
-  services,
-  onBeforeActionHandler: ({ nileContext, action, payload }) => {
-    // runs before every action, auth checks, logging, etc.
-    return Ok(payload);
-  },
-  onAfterActionHandler: ({ nileContext, action, payload, result }) => {
-    // runs after every action, transforms, auditing, etc.
-    return result;
-  },
-});
-```
-
-The full execution pipeline runs in this order:
-
-```txt
-Global Before Hook
-  -> Per-Action Before Hooks (sequential)
-    -> Validation (Zod)
-      -> Handler
-    -> Per-Action After Hooks (sequential)
-  -> Global After Hook
--> Response
-```
-
-Any step returning `Err` short-circuits the pipeline.
-
-## Project Structure
-
-```txt
-my-api/
-  server.ts
-  services/
-    config.ts
-    tasks/
-      create.ts
-      list.ts
-      get.ts
-  db/
-    schema.ts
-    client.ts
-    models/
-      tasks.ts
-```
-
-## Contributing
-
-> First developed by Hussein Kizz at [Nile Squad Labz](https://nilesquad.com) to power our own B2B saas products and services, and now open-sourced for the community. Over 1 year in the making, to now powering Agentic backends and open for community contributions.
-
-Contributions are welcome.
+## Related packages
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/your-feature`)
-3. Commit your changes (`git commit -m 'Add your feature'`)
-4. Push to the branch (`git push origin feature/your-feature`)
-5. Open a Pull Request
+- [`@nilejs/cli`](https://github.com/nile-js/nile/tree/main/packages/cli) - Project scaffolding and code generation
+- [`@nilejs/client`](https://github.com/nile-js/nile/tree/main/packages/client) - Type-safe frontend client
 
 ## License
 

package/dist/index.cjs

@@ -27,7 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/index.ts
+// index.ts
 var index_exports = {};
 __export(index_exports, {
   createAction: () => createAction,
@@ -46,7 +46,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/engine/create-action.ts
+// engine/create-action.ts
 function createAction(config) {
   return config;
 }
@@ -54,7 +54,7 @@ function createActions(configs) {
   return configs;
 }
 
-// src/engine/create-service.ts
+// engine/create-service.ts
 function createService(config) {
   return config;
 }
@@ -62,7 +62,7 @@ function createServices(configs) {
   return configs;
 }
 
-// src/logging/logger.ts
+// logging/logger.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_nanoid = require("nanoid");
@@ -305,7 +305,7 @@ function applyLogFilters(logs, filters) {
   });
 }
 
-// src/logging/create-log.ts
+// logging/create-log.ts
 var createLogger = (appName, config) => {
   return {
     info: (input) => createLog({ ...input, appName, level: "info" }, config),
@@ -314,17 +314,17 @@ var createLogger = (appName, config) => {
   };
 };
 
-// src/nile/server.ts
+// nile/server.ts
 var import_slang_ts7 = require("slang-ts");
 
-// src/engine/engine.ts
+// engine/engine.ts
 var import_slang_ts4 = require("slang-ts");
 
-// src/utils/db/create-model.ts
+// utils/db/create-model.ts
 var import_drizzle_orm = require("drizzle-orm");
 var import_slang_ts2 = require("slang-ts");
 
-// src/utils/handle-error.ts
+// utils/handle-error.ts
 var import_slang_ts = require("slang-ts");
 var CALLER_LINE_REGEX = /at\s+(\S+)\s+/;
 function inferCallerName() {
@@ -360,7 +360,7 @@ function handleError(params) {
   return (0, import_slang_ts.Err)(`[${logId}] ${params.message}`);
 }
 
-// src/utils/db/create-transaction-variant.ts
+// utils/db/create-transaction-variant.ts
 function createTransactionVariant(fn) {
   return async (params) => {
     const { dbx, ...rest } = params;
@@ -389,7 +389,7 @@ function createTransactionVariant(fn) {
   };
 }
 
-// src/utils/db/get-zod-schema.ts
+// utils/db/get-zod-schema.ts
 var import_drizzle_zod = require("drizzle-zod");
 function getZodSchema(table) {
   const isRelation = Object.hasOwn(table, "config") && Object.hasOwn(table, "table");
@@ -414,7 +414,7 @@ function getZodSchema(table) {
   };
 }
 
-// src/utils/db/create-model.ts
+// utils/db/create-model.ts
 function asDb(db) {
   return db;
 }
@@ -666,7 +666,7 @@ function createModel(table, options) {
   };
 }
 
-// src/utils/diagnostics-log.ts
+// utils/diagnostics-log.ts
 function isNileLogger(logger) {
   return "warn" in logger && "error" in logger;
 }
@@ -693,7 +693,7 @@ function createDiagnosticsLog(prefix, params) {
   };
 }
 
-// src/engine/pipeline.ts
+// engine/pipeline.ts
 var import_slang_ts3 = require("slang-ts");
 var import_zod = require("zod");
 async function runHook(hookDef, hookAction, input, nileContext) {
@@ -803,7 +803,7 @@ async function runHandler(action, payload, nileContext, log) {
   return (0, import_slang_ts3.Ok)(result.value);
 }
 
-// src/engine/engine.ts
+// engine/engine.ts
 function createEngine(options) {
   const { diagnostics, services, logger } = options;
   const log = createDiagnosticsLog("Engine", {
@@ -937,11 +937,11 @@ function createEngine(options) {
   };
 }
 
-// src/rest/rest.ts
+// rest/rest.ts
 var import_hono = require("hono");
 var import_zod3 = __toESM(require("zod"), 1);
 
-// src/cors/cors.ts
+// cors/cors.ts
 var import_cors = require("hono/cors");
 var buildDefaultCorsOptions = (config) => {
   const getDefaultOrigin = (reqOrigin) => {
@@ -1023,7 +1023,7 @@ var evaluateResolver = (resolver, origin, c, defaultOpts) => {
   }
 };
 
-// src/rest/intent-handlers.ts
+// rest/intent-handlers.ts
 var import_slang_ts5 = require("slang-ts");
 var import_zod2 = __toESM(require("zod"), 1);
 function toExternalResponse(result, successMessage) {
@@ -1156,7 +1156,7 @@ var intentHandlers = {
   schema: (engine, request) => handleSchema(engine, request)
 };
 
-// src/rest/middleware.ts
+// rest/middleware.ts
 var import_hono_rate_limiter = require("hono-rate-limiter");
 var import_slang_ts6 = require("slang-ts");
 var ASSETS_REGEX = /^\/assets\//;
@@ -1226,7 +1226,7 @@ function applyStaticServing(app, config, runtime, log) {
   log("Static file serving enabled at /assets/*");
 }
 
-// src/rest/rest.ts
+// rest/rest.ts
 var externalRequestSchema = import_zod3.default.object({
   intent: import_zod3.default.enum(["explore", "execute", "schema"]),
   service: import_zod3.default.string().min(1),
@@ -1297,7 +1297,7 @@ function createRestApp(params) {
   return app;
 }
 
-// src/nile/nile.ts
+// nile/nile.ts
 function createNileContext(params) {
   const store = /* @__PURE__ */ new Map();
   const interfaceContext = params?.interfaceContext;
@@ -1351,7 +1351,7 @@ function createNileContext(params) {
   return context;
 }
 
-// src/nile/server.ts
+// nile/server.ts
 var _nileContext = null;
 function getContext() {
   if (!_nileContext) {