@beeblock/svelar 0.4.0

package/dist/session/Session.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Svelar Session Manager
+ *
+ * Server-side session management with pluggable stores.
+ * Supports cookie-based sessions with in-memory, file, or database backing stores.
+ *
+ * @example
+ * ```ts
+ * // In hooks.server.ts
+ * import { SessionMiddleware, MemorySessionStore } from 'svelar/session';
+ *
+ * export const handle = createSvelarHooks({
+ *   middleware: [
+ *     new SessionMiddleware({ store: new MemorySessionStore() }),
+ *   ],
+ * });
+ *
+ * // In a controller or +server.ts
+ * event.locals.session.get('user_id');
+ * event.locals.session.set('flash_message', 'Login successful');
+ * ```
+ */
+export interface SessionData {
+    [key: string]: any;
+}
+export interface SessionStore {
+    /** Read session data by ID */
+    read(id: string): Promise<SessionData | null>;
+    /** Write session data */
+    write(id: string, data: SessionData, ttl: number): Promise<void>;
+    /** Destroy a session */
+    destroy(id: string): Promise<void>;
+    /** Garbage collect expired sessions */
+    gc?(maxLifetime: number): Promise<void>;
+}
+export interface SessionConfig {
+    /** Session cookie name */
+    cookieName?: string;
+    /** Session lifetime in seconds (default: 7200 = 2 hours) */
+    lifetime?: number;
+    /** Secret for signing session IDs */
+    secret?: string;
+    /** Cookie path */
+    path?: string;
+    /** Cookie domain */
+    domain?: string;
+    /** Secure cookie (HTTPS only) */
+    secure?: boolean;
+    /** HttpOnly cookie */
+    httpOnly?: boolean;
+    /** SameSite policy */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /** Session store implementation */
+    store: SessionStore;
+}
+export declare class Session {
+    readonly id: string;
+    private data;
+    private dirty;
+    private flashData;
+    private previousFlashData;
+    constructor(id: string, initialData?: SessionData);
+    /**
+     * Get a session value
+     */
+    get<T = any>(key: string, defaultValue?: T): T;
+    /**
+     * Set a session value
+     */
+    set(key: string, value: any): void;
+    /**
+     * Check if a key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Remove a session value
+     */
+    forget(key: string): void;
+    /**
+     * Clear all session data
+     */
+    flush(): void;
+    /**
+     * Flash data — available only on the next request
+     */
+    flash(key: string, value: any): void;
+    /**
+     * Get all session data
+     */
+    all(): SessionData;
+    /**
+     * Check if session has been modified
+     */
+    isDirty(): boolean;
+    /**
+     * Get data to persist (including flash for next request)
+     * @internal
+     */
+    toPersist(): SessionData;
+    /**
+     * Regenerate session ID (prevents session fixation)
+     * @internal Returns new ID
+     */
+    regenerateId(): string;
+    static generateId(): string;
+}
+export declare class MemorySessionStore implements SessionStore {
+    private sessions;
+    private oldSessionIds;
+    read(id: string): Promise<SessionData | null>;
+    write(id: string, data: SessionData, ttl: number): Promise<void>;
+    destroy(id: string): Promise<void>;
+    gc(maxLifetime: number): Promise<void>;
+    /**
+     * Mark a session ID as old/invalidated (used when a session is regenerated)
+     * @internal
+     */
+    markOldSessionId(id: string): void;
+}
+export declare class DatabaseSessionStore implements SessionStore {
+    private tableName;
+    private connectionName?;
+    private tableEnsured;
+    constructor(tableName?: string, connectionName?: string | undefined);
+    private ensureTable;
+    read(id: string): Promise<SessionData | null>;
+    write(id: string, data: SessionData, ttl: number): Promise<void>;
+    destroy(id: string): Promise<void>;
+    gc(maxLifetime: number): Promise<void>;
+}
+export declare class FileSessionStore implements SessionStore {
+    private dir;
+    constructor(directory?: string);
+    private filePath;
+    private ensureDir;
+    read(id: string): Promise<SessionData | null>;
+    write(id: string, data: SessionData, ttl: number): Promise<void>;
+    destroy(id: string): Promise<void>;
+    gc(_maxLifetime: number): Promise<void>;
+}
+export declare class RedisSessionStore implements SessionStore {
+    private redis;
+    private prefix;
+    constructor(options?: {
+        client?: any;
+        prefix?: string;
+        url?: string;
+    });
+    private _url?;
+    private _connecting?;
+    private getClient;
+    read(id: string): Promise<SessionData | null>;
+    write(id: string, data: SessionData, ttl: number): Promise<void>;
+    destroy(id: string): Promise<void>;
+    gc(_maxLifetime: number): Promise<void>;
+}
+import { Middleware, type MiddlewareContext, type NextFunction } from '../middleware/Middleware.js';
+export declare class SessionMiddleware extends Middleware {
+    private config;
+    constructor(userConfig: SessionConfig);
+    handle(ctx: MiddlewareContext, next: NextFunction): Promise<Response | void>;
+    private getSessionIdFromCookie;
+    private signId;
+    private verifySignedId;
+    private buildCookieString;
+}

package/dist/session/index.d.ts

@@ -0,0 +1 @@
+export { Session, SessionMiddleware, MemorySessionStore, DatabaseSessionStore, FileSessionStore, RedisSessionStore, type SessionStore, type SessionConfig, type SessionData, } from './Session.js';

package/dist/session/index.js

