caspian-utils 0.0.1

package/dist/docs/state.md

@@ -0,0 +1,264 @@
+---
+title: State Management
+description: Manage transient Caspian server state with `casp.state_manager` and `StateManager`, using request-scoped ContextVar storage, shallow AttributeDict reads, listener callbacks, and session-backed JSON persistence.
+related:
+  title: Related docs
+  description: Pair server request state with auth and RPC flows, then read the PulsePoint guide when the state really belongs in the browser instead of the request lifecycle.
+  links:
+    - /docs/auth
+    - /docs/fetch-data
+    - /docs/pulsepoint
+    - /docs/project-structure
+    - /docs/index
+---
+
+This page explains the current installed Caspian state manager API for request-scoped state, session-backed persistence, listener callbacks, and AttributeDict reads.
+
+Treat `casp.state_manager` as the transient server-state layer in Caspian. Use it for short-lived state that should be available during the current request and, where the middleware flow allows it, across a tightly scoped follow-up request. Do not treat it as a database, a long-lived session model, or a replacement for PulsePoint browser state.
+
+## Overview
+
+Caspian exposes request state through `casp.state_manager`.
+
+Import the public API like this:
+
+```python
+from casp.state_manager import StateManager
+```
+
+The current installed implementation lives in `.venv/Lib/site-packages/casp/state_manager.py`.
+
+The real API surface is:
+
+- request initialization with `StateManager.init(request)`
+- top-level state reads with `StateManager.get_state(...)`
+- top-level state writes with `StateManager.set_state(...)`
+- reset operations with `StateManager.reset_state(...)`
+- request-local subscriptions with `StateManager.subscribe(...)`
+
+Use this layer when middleware, route handlers, auth flows, or RPC actions need a shared transient state bag without explicitly threading the request object through every helper.
+
+## Default State Rule
+
+- Use `StateManager` for short-lived server state such as flash-style messages, transient form state, or middleware-to-route coordination.
+- Keep values JSON-serializable because every write persists the full state dict with `json.dumps(...)`.
+- Read and write top-level keys. The current implementation does not provide deep merge, nested path helpers, or delete helpers.
+- Let middleware initialize the manager. App code usually should not call `StateManager.init(...)` directly.
+- Use PulsePoint for browser reactivity and persistent data stores for durable application state.
+
+## Request-Scoped Storage Model
+
+The installed implementation stores state in `ContextVar` containers:
+
+- `_state_data` holds the current request's state dict
+- `_state_listeners` holds the current request's listener callbacks
+- `_current_request` holds the current request object
+
+That means the state manager is request-scoped, not process-global. One request does not share in-memory state or listeners with another request.
+
+The session persistence layer is separate from the in-memory request copy. `save_state()` serializes the current dict to JSON and stores it under the constant key `app_state_cL7y4KirLp`.
+
+Important implementation detail:
+
+- the current code reads and writes `request.state.session`, not `request.session`
+
+In other words, cross-request persistence depends on the surrounding Caspian middleware keeping `request.state.session` available and in sync with session storage.
+
+## Request Lifecycle
+
+The current request lifecycle is:
+
+1. `StateManager.init(request)` stores the request object.
+2. It clears the in-memory state dict and listener list for the new request.
+3. It calls `load_state()` and tries to decode any previously saved JSON from the session bucket.
+4. It checks the `X-PulsePoint-Wire` header.
+5. When that header is missing or falsy, it immediately calls `reset_state()`.
+
+That last step matters. In the current implementation, non-wire requests start by clearing the loaded state and writing the empty state back to the session bucket.
+
+Treat the current behavior as request-local state plus framework-managed transient persistence for wire-driven flows. If you expect full-page redirect flash semantics, verify the exact middleware and request path in your local Caspian version before depending on it.
+
+You usually do not initialize this manually in route code. The current auth middleware docs already show `StateManager.init(request)` running during request setup.
+
+## Reading State
+
+Use `StateManager.get_state(...)` to read the whole state bag or a single top-level key.
+
+Behavior:
+
+- `StateManager.get_state()` returns an `AttributeDict` wrapping the full top-level state dict
+- `StateManager.get_state("key", initial_value)` returns the stored value or the provided default
+- when the returned value is a dict, the direct return value is wrapped in `AttributeDict`
+
+Example:
+
+```python
+from casp.state_manager import StateManager
+
+StateManager.set_state("flash", {
+    "type": "success",
+    "message": "Profile updated.",
+})
+
+flash = StateManager.get_state("flash")
+if flash is not None:
+    print(flash.type)
+    print(flash.message)
+
+state = StateManager.get_state()
+print(state.flash["message"])
+```
+
+Implementation note:
+
+- `AttributeDict` is shallow in the current file
+
+`StateManager.get_state("flash")` wraps that one dict, so `flash.message` works. `StateManager.get_state()` wraps only the top-level state object, so nested dict values remain plain dicts unless you fetch that key directly.
+
+Do not assume recursive dot notation such as `StateManager.get_state().flash.message` unless your stored nested value has already been wrapped elsewhere.
+
+## Writing State
+
+Use `StateManager.set_state(key, value)` to replace a top-level key.
+
+Current behavior:
+
+- updates the current in-memory dict in place
+- notifies every registered listener
+- serializes the entire state dict into the session bucket
+
+Example:
+
+```python
+from casp.rpc import rpc
+from casp.state_manager import StateManager
+
+@rpc(require_auth=True)
+async def save_profile(data: dict):
+    StateManager.set_state("flash", {
+        "type": "success",
+        "message": "Profile updated.",
+    })
+
+    return {"success": True}
+```
+
+Keep writes JSON-safe. The current `save_state()` implementation does not catch `TypeError` from `json.dumps(...)`, so non-serializable values such as file handles, request objects, response objects, or arbitrary class instances can break the write path.
+
+## Resetting State
+
+Use `StateManager.reset_state(...)` to clear either one key or the whole state dict.
+
+Example:
+
+```python
+from casp.state_manager import StateManager
+
+StateManager.reset_state("flash")
+StateManager.reset_state()
+```
+
+Current behavior is slightly surprising:
+
+- `StateManager.reset_state()` replaces the whole state dict with `{}`
+- `StateManager.reset_state("flash")` does not delete the key; it sets the existing key to `None`
+- both forms notify listeners and save the updated state back to the session bucket
+
+If you need true key removal, there is no public delete helper in the current implementation.
+
+## Request-Local Listeners
+
+`StateManager.subscribe(listener)` registers a callback for the current request context.
+
+Behavior:
+
+- appends the listener to the current request's listener list
+- immediately invokes the listener with the current state dict
+- returns an `unsubscribe()` function that removes that listener from the current request list
+
+Example:
+
+```python
+from casp.state_manager import StateManager
+
+def log_changes(state):
+    if state.get("error"):
+        print(f"Error detected: {state['error']}")
+
+unsubscribe = StateManager.subscribe(log_changes)
+
+StateManager.set_state("error", "Invalid credentials")
+
+unsubscribe()
+```
+
+Treat these listeners as request-local callbacks, not as a cross-request event bus.
+
+The current implementation resets `_state_listeners` inside `StateManager.init(...)`, so subscriptions do not survive into later requests.
+
+## API Reference
+
+| Method | Purpose | Current behavior |
+| --- | --- | --- |
+| `init(request)` | Prepare request-bound state | Stores the request, clears in-memory state and listeners, loads saved JSON state, then clears state again for non-wire requests. |
+| `get_state(key=None, initial_value=None)` | Read all state or one key | Returns a shallow `AttributeDict` for dict values and the provided default for missing keys. |
+| `set_state(key, value)` | Replace one top-level key | Mutates the state dict, notifies listeners, and JSON-saves the full state bag. |
+| `reset_state(key=None)` | Clear one key or everything | Sets one key to `None` or replaces the full dict with `{}`. |
+| `subscribe(listener)` | Listen for request-local changes | Immediately invokes the listener and returns an unsubscribe closure. |
+| `save_state()` | Persist current state | Serializes the full dict into the session bucket under `APP_STATE_KEY`. |
+| `load_state()` | Rehydrate saved state | Loads JSON when the session bucket exists and ignores malformed JSON. |
+
+## Current Implementation Notes
+
+- The persistence bucket key is `StateManager.APP_STATE_KEY = "app_state_cL7y4KirLp"`.
+- `load_state()` only catches `json.JSONDecodeError`; malformed JSON is ignored silently.
+- `save_state()` writes the entire state dict every time `set_state()` or `reset_state()` runs.
+- `set_state()` replaces a top-level key value. There is no deep merge behavior.
+- `notify_listeners()` runs on every `set_state()`, successful `load_state()`, and every `reset_state()` call.
+- Listener callbacks receive the raw state dict, not an `AttributeDict` wrapper.
+- `AttributeDict.__getattr__` raises `AttributeError` for missing keys and `__setattr__` writes back into the dict.
+- Because persistence uses JSON, keep stored values simple: strings, numbers, booleans, lists, dicts, and `None`.
+- The current lifecycle resets loaded state on non-wire requests, so verify redirect and flash behavior against the actual request type you are using.
+
+## Recommended Usage Pattern
+
+Use `StateManager` close to the request boundary and keep the stored payloads small.
+
+Common placement patterns are:
+
+- route handlers that need to share transient data with helpers in the same request
+- `@rpc()` actions that record short-lived success or error state during a wire-driven flow
+- auth-aware flows that need request-bound coordination between middleware and route logic
+- shared helpers under `src/lib/` when multiple routes use the same transient-state conventions
+
+Good candidates for this state layer are:
+
+- success or error messages
+- temporary redirect or workflow flags
+- lightweight request-bound metadata
+- small structured dicts that can be serialized safely
+
+Poor candidates are:
+
+- ORM models or request objects
+- file handles and uploads
+- large payloads or cached query results
+- durable business data that belongs in a database
+- browser interaction state that should live in PulsePoint
+
+For browser-triggered writes and route actions, pair this page with [fetch-data.md](./fetch-data.md). For middleware and session-aware auth flows, pair it with [auth.md](./auth.md).
+
+## AI Routing Notes
+
+If an AI agent is deciding how to use transient state in a Caspian app, apply these rules first.
+
+- Use `StateManager` from `casp.state_manager` for request-scoped server state, not for durable application records.
+- Assume the current API is top-level-key based only.
+- Keep stored values JSON-serializable.
+- Prefer `StateManager.get_state("key")` when you want dot notation on a dict payload.
+- Do not assume recursive `AttributeDict` wrapping for nested dicts.
+- Treat `subscribe(...)` listeners as request-local and short-lived.
+- Be careful with full-page redirect assumptions because `init(request)` clears loaded state on non-wire requests.
+- Use PulsePoint state for client interactivity and `StateManager` for server request flows.
+- Check [auth.md](./auth.md) for middleware ordering and request initialization details.
+- Check [project-structure.md](./project-structure.md) before deciding whether a transient-state helper belongs next to a route or in `src/lib/`.

