v0.35.0

Enigmatic

A lightweight client-side JavaScript library for DOM manipulation, reactive state management, and API interactions, with an optional Bun server for backend functionality.

Try Demo View on npm

Quick Start

Using client.js via CDN

Include client.js in any HTML file using the unpkg CDN:

<script src="https://unpkg.com/enigmatic"></script>
<script src="https://unpkg.com/enigmatic/client/public/custom.js"></script>
<script>
  window.api_url = 'https://your-server.com';
  window.state.message = 'Hello World';
</script>

Using the Bun Server

The Bun server provides a complete backend with:

Installation

  1. Install Bun: 
    curl -fsSL https://bun.sh/install | bash
  2. Install dependencies: 
    bun install
  3. TLS certificates: place cert.pem and key.pem in server/certs/ for HTTPS

Running the Server

npm start
# or
npx enigmatic
# or with hot reload
npm run hot

Server runs at https://localhost:3000 (HTTPS is required for Auth0 cookies).

Features

DOM Utilities

Simple selectors: window.$, window.$$, window.$c

Reactive State

Proxy-based state management that automatically updates DOM elements

Custom Elements

Automatic initialization and reactive updates for custom HTML elements

KV Storage

Simple key-value operations: get, set, delete

File Storage

Upload, download, list, and delete files via R2/S3-compatible storage

Authentication

Built-in Auth0 OAuth2 integration with login/logout

API Endpoints

Method Path Description
GET / Serves index.html
GET /login Redirects to Auth0 login
GET /callback Auth0 OAuth callback
GET /logout Logs out and clears session
GET /me Current user or 401 (no auth)
GET /{key} KV get (auth required)
POST /{key} KV set (auth required)
DELETE /{key} KV delete (auth required)
PUT /{key} Upload file to R2 (auth required)
PURGE /{key} Delete file from R2 (auth required)
PROPFIND / List R2 files (auth required)
PATCH /{key} Download file from R2 (auth required)

Example Usage

Reactive State

<hello-world data="message"></hello-world>
<script>
  window.custom['hello-world'] = (data) => `Hello ${data}`;
  window.state.message = "World"; // Automatically updates the element
</script>

KV Storage

// Get value
const value = await window.get('my-key');

// Set value
await window.set('my-key', 'my-value');

// Delete key
await window.delete('my-key');

File Operations

// Upload file
await window.put('filename.txt', fileBlob);

// List files
const files = await window.list();

// Download file
await window.download('filename.txt');

// Delete file
await window.purge('filename.txt');

Environment Variables

Create a .env file in the project root:

# Auth0
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

# Cloudflare R2 (optional, for file storage)
CLOUDFLARE_ACCESS_KEY_ID=your-access-key-id
CLOUDFLARE_SECRET_ACCESS_KEY=your-secret-access-key
CLOUDFLARE_BUCKET_NAME=your-bucket-name
CLOUDFLARE_PUBLIC_URL=https://your-account-id.r2.cloudflarestorage.com