@@ -0,0 +1,16 @@
+var A=Object.defineProperty;var N=(c,e)=>()=>(c&&(e=c(c=0)),e);var E=(c,e)=>{for(var t in e)A(c,t,{get:e[t],enumerable:!0})};function T(c,e){let t=Symbol.for(c),s=globalThis;return s[t]||(s[t]=e()),s[t]}var D=N(()=>{"use strict"});var h={};E(h,{Connection:()=>M});var v,M,p=N(()=>{"use strict";D();v=class{connections=new Map;config=null;defaultName="default";configure(e){this.config=e,this.defaultName=e.default}async connection(e){let t=e??this.defaultName;if(this.connections.has(t))return this.connections.get(t).drizzle;if(!this.config)throw new Error("Database not configured. Call Connection.configure() first, or register DatabaseServiceProvider.");let s=this.config.connections[t];if(!s)throw new Error(`Database connection "${t}" is not defined in configuration.`);let n=await this.createConnection(s);return this.connections.set(t,n),n.drizzle}async rawClient(e){let t=e??this.defaultName;return await this.connection(t),this.connections.get(t).rawClient}async raw(e,t=[],s){let n=await this.connection(s),i=this.getConfig(s);switch(i.driver){case"sqlite":{let r=await this.rawClient(s),a=t.map(l=>typeof l=="boolean"?l?1:0:l instanceof Date?l.toISOString():l),o=r.prepare(e),d=e.trimStart().toUpperCase();return d.startsWith("SELECT")||d.startsWith("PRAGMA")||d.startsWith("WITH")?o.all(...a):o.run(...a)}case"postgres":return(await this.rawClient(s))(e,...t);case"mysql":{let r=await this.rawClient(s),[a]=await r.execute(e,t);return a}default:throw new Error(`Unsupported driver: ${i.driver}`)}}getDriver(e){return this.getConfig(e).driver}getConfig(e){let t=e??this.defaultName;if(!this.config)throw new Error("Database not configured.");let s=this.config.connections[t];if(!s)throw new Error(`Database connection "${t}" is not defined.`);return s}async disconnect(e){if(e){let t=this.connections.get(e);t&&(await this.closeConnection(t),this.connections.delete(e))}else{for(let[t,s]of this.connections)await this.closeConnection(s);this.connections.clear()}}isConnected(e){return this.connections.has(e??this.defaultName)}async transaction(e,t){let s=this.getConfig(t),n=await this.rawClient(t);switch(s.driver){case"sqlite":{n.exec("BEGIN");try{let i=await e();return n.exec("COMMIT"),i}catch(i){throw n.exec("ROLLBACK"),i}}case"postgres":{await n`BEGIN`;try{let i=await e();return await n`COMMIT`,i}catch(i){throw await n`ROLLBACK`,i}}case"mysql":{let i=await n.getConnection();await i.beginTransaction();try{let r=await e();return await i.commit(),i.release(),r}catch(r){throw await i.rollback(),i.release(),r}}default:throw new Error(`Unsupported driver: ${s.driver}`)}}async createConnection(e){switch(e.driver){case"sqlite":return this.createSQLiteConnection(e);case"postgres":return this.createPostgresConnection(e);case"mysql":return this.createMySQLConnection(e);default:throw new Error(`Unsupported database driver: ${e.driver}`)}}async createSQLiteConnection(e){let t=e.filename??e.database??":memory:";try{let s=(await import("better-sqlite3")).default,{drizzle:n}=await import("drizzle-orm/better-sqlite3"),i=new s(t);return i.pragma("journal_mode = WAL"),i.pragma("foreign_keys = ON"),{drizzle:n(i),config:e,rawClient:i}}catch(s){let n;try{n=(await new Function("mod","return import(mod)")("node:sqlite")).DatabaseSync}catch{throw new Error(`No SQLite driver available. Install better-sqlite3 (npm install better-sqlite3) or use Node.js v22+ which includes built-in SQLite support. Original error: ${s instanceof Error?s.message:String(s)}`)}let i=new n(t);i.exec("PRAGMA journal_mode = WAL"),i.exec("PRAGMA foreign_keys = ON");let r={prepare(o){let d=i.prepare(o);return{all(...l){return d.all(...l)},run(...l){return d.run(...l)},get(...l){return d.get(...l)}}},exec(o){i.exec(o)},pragma(o){return i.prepare(`PRAGMA ${o}`).all()},close(){i.close()}},a;try{let{drizzle:o}=await import("drizzle-orm/better-sqlite3");a=o(r)}catch{a=r}return{drizzle:a,config:e,rawClient:r}}}async createPostgresConnection(e){let t=(await import("postgres")).default,{drizzle:s}=await import("drizzle-orm/postgres-js"),n=e.url??`postgres://${e.user}:${e.password}@${e.host??"localhost"}:${e.port??5432}/${e.database}`,i=t(n);return{drizzle:s(i),config:e,rawClient:i}}async createMySQLConnection(e){let t=await import("mysql2/promise"),{drizzle:s}=await import("drizzle-orm/mysql2"),n=t.createPool({host:e.host??"localhost",port:e.port??3306,database:e.database,user:e.user,password:e.password,uri:e.url});return{drizzle:s(n),config:e,rawClient:n}}async closeConnection(e){try{switch(e.config.driver){case"sqlite":e.rawClient.close();break;case"postgres":await e.rawClient.end();break;case"mysql":await e.rawClient.end();break}}catch{}}},M=T("svelar.connection",()=>new v)});import{randomBytes as R,createHmac as P,timingSafeEqual as O}from"crypto";import{promises as u}from"fs";import{join as g}from"path";var w=class{};var f=class c{constructor(e,t){this.id=e;t&&(this.data={...t},this.data._flash&&(this.previousFlashData=this.data._flash,delete this.data._flash))}data={};dirty=!1;flashData={};previousFlashData={};get(e,t){return e in this.flashData?this.flashData[e]:e in this.previousFlashData?this.previousFlashData[e]:e in this.data?this.data[e]:t}set(e,t){this.data[e]=t,this.dirty=!0}has(e){return e in this.data||e in this.flashData||e in this.previousFlashData}forget(e){delete this.data[e],this.dirty=!0}flush(){this.data={},this.dirty=!0}flash(e,t){this.flashData[e]=t,this.dirty=!0}all(){return{...this.data,...this.previousFlashData,...this.flashData}}isDirty(){return this.dirty||Object.keys(this.flashData).length>0}toPersist(){let e={...this.data};return Object.keys(this.flashData).length>0&&(e._flash=this.flashData),e}regenerateId(){let e=this.id,t=c.generateId();this.id=t,this.dirty=!0;let s=m.get(e);return s instanceof y&&s.markOldSessionId(e),m.delete(e),t}static generateId(){return R(32).toString("hex")}},m=new Map,y=class{sessions=new Map;oldSessionIds=new Set;async read(e){if(this.oldSessionIds.has(e))return null;let t=this.sessions.get(e);return t?Date.now()>t.expiresAt?(this.sessions.delete(e),null):t.data:null}async write(e,t,s){this.sessions.set(e,{data:t,expiresAt:Date.now()+s*1e3}),m.set(e,this)}async destroy(e){this.sessions.delete(e),m.delete(e)}async gc(e){let t=Date.now();for(let[s,n]of this.sessions)t>n.expiresAt&&(this.sessions.delete(s),m.delete(s))}markOldSessionId(e){this.oldSessionIds.add(e),this.sessions.delete(e)}},S=class{constructor(e="sessions",t){this.tableName=e;this.connectionName=t}tableEnsured=!1;async ensureTable(){if(!this.tableEnsured)try{let{Connection:e}=await Promise.resolve().then(()=>(p(),h));switch(e.getDriver(this.connectionName)){case"sqlite":await e.raw(`CREATE TABLE IF NOT EXISTS ${this.tableName} (
+              id TEXT PRIMARY KEY,
+              payload TEXT NOT NULL,
+              expires_at TEXT NOT NULL
+            )`,[],this.connectionName);break;case"postgres":await e.raw(`CREATE TABLE IF NOT EXISTS ${this.tableName} (
+              id VARCHAR(255) PRIMARY KEY,
+              payload TEXT NOT NULL,
+              expires_at TIMESTAMPTZ NOT NULL
+            )`,[],this.connectionName);break;case"mysql":await e.raw(`CREATE TABLE IF NOT EXISTS ${this.tableName} (
+              id VARCHAR(255) PRIMARY KEY,
+              payload TEXT NOT NULL,
+              expires_at DATETIME NOT NULL
+            ) ENGINE=InnoDB`,[],this.connectionName);break}this.tableEnsured=!0}catch{}}async read(e){await this.ensureTable();let{Connection:t}=await Promise.resolve().then(()=>(p(),h)),s=await t.raw(`SELECT payload, expires_at FROM ${this.tableName} WHERE id = ?`,[e],this.connectionName);if(s.length===0)return null;let n=s[0];if(new Date(n.expires_at)<new Date)return await this.destroy(e),null;try{return JSON.parse(n.payload)}catch{return null}}async write(e,t,s){await this.ensureTable();let{Connection:n}=await Promise.resolve().then(()=>(p(),h)),i=JSON.stringify(t),r=new Date(Date.now()+s*1e3).toISOString(),a=n.getDriver(this.connectionName);a==="sqlite"?await n.raw(`INSERT INTO ${this.tableName} (id, payload, expires_at) VALUES (?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET payload = excluded.payload, expires_at = excluded.expires_at`,[e,i,r],this.connectionName):a==="postgres"?await n.raw(`INSERT INTO ${this.tableName} (id, payload, expires_at) VALUES ($1, $2, $3)
+         ON CONFLICT(id) DO UPDATE SET payload = $2, expires_at = $3`,[e,i,r],this.connectionName):await n.raw(`INSERT INTO ${this.tableName} (id, payload, expires_at) VALUES (?, ?, ?)
+         ON DUPLICATE KEY UPDATE payload = VALUES(payload), expires_at = VALUES(expires_at)`,[e,i,r],this.connectionName)}async destroy(e){let{Connection:t}=await Promise.resolve().then(()=>(p(),h));await t.raw(`DELETE FROM ${this.tableName} WHERE id = ?`,[e],this.connectionName)}async gc(e){let{Connection:t}=await Promise.resolve().then(()=>(p(),h));await t.raw(`DELETE FROM ${this.tableName} WHERE expires_at < ?`,[new Date().toISOString()],this.connectionName)}},C=class{dir;constructor(e){this.dir=e??g(process.cwd(),"storage","sessions")}filePath(e){let t=e.replace(/[^a-zA-Z0-9_-]/g,"");return g(this.dir,`${t}.json`)}async ensureDir(){await u.mkdir(this.dir,{recursive:!0})}async read(e){try{let t=await u.readFile(this.filePath(e),"utf-8"),s=JSON.parse(t);return new Date(s.expiresAt)<new Date?(await this.destroy(e),null):s.data}catch{return null}}async write(e,t,s){await this.ensureDir();let n={data:t,expiresAt:new Date(Date.now()+s*1e3).toISOString()};await u.writeFile(this.filePath(e),JSON.stringify(n),"utf-8")}async destroy(e){try{await u.unlink(this.filePath(e))}catch{}}async gc(e){try{let t=await u.readdir(this.dir),s=new Date;for(let n of t)if(n.endsWith(".json"))try{let i=await u.readFile(g(this.dir,n),"utf-8"),r=JSON.parse(i);new Date(r.expiresAt)<s&&await u.unlink(g(this.dir,n))}catch{await u.unlink(g(this.dir,n)).catch(()=>{})}}catch{}}},x=class{redis;prefix;constructor(e){this.prefix=e?.prefix??"svelar_session:",e?.client?this.redis=e.client:this._url=e?.url}_url;_connecting;async getClient(){return this.redis?this.redis:(this._connecting||(this._connecting=(async()=>{try{let{default:e}=await import("ioredis");return this.redis=this._url?new e(this._url):new e,this.redis}catch{throw new Error('RedisSessionStore requires "ioredis" package. Install it: npm install ioredis')}})()),this._connecting)}async read(e){let s=await(await this.getClient()).get(this.prefix+e);if(!s)return null;try{return JSON.parse(s)}catch{return null}}async write(e,t,s){await(await this.getClient()).set(this.prefix+e,JSON.stringify(t),"EX",s)}async destroy(e){await(await this.getClient()).del(this.prefix+e)}async gc(e){}},b=class extends w{config;constructor(e){super(),this.config={cookieName:"svelar_session",lifetime:7200,secret:process.env.APP_KEY??(()=>{throw new Error("APP_KEY is not set. Set it in your .env file before using sessions.")})(),path:"/",domain:"",secure:process.env.NODE_ENV==="production",httpOnly:!0,sameSite:"lax",...e}}async handle(e,t){let s=e.event.request.headers.get("cookie")??"",n=this.getSessionIdFromCookie(s),i=null;if(n){let o=this.verifySignedId(n);o?(i=await this.config.store.read(o),n=o):n=null}n||(n=f.generateId());let r=new f(n,i??{});e.event.locals.session=r,e.locals.session=r;let a=await t();if(r.isDirty()&&await this.config.store.write(r.id,r.toPersist(),this.config.lifetime),a instanceof Response){let o=this.signId(r.id),d=this.buildCookieString(o);a.headers.append("Set-Cookie",d)}return a}getSessionIdFromCookie(e){let t=e.split(";").map(s=>s.trim());for(let s of t){let[n,...i]=s.split("=");if(n===this.config.cookieName)return decodeURIComponent(i.join("="))}return null}signId(e){let t=P("sha256",this.config.secret).update(e).digest("base64url");return`${e}.${t}`}verifySignedId(e){let t=e.lastIndexOf(".");if(t===-1)return null;let s=e.slice(0,t),n=e.slice(t+1),i=P("sha256",this.config.secret).update(s).digest("base64url");if(n.length!==i.length)return null;let r=Buffer.from(n),a=Buffer.from(i);if(r.length!==a.length)return null;try{if(O(r,a))return s}catch{}return null}buildCookieString(e){let t=[`${this.config.cookieName}=${encodeURIComponent(e)}`];return t.push(`Path=${this.config.path}`),t.push(`Max-Age=${this.config.lifetime}`),this.config.domain&&t.push(`Domain=${this.config.domain}`),this.config.secure&&t.push("Secure"),this.config.httpOnly&&t.push("HttpOnly"),t.push(`SameSite=${this.config.sameSite}`),t.join("; ")}};export{S as DatabaseSessionStore,C as FileSessionStore,y as MemorySessionStore,x as RedisSessionStore,f as Session,b as SessionMiddleware};