package/dist/docs/validation.md

@@ -0,0 +1,293 @@
+---
+title: Validation
+description: Validate and sanitize Caspian inputs with `casp.validate`, `Validate`, `Rule`, direct validators, rule-based checks, and file or date or ID validation before route or RPC logic persists data, with Validate as the default server-side validation layer.
+related:
+  title: Related docs
+    description: Use the auth guide for session and credential flows, the fetch-data guide when validation runs inside RPC actions, then use the structure guide to place reusable validators in the right layer.
+  links:
+        - /docs/auth
+    - /docs/fetch-data
+    - /docs/routing
+    - /docs/project-structure
+    - /docs/index
+---
+
+This page explains the current installed Caspian validation API for direct field checks, rule-based validation, sanitization, and reusable input guards.
+
+Treat `casp.validate` as the default validation layer in Caspian app code. Do not rely on client-only checks or hand-rolled validation helpers when `Validate` and `Rule` already cover the input boundary.
+
+## Overview
+
+Caspian exposes validation through `casp.validate`.
+
+Import the public API like this:
+
+```python
+from casp.validate import Validate, Rule
+```
+
+The current installed implementation lives in `.venv/Lib/site-packages/casp/validate.py`.
+
+The real API surface is:
+
+- direct single-value validation with `Validate.*(...)`
+- multi-rule validation with `Validate.with_rules(...)`
+- rule-string helpers built with `Rule`
+
+Use validation at the boundary where untrusted data enters the app, especially in form handling, auth flows, and RPC mutations.
+
+## Default Validation Rule
+
+- Use `Validate.*(...)` for direct coercion, sanitization, and simple boundary checks.
+- Use `Validate.with_rules(...)` plus `Rule` for maintained forms, RPC payloads, and multi-constraint workflows.
+- Keep PulsePoint-side checks as UX improvements only; the authoritative validation still belongs on the server boundary.
+- Validate before persistence, authorization decisions, external API calls, or any RPC side effect.
+
+## Framework Internals Note
+
+- The validation implementation lives in `.venv/Lib/site-packages/casp/validate.py`.
+- Treat that file as framework code. Read it when the task is about validation internals, debugging framework behavior, or documenting the installed Caspian implementation.
+- If upstream docs and the installed file disagree, prefer the installed file for local project guidance.
+
+## Direct Validation
+
+Use direct validators when you only need to check one value. These helpers usually return a sanitized or coerced value on success and `None` on failure.
+
+The current `Validate` class exposes these main groups of helpers:
+
+| Category | Methods | Notes |
+| --- | --- | --- |
+| Strings and identifiers | `string`, `email`, `url`, `ip`, `uuid`, `ulid`, `cuid`, `cuid2`, `nanoid`, `bytes`, `xml` | `string()` trims input and escapes HTML by default. |
+| Numbers | `int`, `big_int`, `float`, `decimal` | `decimal()` returns a quantized `Decimal`, with `scale=30` by default. |
+| Dates and times | `date`, `date_time` | Uses PHP-style format tokens such as `Y-m-d` and `Y-m-d H:i:s`. |
+| Booleans | `boolean` | Accepts `1`, `true`, `on`, `yes`, `y` and the corresponding false forms. |
+| Structured values | `json`, `is_json`, `enum`, `enum_class` | `json()` serializes non-strings and validates JSON strings. |
+| Text utility | `emojis` | Replaces supported text tokens such as `:wave:` and `<3`. |
+
+Example:
+
+```python
+from casp.validate import Validate
+
+email = Validate.email("  User@Example.com ")
+# Result: "User@Example.com"
+
+identifier = Validate.cuid2("tz4a98xxat96iws9zmbrgj3a")
+# Result: "tz4a98xxat96iws9zmbrgj3a"
+
+invalid = Validate.url("not-a-url")
+# Result: None
+
+safe_name = Validate.string(" <Admin> ")
+# Result: "&lt;Admin&gt;"
+
+enabled = Validate.boolean("yes")
+# Result: True
+```
+
+Implementation notes from the installed file:
+
+- `Validate.string(value, escape_html=True)` trims and HTML-escapes by default.
+- `Validate.date(...)` and `Validate.date_time(...)` use PHP-style format tokens mapped internally to Python datetime formats.
+- `Validate.decimal(...)` returns a `Decimal` rounded with `ROUND_HALF_UP`.
+- `Validate.cuid(...)` accepts either installed-library-backed legacy CUID or CUID2-like values depending on available packages.
+- `Validate.is_json(...)` is the strict boolean check. `Validate.json(...)` returns serialized JSON for non-strings and parser text for invalid JSON strings.
+
+Use this style for:
+
+- one-off field checks
+- simple preconditions before a query or mutation
+- cases where `None` is enough to branch into an error response
+
+For sign-in, signup, reset-password, and other session-aware flows, pair these checks with `casp.auth` patterns from `auth.md`.
+
+## Rules Engine With `with_rules`
+
+Use `Validate.with_rules(...)` when a field needs multiple constraints.
+
+The current function signature is conceptually:
+
+```python
+Validate.with_rules(value, rules, confirmation_value=None)
+```
+
+It accepts two rule formats:
+
+- a pipe-separated string such as `required|min:3|max:20|regex:^[a-zA-Z0-9_]+$`
+- a list of rule strings, often created with `Rule`
+
+Example:
+
+```python
+from casp.validate import Validate, Rule
+
+def register_user(data):
+    username = data.get("username")
+    password = data.get("password")
+    password_confirmation = data.get("password_confirmation")
+
+    check = Validate.with_rules(
+        username,
+        "required|min:3|max:20|regex:^[a-zA-Z0-9_]+$",
+    )
+
+    check_safe = Validate.with_rules(username, [
+        Rule.REQUIRED,
+        Rule.min(3),
+        Rule.max(20),
+        Rule.regex(r"^[a-zA-Z0-9_]+$"),
+        Rule.not_in_list(["admin", "root"]),
+    ])
+
+    password_check = Validate.with_rules(password, [
+        Rule.REQUIRED,
+        Rule.min(8),
+        Rule.confirmed(),
+    ], confirmation_value=password_confirmation)
+
+    if check_safe is not True:
+        return {"error": check_safe}
+
+    if password_check is not True:
+        return {"error": password_check}
+
+    return {"success": True}
+```
+
+The current implementation applies rules in order and stops on the first failure.
+
+Contract:
+
+- `True` means the value passed all rules
+- a non-`True` result is the first validation error message
+
+Prefer the `Rule` form when the rules will live in maintained project code because it reduces string typos and gives better autocomplete, even though `Rule` ultimately returns rule strings.
+
+## Implemented Rule Set
+
+The installed `apply_rule(...)` implementation currently supports these rule names:
+
+- Presence and length: `required`, `min`, `max`, `size`, `between`
+- Prefix and suffix: `startsWith`, `endsWith`
+- Confirmation: `confirmed`
+- Format and identity: `email`, `url`, `ip`, `uuid`, `ulid`, `cuid`, `cuid2`, `nanoid`, `json`, `regex`
+- Numeric and boolean: `int`, `float`, `boolean`, `digits`, `digitsBetween`
+- Membership: `in`, `notIn`
+- Dates: `date`, `dateFormat`, `before`, `after`
+- Files: `file`, `extensions`, `mimes`
+
+The `Rule` helper currently provides:
+
+- Constants: `REQUIRED`, `EMAIL`, `URL`, `IP`, `UUID`, `ULID`, `CUID`, `CUID2`, `NANOID`, `INTEGER`, `FLOAT`, `BOOLEAN`, `JSON`, `FILE`
+- Methods: `min`, `max`, `size`, `starts_with`, `ends_with`, `confirmed`, `in_list`, `not_in_list`, `between`, `digits`, `digits_between`, `date`, `date_format`, `before`, `after`, `regex`, `extensions`, `mimes`
+
+Examples:
+
+| Rule | Helper | Purpose |
+| --- | --- | --- |
+| `required` | `Rule.REQUIRED` | Fails for `None`, empty strings, and empty collections. |
+| `email` | `Rule.EMAIL` | Validates email format. |
+| `min` / `max` | `Rule.min(5)` / `Rule.max(20)` | Enforces string length constraints. |
+| `confirmed` | `Rule.confirmed()` | Compares the value to `confirmation_value`. |
+| `in` / `notIn` | `Rule.in_list([...])` / `Rule.not_in_list([...])` | Restricts or blocks specific values. |
+| `regex` | `Rule.regex(r"^[a-z]+$")` | Matches a custom regular expression. |
+| `extensions` / `mimes` | `Rule.extensions([...])` / `Rule.mimes([...])` | Validates upload extensions or MIME types. |
+
+## File Validation
+
+The installed file includes upload-oriented helpers and rules.
+
+- `file` passes when the value is a filesystem path, a readable file-like object, or an object with `read(...)`.
+- `extensions` validates file suffixes from a path or `filename` attribute.
+- `mimes` uses `python-magic` when installed for MIME sniffing, then falls back to `mimetypes.guess_type(...)`.
+
+Use these rules for RPC uploads and form submissions that accept files.
+
+## Sanitization
+
+Validation in Caspian is more than rule checking. The installed implementation also sanitizes or normalizes several values.
+
+Documented behaviors include:
+
+- trimming and cleaning string inputs during direct validation
+- sanitization helpers for safer string handling
+- normalization for formats such as dates and booleans
+
+Concrete examples from the current file:
+
+- `Validate.string(...)` escapes HTML unless `escape_html=False`
+- `Validate.boolean(...)` normalizes common truthy and falsy text values
+- `Validate.date_time(...)` accepts multiple parse paths before formatting the final string
+
+This means validation should happen before application code persists, compares, or authorizes incoming values.
+
+## Optional Dependency Behavior
+
+The installed implementation uses optional packages when they are available:
+
+- `email-validator` for stronger email validation
+- `python-dateutil` for more flexible datetime parsing
+- `python-magic` for content-based MIME detection
+- `cuid2` and `cuid` packages to recognize specific ID formats
+
+If those packages are missing, the module falls back to simpler behavior.
+
+## Current Implementation Notes
+
+- Unknown rule names currently fall through and pass because `apply_rule(...)` returns `True` when a rule is not recognized.
+- The upstream docs show `alpha_num`, but the current installed `apply_rule(...)` implementation does not implement an `alpha_num` rule.
+- Use `regex` for alphanumeric username rules until the framework adds a dedicated `alpha_num` rule.
+- `Rule` is an IntelliSense and string-builder helper, not an enum-backed validator by itself.
+
+## Recommended Usage Pattern
+
+Validate close to the input boundary.
+
+Common placement patterns are:
+
+- inside `@rpc()` actions before database writes
+- inside route-level backend files such as `src/app/**/index.py`
+- in shared helpers under `src/lib/` when multiple routes or actions reuse the same rule sets
+
+For browser-triggered writes and form submissions, pair this page with [fetch-data.md](./fetch-data.md).
+
+Example RPC action:
+
+```python
+from casp.rpc import rpc
+from casp.validate import Validate, Rule
+
+@rpc()
+def create_account(data: dict):
+    email = Validate.email(data.get("email"))
+    password = data.get("password")
+
+    password_check = Validate.with_rules(password, [
+        Rule.REQUIRED,
+        Rule.min(8),
+    ])
+
+    if email is None:
+        return {"error": "Invalid email address."}
+
+    if password_check is not True:
+        return {"error": password_check}
+
+    return {"success": True}
+```
+
+## AI Routing Notes
+
+If an AI agent is deciding how to validate input in Caspian, apply these rules first.
+
+- Treat `Validate` and `Rule` as the default validation API for Caspian app code.
+- Use direct `Validate.*(...)` calls for quick single-field checks.
+- Use `Validate.with_rules(...)` for multi-constraint validation.
+- Prefer `Rule` helpers in maintained project code instead of long rule strings.
+- Validate request, form, and RPC payloads before database writes or auth-sensitive logic.
+- Put reusable validation workflows in `src/lib/` when multiple routes need them.
+- Keep route-specific validation next to the route or action that owns the input boundary.
+- Use `.venv/Lib/site-packages/casp/validate.py` only when the task is about Caspian core validation internals or framework debugging.
+- Prefer the implemented local rule set over upstream examples when they differ.
+- Pair validation with [fetch-data.md](./fetch-data.md) when user input arrives through `pp.rpc()`.
+- Check [project-structure.md](./project-structure.md) before deciding whether a validator belongs in `src/app/` or `src/lib/`.

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "caspian-utils",
+  "version": "0.0.1",
+  "description": "Caspian tooling",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "caspian",
+    "docs"
+  ],
+  "author": "Jefferson Abraham Omier <thesteelninjacode@gmail.com>",
+  "license": "MTI",
+  "type": "module"
+}