package/dist/storage/index.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Svelar Storage / Filesystem
+ *
+ * Laravel-inspired filesystem abstraction with local and S3-compatible drivers.
+ *
+ * @example
+ * ```ts
+ * import { Storage } from 'svelar/storage';
+ *
+ * // Configure
+ * Storage.configure({
+ *   default: 'local',
+ *   disks: {
+ *     local: { driver: 'local', root: './storage' },
+ *     public: { driver: 'local', root: './storage/public', urlPrefix: '/storage' },
+ *   },
+ * });
+ *
+ * // Usage
+ * await Storage.put('avatars/user-1.png', buffer);
+ * const content = await Storage.get('avatars/user-1.png');
+ * const exists = await Storage.exists('avatars/user-1.png');
+ * await Storage.delete('avatars/user-1.png');
+ * const files = await Storage.files('avatars');
+ * ```
+ */
+export type StorageDriver = 'local' | 's3';
+export interface DiskConfig {
+    driver: StorageDriver;
+    /** Root path for local driver */
+    root?: string;
+    /** URL prefix for public files */
+    urlPrefix?: string;
+    /** S3 / RustFS configuration */
+    bucket?: string;
+    region?: string;
+    /** S3-compatible endpoint URL (e.g. http://rustfs:9000 for RustFS/MinIO) */
+    endpoint?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    /** Force path-style addressing (required for RustFS/MinIO, default: true) */
+    forcePathStyle?: boolean;
+    /** Optional prefix/directory within the bucket */
+    prefix?: string;
+}
+export interface StorageConfig {
+    default: string;
+    disks: Record<string, DiskConfig>;
+}
+export interface FileInfo {
+    path: string;
+    name: string;
+    extension: string;
+    size: number;
+    lastModified: Date;
+}
+interface Disk {
+    get(path: string): Promise<Buffer>;
+    getText(path: string): Promise<string>;
+    put(path: string, content: string | Buffer): Promise<void>;
+    append(path: string, content: string | Buffer): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<boolean>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    files(directory?: string): Promise<string[]>;
+    allFiles(directory?: string): Promise<string[]>;
+    directories(directory?: string): Promise<string[]>;
+    makeDirectory(path: string): Promise<void>;
+    deleteDirectory(path: string): Promise<void>;
+    size(path: string): Promise<number>;
+    lastModified(path: string): Promise<Date>;
+    url(path: string): string;
+}
+/**
+ * S3-compatible storage disk using @aws-sdk/client-s3.
+ * Works with RustFS, MinIO, AWS S3, and any S3-compatible service.
+ * Requires: npm install @aws-sdk/client-s3 (peer dependency, loaded dynamically)
+ */
+declare class S3Disk implements Disk {
+    private config;
+    private _client;
+    private _s3Module;
+    constructor(config: DiskConfig);
+    private getS3;
+    private getClient;
+    private key;
+    get(path: string): Promise<Buffer>;
+    getText(path: string): Promise<string>;
+    put(path: string, content: string | Buffer): Promise<void>;
+    append(path: string, content: string | Buffer): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<boolean>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    files(directory?: string): Promise<string[]>;
+    allFiles(directory?: string): Promise<string[]>;
+    directories(directory?: string): Promise<string[]>;
+    makeDirectory(_path: string): Promise<void>;
+    deleteDirectory(path: string): Promise<void>;
+    size(path: string): Promise<number>;
+    lastModified(path: string): Promise<Date>;
+    url(path: string): string;
+    /**
+     * Generate a pre-signed URL for temporary access to a file.
+     * Requires: npm install @aws-sdk/s3-request-presigner
+     */
+    temporaryUrl(path: string, expiresInSeconds?: number): Promise<string>;
+    /**
+     * Ensure the bucket exists, creating it if not.
+     * Useful for initial setup with RustFS/MinIO.
+     */
+    ensureBucket(): Promise<void>;
+}
+declare class StorageManager {
+    private config;
+    private disks;
+    /**
+     * Configure the storage manager
+     */
+    configure(config: StorageConfig): void;
+    /**
+     * Get a disk instance by name (or default)
+     */
+    disk(name?: string): Disk;
+    get(path: string): Promise<Buffer>;
+    getText(path: string): Promise<string>;
+    put(path: string, content: string | Buffer): Promise<void>;
+    append(path: string, content: string | Buffer): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<boolean>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    files(directory?: string): Promise<string[]>;
+    allFiles(directory?: string): Promise<string[]>;
+    directories(directory?: string): Promise<string[]>;
+    makeDirectory(path: string): Promise<void>;
+    deleteDirectory(path: string): Promise<void>;
+    size(path: string): Promise<number>;
+    lastModified(path: string): Promise<Date>;
+    url(path: string): string;
+    private createDisk;
+    /**
+     * Get the S3 disk instance with extended S3 methods (temporaryUrl, ensureBucket).
+     * Throws if the named disk is not an S3 disk.
+     */
+    s3Disk(name?: string): S3Disk;
+}
+/**
+ * Global Storage singleton
+ */
+export declare const Storage: StorageManager;
+export type { Disk, StorageManager };
+export { S3Disk };

package/dist/storage/index.js

@@ -0,0 +1 @@
+import{readFile as w,writeFile as P,unlink as v,mkdir as a,readdir as f,stat as k,copyFile as b,rename as C}from"fs/promises";import{existsSync as x}from"fs";import{join as D,dirname as g}from"path";function p(c,t){let e=Symbol.for(c),i=globalThis;return i[e]||(i[e]=t()),i[e]}var h=class{constructor(t){this.config=t;if(!t.root)throw new Error('Local disk requires a "root" path.')}resolve(t){return D(this.config.root,t)}async get(t){return w(this.resolve(t))}async getText(t){return w(this.resolve(t),"utf-8")}async put(t,e){let i=this.resolve(t);await a(g(i),{recursive:!0}),await P(i,e)}async append(t,e){let{appendFile:i}=await import("fs/promises"),s=this.resolve(t);await a(g(s),{recursive:!0}),await i(s,e)}async exists(t){return x(this.resolve(t))}async delete(t){try{return await v(this.resolve(t)),!0}catch{return!1}}async copy(t,e){let i=this.resolve(e);await a(g(i),{recursive:!0}),await b(this.resolve(t),i)}async move(t,e){let i=this.resolve(e);await a(g(i),{recursive:!0}),await C(this.resolve(t),i)}async files(t=""){let e=this.resolve(t);try{return(await f(e,{withFileTypes:!0})).filter(s=>s.isFile()).map(s=>t?`${t}/${s.name}`:s.name)}catch{return[]}}async allFiles(t=""){let e=[],i=this.resolve(t);try{let s=await f(i,{withFileTypes:!0});for(let n of s){let r=t?`${t}/${n.name}`:n.name;n.isFile()?e.push(r):n.isDirectory()&&e.push(...await this.allFiles(r))}}catch{}return e}async directories(t=""){let e=this.resolve(t);try{return(await f(e,{withFileTypes:!0})).filter(s=>s.isDirectory()).map(s=>t?`${t}/${s.name}`:s.name)}catch{return[]}}async makeDirectory(t){await a(this.resolve(t),{recursive:!0})}async deleteDirectory(t){let{rm:e}=await import("fs/promises");await e(this.resolve(t),{recursive:!0,force:!0})}async size(t){return(await k(this.resolve(t))).size}async lastModified(t){return(await k(this.resolve(t))).mtime}url(t){return`${this.config.urlPrefix??""}/${t}`}},l=class{config;_client=null;_s3Module=null;constructor(t){if(!t.bucket)throw new Error('S3 disk requires a "bucket" name.');this.config=t}async getS3(){if(this._s3Module)return this._s3Module;try{return this._s3Module=await Function('return import("@aws-sdk/client-s3")')(),this._s3Module}catch{throw new Error("S3 storage driver requires @aws-sdk/client-s3. Install it with: npm install @aws-sdk/client-s3")}}async getClient(){if(this._client)return this._client;let t=await this.getS3();return this._client=new t.S3Client({region:this.config.region??"us-east-1",endpoint:this.config.endpoint,forcePathStyle:this.config.forcePathStyle??!0,credentials:{accessKeyId:this.config.accessKeyId??"",secretAccessKey:this.config.secretAccessKey??""}}),this._client}key(t){let e=this.config.prefix;return e?`${e}/${t}`:t}async get(t){let e=await this.getS3(),n=await(await(await this.getClient()).send(new e.GetObjectCommand({Bucket:this.config.bucket,Key:this.key(t)}))).Body.transformToByteArray();return Buffer.from(n)}async getText(t){return(await this.get(t)).toString("utf-8")}async put(t,e){let i=await this.getS3(),s=await this.getClient(),n=typeof e=="string"?Buffer.from(e,"utf-8"):e;await s.send(new i.PutObjectCommand({Bucket:this.config.bucket,Key:this.key(t),Body:n}))}async append(t,e){let i=null;try{i=await this.get(t)}catch{}let s=typeof e=="string"?Buffer.from(e,"utf-8"):e,n=i?Buffer.concat([i,s]):s;await this.put(t,n)}async exists(t){let e=await this.getS3(),i=await this.getClient();try{return await i.send(new e.HeadObjectCommand({Bucket:this.config.bucket,Key:this.key(t)})),!0}catch{return!1}}async delete(t){let e=await this.getS3(),i=await this.getClient();try{return await i.send(new e.DeleteObjectCommand({Bucket:this.config.bucket,Key:this.key(t)})),!0}catch{return!1}}async copy(t,e){let i=await this.getS3();await(await this.getClient()).send(new i.CopyObjectCommand({Bucket:this.config.bucket,CopySource:`${this.config.bucket}/${this.key(t)}`,Key:this.key(e)}))}async move(t,e){await this.copy(t,e),await this.delete(t)}async files(t=""){let e=await this.getS3(),i=await this.getClient(),s=this.key(t?`${t}/`:"");try{return((await i.send(new e.ListObjectsV2Command({Bucket:this.config.bucket,Prefix:s,Delimiter:"/"}))).Contents??[]).map(r=>r.Key).filter(r=>r!==s).map(r=>{let o=this.config.prefix;return o?r.slice(o.length+1):r})}catch{return[]}}async allFiles(t=""){let e=await this.getS3(),i=await this.getClient(),s=this.key(t?`${t}/`:""),n=[],r;do{let o=await i.send(new e.ListObjectsV2Command({Bucket:this.config.bucket,Prefix:s,ContinuationToken:r}));for(let u of o.Contents??[]){let m=this.config.prefix,y=m?u.Key.slice(m.length+1):u.Key;y&&n.push(y)}r=o.IsTruncated?o.NextContinuationToken:void 0}while(r);return n}async directories(t=""){let e=await this.getS3(),i=await this.getClient(),s=this.key(t?`${t}/`:"");try{return((await i.send(new e.ListObjectsV2Command({Bucket:this.config.bucket,Prefix:s,Delimiter:"/"}))).CommonPrefixes??[]).map(r=>{let o=this.config.prefix;return(o?r.Prefix.slice(o.length+1):r.Prefix).replace(/\/$/,"")}).filter(r=>r.length>0)}catch{return[]}}async makeDirectory(t){}async deleteDirectory(t){let e=await this.allFiles(t);for(let i of e)await this.delete(i)}async size(t){let e=await this.getS3();return(await(await this.getClient()).send(new e.HeadObjectCommand({Bucket:this.config.bucket,Key:this.key(t)}))).ContentLength??0}async lastModified(t){let e=await this.getS3();return(await(await this.getClient()).send(new e.HeadObjectCommand({Bucket:this.config.bucket,Key:this.key(t)}))).LastModified??new Date}url(t){let e=this.config.urlPrefix;if(e)return`${e}/${t}`;let i=this.config.endpoint??`https://s3.${this.config.region??"us-east-1"}.amazonaws.com`;return this.config.forcePathStyle!==!1?`${i}/${this.config.bucket}/${this.key(t)}`:`${i.replace("://",`://${this.config.bucket}.`)}/${this.key(t)}`}async temporaryUrl(t,e=3600){try{let i=await Function('return import("@aws-sdk/s3-request-presigner")')(),s=await this.getS3(),n=await this.getClient(),r=new s.GetObjectCommand({Bucket:this.config.bucket,Key:this.key(t)});return await i.getSignedUrl(n,r,{expiresIn:e})}catch{throw new Error("Pre-signed URLs require @aws-sdk/s3-request-presigner. Install it with: npm install @aws-sdk/s3-request-presigner")}}async ensureBucket(){let t=await this.getS3(),e=await this.getClient();try{await e.send(new t.HeadBucketCommand({Bucket:this.config.bucket}))}catch{await e.send(new t.CreateBucketCommand({Bucket:this.config.bucket}))}}},d=class{config=null;disks=new Map;configure(t){this.config=t}disk(t){let e=t??this.config?.default??"local";if(this.disks.has(e))return this.disks.get(e);if(!this.config)throw new Error("Storage not configured. Call Storage.configure() first.");let i=this.config.disks[e];if(!i)throw new Error(`Storage disk "${e}" is not defined.`);let s=this.createDisk(i);return this.disks.set(e,s),s}async get(t){return this.disk().get(t)}async getText(t){return this.disk().getText(t)}async put(t,e){return this.disk().put(t,e)}async append(t,e){return this.disk().append(t,e)}async exists(t){return this.disk().exists(t)}async delete(t){return this.disk().delete(t)}async copy(t,e){return this.disk().copy(t,e)}async move(t,e){return this.disk().move(t,e)}async files(t){return this.disk().files(t)}async allFiles(t){return this.disk().allFiles(t)}async directories(t){return this.disk().directories(t)}async makeDirectory(t){return this.disk().makeDirectory(t)}async deleteDirectory(t){return this.disk().deleteDirectory(t)}async size(t){return this.disk().size(t)}async lastModified(t){return this.disk().lastModified(t)}url(t){return this.disk().url(t)}createDisk(t){switch(t.driver){case"local":return new h(t);case"s3":return new l(t);default:throw new Error(`Unknown storage driver: ${t.driver}`)}}s3Disk(t){let e=this.disk(t);if(!(e instanceof l))throw new Error(`Disk "${t??this.config?.default}" is not an S3 disk.`);return e}},M=p("svelar.storage",()=>new d);export{l as S3Disk,M as Storage};

package/dist/support/Pipeline.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Svelar Pipeline
+ *
+ * Laravel-inspired Pipeline (Chain of Responsibility pattern).
+ * Passes data through a sequence of pipes, where each pipe can
+ * transform, validate, or halt the data before passing it on.
+ *
+ * @example
+ * ```ts
+ * const result = await Pipeline.send(order)
+ *   .through([
+ *     ValidateStock,
+ *     ApplyDiscount,
+ *     CalculateTax,
+ *     ChargePayment,
+ *   ])
+ *   .thenReturn();
+ * ```
+ */
+/**
+ * A pipe can be:
+ * - A class with a handle(data, next) method
+ * - An inline function (data, next) => result
+ */
+export type PipeFunction<T> = (passable: T, next: (passable: T) => Promise<T>) => Promise<T> | T;
+export interface Pipe<T> {
+    handle(passable: T, next: (passable: T) => Promise<T>): Promise<T> | T;
+}
+export type PipeEntry<T> = (new () => Pipe<T>) | PipeFunction<T>;
+export declare class Pipeline<T> {
+    private passable;
+    private pipes;
+    private onCatchFn?;
+    /**
+     * Set the data being sent through the pipeline.
+     */
+    static send<T>(passable: T): Pipeline<T>;
+    /**
+     * Set the pipes to process.
+     */
+    through(pipes: PipeEntry<T>[]): this;
+    /**
+     * Add a single pipe to the pipeline.
+     */
+    pipe(pipe: PipeEntry<T>): this;
+    /**
+     * Set an error handler for the pipeline.
+     * If a pipe throws, this handler receives the error and current passable,
+     * and can return a recovery value or re-throw.
+     */
+    onCatch(handler: (error: Error, passable: T) => Promise<T> | T): this;
+    /**
+     * Run the pipeline and return the final result.
+     */
+    thenReturn(): Promise<T>;
+    /**
+     * Run the pipeline with a final destination callback.
+     */
+    then<R>(destination: (passable: T) => Promise<R> | R): Promise<R>;
+    /**
+     * Execute the pipeline.
+     */
+    private run;
+    private isPipeClass;
+}

package/dist/support/date.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Svelar Date Utilities
+ *
+ * Timezone-safe date formatting, parsing, and relative time helpers.
+ * Built on date-fns to avoid the classic "off by one day" bug where
+ * `new Date('2024-01-15')` parses as UTC midnight and displays as
+ * January 14th in negative UTC offset timezones.
+ *
+ * @example
+ * ```ts
+ * import { formatDate, formatRelative, parseLocalDate, toLocal } from 'svelar/dates';
+ *
+ * // Safe date formatting (locale-aware)
+ * formatDate(user.createdAt);                    // "Mar 27, 2026"
+ * formatDate(user.createdAt, 'PPpp');            // "Mar 27, 2026, 2:30 PM"
+ * formatDate(user.createdAt, 'PP', { locale: pt }); // "27 de mar. de 2026"
+ *
+ * // Relative time
+ * formatRelative(Date.now() - 3600000);          // "about 1 hour ago"
+ *
+ * // Parse date-only strings safely (as LOCAL, not UTC)
+ * parseLocalDate('2024-01-15');                   // Jan 15 00:00 LOCAL time
+ *
+ * // Convert any Date/timestamp to local-safe Date
+ * toLocal(someUtcDate);
+ * ```
+ */
+import { format as fnsFormat, isValid, parseISO, differenceInDays, differenceInHours, differenceInMinutes, differenceInSeconds, startOfDay, endOfDay, isToday, isYesterday, isTomorrow, addDays, addHours, addMinutes, subDays, subHours, subMinutes, type Locale } from 'date-fns';
+export type { Locale };
+export interface FormatOptions {
+    /** date-fns locale object (e.g. import { pt } from 'date-fns/locale') */
+    locale?: Locale;
+}
+export type DateInput = Date | number | string;
+/**
+ * Normalize any date input to a safe Date object.
+ *
+ * - Numbers (timestamps) → `new Date(ts)` (correct, timestamps are always UTC)
+ * - Date objects → returned as-is
+ * - ISO strings with time component → `parseISO()` (handles timezone offset)
+ * - Date-only strings like '2024-01-15' → parsed as LOCAL date to avoid
+ *   the off-by-one-day bug (JS natively parses these as UTC midnight)
+ */
+export declare function toDate(input: DateInput): Date;
+/**
+ * Parse a date-only string (e.g. '2024-01-15') as LOCAL midnight.
+ *
+ * The native `new Date('2024-01-15')` parses as UTC midnight, which causes
+ * the infamous off-by-one-day bug in negative UTC offset timezones.
+ * This function explicitly constructs the date from year/month/day parts
+ * using the local timezone.
+ */
+export declare function parseLocalDate(dateStr: string): Date;
+/**
+ * Ensure a date is treated as local midnight (strips time component).
+ * Useful when comparing dates without time (e.g. "is this the same day?").
+ */
+export declare function toLocal(input: DateInput): Date;
+/**
+ * Format a date with a date-fns pattern. Defaults to 'PP' (locale-aware medium date).
+ *
+ * Common patterns:
+ * - 'PP'    → "Mar 27, 2026"
+ * - 'PPP'   → "March 27th, 2026"
+ * - 'PPpp'  → "Mar 27, 2026, 2:30:00 PM"
+ * - 'p'     → "2:30 PM"
+ * - 'Pp'    → "Mar 27, 2026, 2:30 PM"
+ * - 'yyyy-MM-dd' → "2026-03-27"
+ *
+ * @see https://date-fns.org/docs/format
+ */
+export declare function formatDate(input: DateInput, pattern?: string, options?: FormatOptions): string;
+/**
+ * Format a date as relative time from now (e.g. "about 2 hours ago", "in 3 days").
+ * Uses `formatDistanceToNow` with `addSuffix: true`.
+ */
+export declare function formatRelative(input: DateInput, options?: FormatOptions): string;
+/**
+ * Format a short relative time without suffix (e.g. "2h", "3d", "5m").
+ * Useful for compact UI like tables and badges.
+ */
+export declare function formatShortRelative(input: DateInput): string;
+/**
+ * Format the distance between two dates (e.g. "about 2 hours").
+ */
+export declare function formatBetween(start: DateInput, end: DateInput, options?: FormatOptions): string;
+/**
+ * Return a human-readable "time ago" string. Alias for `formatRelative`.
+ * Inspired by Laravel's Carbon `diffForHumans()`.
+ *
+ * @example
+ * timeAgo(user.createdAt)  // "about 2 hours ago"
+ * timeAgo(post.publishedAt, { locale: pt })  // "cerca de 2 horas atrás"
+ */
+export declare function timeAgo(input: DateInput, options?: FormatOptions): string;
+/**
+ * Cast date fields on a model-like object. Converts raw timestamps/strings
+ * to timezone-safe Date objects and adds a `.timeAgo()` method.
+ *
+ * Server stores UTC → UI always shows in the user's local timezone.
+ *
+ * @example
+ * ```ts
+ * // In a server load function
+ * const user = await db.query.users.findFirst({ where: eq(users.id, id) });
+ *
+ * return {
+ *   user: castDates(user, ['createdAt', 'updatedAt', 'lastLoginAt'])
+ * };
+ *
+ * // In the template
+ * user.createdAt          // Date object (local timezone)
+ * user.createdAt_ago      // "about 2 hours ago"
+ * user.createdAt_short    // "2h"
+ * user.createdAt_formatted // "Mar 27, 2026"
+ * ```
+ */
+export declare function castDates<T extends Record<string, any>>(obj: T, dateFields: (keyof T)[], options?: FormatOptions): T & Record<string, any>;
+/**
+ * Create a reusable date caster for a specific set of fields.
+ * Useful when you cast the same fields on every request.
+ *
+ * @example
+ * ```ts
+ * // Define once
+ * const castUserDates = dateCaster(['createdAt', 'updatedAt', 'lastLoginAt']);
+ *
+ * // Use in load functions
+ * return { user: castUserDates(user) };
+ * ```
+ */
+export declare function dateCaster<K extends string>(fields: K[]): <T extends Record<string, any>>(obj: T, options?: FormatOptions) => T & Record<string, any>;
+export { isToday, isYesterday, isTomorrow, isValid };
+export { differenceInDays, differenceInHours, differenceInMinutes, differenceInSeconds, };
+export { startOfDay, endOfDay, addDays, addHours, addMinutes, subDays, subHours, subMinutes, };
+export { parseISO, fnsFormat as format };

package/dist/support/date.js

@@ -0,0 +1 @@
+import{format as p,formatDistanceToNow as m,formatDistance as D,isValid as d,parseISO as y,differenceInDays as M,differenceInHours as O,differenceInMinutes as T,differenceInSeconds as F,startOfDay as _,endOfDay as b,isToday as S,isYesterday as L,isTomorrow as R,addDays as v,addHours as P,addMinutes as k,subDays as H,subHours as E,subMinutes as K}from"date-fns";import{enUS as c}from"date-fns/locale";function s(t){if(t instanceof Date)return t;if(typeof t=="number")return new Date(t);if(typeof t=="string"){let e=t.trim();if(/^\d{4}-\d{2}-\d{2}$/.test(e))return x(e);let r=y(e);if(d(r))return r;let o=new Date(e);if(d(o))return o;throw new Error(`Invalid date string: "${t}"`)}throw new Error(`Invalid date input: ${t}`)}function x(t){let[e,r,o]=t.split("-").map(Number);return new Date(e,r-1,o)}function Y(t){let e=s(t);return new Date(e.getFullYear(),e.getMonth(),e.getDate())}function g(t,e="PP",r){let o=s(t);return p(o,e,{locale:r?.locale??c})}function l(t,e){let r=s(t);return m(r,{addSuffix:!0,locale:e?.locale??c})}function h(t){let e=s(t),r=Date.now(),o=Math.abs(r-e.getTime()),i=Math.floor(o/1e3);if(i<60)return`${i}s`;let f=Math.floor(o/6e4);if(f<60)return`${f}m`;let a=Math.floor(o/36e5);if(a<24)return`${a}h`;let n=Math.floor(o/864e5);if(n<30)return`${n}d`;let u=Math.floor(n/30);return u<12?`${u}mo`:`${Math.floor(n/365)}y`}function A(t,e,r){return D(s(t),s(e),{locale:r?.locale??c})}function B(t,e){return l(t,e)}function I(t,e,r){let o={...t};for(let i of e){let f=t[i];if(f==null)continue;let a=String(i),n=s(f);o[a]=n,o[`${a}_ago`]=l(n,r),o[`${a}_short`]=h(n),o[`${a}_formatted`]=g(n,"PP",r)}return o}function C(t){return(e,r)=>I(e,t,r)}export{v as addDays,P as addHours,k as addMinutes,I as castDates,C as dateCaster,M as differenceInDays,O as differenceInHours,T as differenceInMinutes,F as differenceInSeconds,b as endOfDay,p as format,A as formatBetween,g as formatDate,l as formatRelative,h as formatShortRelative,S as isToday,R as isTomorrow,d as isValid,L as isYesterday,y as parseISO,x as parseLocalDate,_ as startOfDay,H as subDays,E as subHours,K as subMinutes,B as timeAgo,s as toDate,Y as toLocal};

package/dist/support/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Svelar Support Utilities
+ *
+ * Helpers for UUIDv7, ULID, and other common operations.
+ */
+export { uuidv7, ulid, isUuidv7, isUlid, uuidv7Timestamp, ulidTimestamp } from './uuid.js';
+export { singleton } from './singleton.js';
+export { Pipeline, type Pipe, type PipeFunction, type PipeEntry } from './Pipeline.js';

package/dist/support/index.js

@@ -0,0 +1 @@
+import{randomBytes as p}from"crypto";function u(){let s=Date.now(),e=Buffer.alloc(6);e.writeUIntBE(s,0,6);let t=p(10),n=Buffer.alloc(16);e.copy(n,0),n[6]=112|t[0]&15,n[7]=t[1],n[8]=128|t[2]&63,n[9]=t[3],n[10]=t[4],n[11]=t[5],n[12]=t[6],n[13]=t[7],n[14]=t[8],n[15]=t[9];let r=n.toString("hex");return[r.slice(0,8),r.slice(8,12),r.slice(12,16),r.slice(16,20),r.slice(20,32)].join("-")}var a="0123456789ABCDEFGHJKMNPQRSTVWXYZ";function l(){let s=Date.now(),e="",t=s;for(let i=0;i<10;i++)e=a[t&31]+e,t=Math.floor(t/32);let n=p(10),r="";for(let i=0;i<10;i++)r+=a[n[i]&31];let o=p(6);for(let i=0;i<6;i++)r+=a[o[i]&31];return e+r}function T(s){return/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(s)}function f(s){return/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(s)}function h(s){let e=s.replace(/-/g,"").slice(0,12),t=parseInt(e,16);return new Date(t)}function P(s){let e=s.slice(0,10),t=0;for(let n of e)t=t*32+a.indexOf(n.toUpperCase());return new Date(t)}function m(s,e){let t=Symbol.for(s),n=globalThis;return n[t]||(n[t]=e()),n[t]}var c=class s{passable;pipes=[];onCatchFn;static send(e){let t=new s;return t.passable=e,t}through(e){return this.pipes=e,this}pipe(e){return this.pipes.push(e),this}onCatch(e){return this.onCatchFn=e,this}async thenReturn(){return this.run(e=>e)}async then(e){return this.run(e)}async run(e){let t=async n=>e(n);for(let n=this.pipes.length-1;n>=0;n--){let r=this.pipes[n],o=t;t=async i=>this.isPipeClass(r)?new r().handle(i,o):r(i,o)}try{return await t(this.passable)}catch(n){if(this.onCatchFn)return await this.onCatchFn(n,this.passable);throw n}}isPipeClass(e){return typeof e=="function"&&e.prototype&&typeof e.prototype.handle=="function"}};export{c as Pipeline,f as isUlid,T as isUuidv7,m as singleton,l as ulid,P as ulidTimestamp,u as uuidv7,h as uuidv7Timestamp};

package/dist/support/singleton.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Cross-bundle singleton helper.
+ *
+ * tsup bundles each entry point independently, duplicating module-scoped variables.
+ * This means `export const Foo = new FooManager()` produces a separate instance in
+ * every bundle that imports the file. Using `Symbol.for()` on `globalThis` ensures
+ * only one instance exists per key across the entire process, regardless of how many
+ * bundles reference it.
+ */
+export declare function singleton<T>(key: string, factory: () => T): T;

package/dist/support/uuid.d.ts

@@ -0,0 +1,40 @@
+/**
+ * UUIDv7 & ULID generators
+ *
+ * UUIDv7 (RFC 9562) embeds a Unix timestamp in the first 48 bits,
+ * making IDs time-sortable while remaining globally unique.
+ *
+ * ULID (Universally Unique Lexicographically Sortable Identifier)
+ * is a 26-character Crockford Base32 string with 48-bit timestamp + 80 random bits.
+ */
+/**
+ * Generate a UUIDv7 (time-ordered UUID per RFC 9562).
+ *
+ * Layout (128 bits):
+ *   48-bit unix_ts_ms | 4-bit version (0111) | 12-bit rand_a
+ *   2-bit variant (10) | 62-bit rand_b
+ */
+export declare function uuidv7(): string;
+/**
+ * Generate a ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * 26 characters: 10-char timestamp (48-bit ms) + 16-char randomness (80-bit).
+ * Crockford Base32 encoded, naturally sortable by creation time.
+ */
+export declare function ulid(): string;
+/**
+ * Check if a string is a valid UUIDv7.
+ */
+export declare function isUuidv7(value: string): boolean;
+/**
+ * Check if a string is a valid ULID.
+ */
+export declare function isUlid(value: string): boolean;
+/**
+ * Extract the timestamp from a UUIDv7.
+ */
+export declare function uuidv7Timestamp(uuid: string): Date;
+/**
+ * Extract the timestamp from a ULID.
+ */
+export declare function ulidTimestamp(id: string): Date;