@cequrebackends/cequre-ts 0.11.4

package/dist/interface-map.d.ts

@@ -0,0 +1,175 @@
+/**
+ * ============================================================================
+ * CEQURE UNIVERSAL ADAPTER CONTRACT (INTERFACE MAP)
+ * ============================================================================
+ *
+ * Architectural Context:
+ * Cequre is designed using a strict "Ports and Adapters" (Hexagonal) architecture.
+ * Because 95% of Cequre's logic (AST parsing, TypeBox validation, ORM mapping,
+ * SDK generation, Auth flows, and Hooks) is pure, platform-agnostic TypeScript,
+ * it can execute natively on any modern JavaScript runtime.
+ *
+ * However, the remaining 5% of the framework physically touches the underlying
+ * Operating System or Infrastructure boundaries (I/O). Examples include:
+ * - Local File Systems vs Cloud Buckets (Storage)
+ * - Persistent Daemons vs Serverless Webhooks (Queues and Cron)
+ * - Raw TCP Sockets vs Stateless Functions (Realtime WebSockets)
+ * - Native bindings vs WebCrypto (Password Hashing)
+ *
+ * Purpose of this File:
+ * This file explicitly defines the 10 interfaces that represent those physical I/O boundaries.
+ * The core Cequre framework MUST NEVER directly invoke Bun, Node, Vercel, or Deno APIs.
+ * It ONLY programs against the generic contracts defined in this file.
+ *
+ * Building an Adapter:
+ * For Cequre to compile and run on a new deployment platform (e.g., Vercel Serverless or Node.js),
+ * a developer only needs to write a thin "Platform Adapter" that implements these 10 interfaces.
+ * At build time, the Cequre CLI (Compiler) uses Dependency Injection and bundler path-aliasing
+ * to hot-swap these abstract interfaces with the concrete, platform-specific implementations.
+ *
+ * TL;DR for AI/LLMs:
+ * If you are reading this file to port Cequre to a new runtime environment, your ONLY job
+ * is to write classes that satisfy the 10 interfaces below using the native APIs of your
+ * target environment, and register them with the Dependency Injector.
+ */
+export interface UploadedFile {
+    filename: string;
+    originalName: string;
+    mimetype: string;
+    size: number;
+    url: string;
+}
+export interface StorageProvider {
+    /** Save a file to the platform's storage medium */
+    saveFile(file: File, options?: {
+        filename?: string;
+    }): Promise<UploadedFile>;
+    /** Delete a file by its reference filename/path */
+    deleteFile(filename: string): Promise<void>;
+    /** Optional: S3/Blob specific Multipart uploads for massive files */
+    initMultipartUpload?(options: {
+        filename: string;
+        mimetype: string;
+        size: number;
+    }): Promise<{
+        uploadId: string;
+        filename: string;
+        parts?: {
+            partNumber: number;
+            url: string;
+        }[];
+    }>;
+    completeMultipartUpload?(uploadId: string, filename: string, parts: {
+        partNumber: number;
+        etag?: string;
+    }[]): Promise<UploadedFile>;
+}
+export interface PaginatedResult<T = Record<string, unknown>> {
+    docs: T[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+export interface CequreAdapter {
+    readonly adapterType: string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<void>;
+    find(collection: string, query: Record<string, any>): Promise<PaginatedResult>;
+    findById(collection: string, id: string): Promise<Record<string, unknown> | null>;
+    create(collection: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    update(collection: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    delete(collection: string, id: string): Promise<void>;
+    count(collection: string, query?: Record<string, any>): Promise<number>;
+    createTableDDL?(table: unknown): string;
+    dropTableDDL?(table: string): string;
+    raw?(sql: string, params?: unknown[]): Promise<unknown>;
+}
+export interface CacheStore {
+    get(key: string): Promise<any | null>;
+    set(key: string, value: any, ttlSeconds?: number): Promise<void>;
+    del(...keys: string[]): Promise<number>;
+    close(): void;
+}
+export interface CequreEmailSendOptions {
+    from?: string;
+    to?: string;
+    cc?: string;
+    bcc?: string;
+    replyTo?: string;
+    subject?: string;
+    text?: string;
+    html?: string;
+}
+export interface CequreEmailTransport {
+    send(options: CequreEmailSendOptions): Promise<{
+        messageId: string;
+    }>;
+    verify(): Promise<boolean>;
+}
+export interface CryptoProvider {
+    /** Hash a plaintext password */
+    hash(plaintext: string): Promise<string>;
+    /** Verify a plaintext password against a hash */
+    verify(plaintext: string, hash: string): Promise<boolean>;
+    /** Generate a cryptographically secure random token */
+    generateRandomToken(length: number): string;
+}
+export interface CronJobConfig {
+    /** Standard cron expression (e.g. "0 0 * * *") */
+    schedule: string;
+    /** The function to execute */
+    handler: () => void | Promise<void>;
+}
+export interface CronProvider {
+    /** Register a job with the underlying platform's scheduler */
+    registerJob(name: string, config: CronJobConfig): void;
+    /** Start/Initialize the scheduler if required by the platform */
+    start(): void;
+}
+export interface RealtimeProvider {
+    /** Publish a message to a specific topic/channel */
+    publish(topic: string, data: any): void;
+    /** Broadcast a message to all connected clients */
+    broadcast(data: any): void;
+    /** Handle an incoming Upgrade request from the HTTP layer */
+    upgrade(req: Request): boolean | Promise<boolean>;
+}
+export interface QueueJob<T = any> {
+    id: string;
+    name: string;
+    data: T;
+    timestamp: number;
+}
+export interface QueueProvider {
+    /** Enqueue a new job to be processed */
+    enqueue<T>(queueName: string, jobName: string, data: T, options?: any): Promise<string>;
+    /** Register a worker to process jobs from a specific queue */
+    registerWorker<T>(queueName: string, handler: (job: QueueJob<T>) => Promise<void>): void;
+    /** Start processing jobs (used by persistent platforms, ignored by serverless webhook queues) */
+    startWorkers(): void;
+}
+export interface CequreServerConfig {
+    port?: number;
+    hostname?: string;
+    /** The universal fetch handler generated by the Cequre Router */
+    fetch: (req: Request) => Promise<Response> | Response;
+}
+export interface ServerProvider {
+    /**
+     * Starts the server on persistent platforms (Bun/Node).
+     * On Serverless platforms (Vercel), this may simply export the fetch handler.
+     */
+    start(config: CequreServerConfig): void | any;
+    /** Stop the server gracefully */
+    stop?(): Promise<void>;
+}
+export interface LoggerProvider {
+    info(message: string, meta?: Record<string, any>): void;
+    warn(message: string, meta?: Record<string, any>): void;
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+    debug(message: string, meta?: Record<string, any>): void;
+}

package/dist/shared/core/adapter.d.ts

@@ -0,0 +1,84 @@
+export type ConstraintType = "foreign_key" | "unique" | "not_null" | "check" | "exclusion";
+export interface ParsedConstraintError {
+    type: ConstraintType;
+    table?: string;
+    column?: string;
+    constraint?: string;
+    referencedTable?: string;
+    referencedColumn?: string;
+    rawMessage: string;
+}
+export interface CequreAdapter {
+    readonly adapterType: string;
+    name?: string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    transaction?<R>(callback: (trxAdapter: CequreAdapter) => Promise<R>): Promise<R>;
+    ping(): Promise<void>;
+    configureCollections?(collections: any[]): void | Promise<void>;
+    getStartupInfo?(): {
+        createdResourceName?: string | null;
+    };
+    getSystemTableStatements?(): string[];
+    getCurrentSchema?(): Promise<{
+        tables: string[];
+        columns: Record<string, string[]>;
+    }>;
+    recordMigration?(version: string, description: string): Promise<void>;
+    getCurrentMigrationVersion?(): Promise<string | null>;
+    parseConstraintError?(error: unknown): ParsedConstraintError | null;
+    createTableDDL?(table: unknown): string;
+    renameColumnDDL?(table: string, oldName: string, newName: string, column?: unknown): string;
+    addColumnDDL?(table: string, column: unknown): string | null;
+    dropColumnDDL?(table: string, column: string): string;
+    dropTableDDL?(table: string): string;
+    supportsGeneratedConstraintSQL?: boolean;
+    find(collection: string, query: QueryArgs<any>): Promise<PaginatedResult>;
+    findById(collection: string, id: string): Promise<Record<string, unknown> | null>;
+    findByIds?(collection: string, ids: string[]): Promise<Record<string, unknown>[]>;
+    create(collection: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    createMany?(collection: string, docs: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;
+    update(collection: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    delete(collection: string, id: string): Promise<void>;
+    deleteMany?(collection: string, ids: string[]): Promise<void>;
+    count(collection: string, query?: Pick<QueryArgs<any>, "where">): Promise<number>;
+    raw?(sql: string, params?: unknown[]): Promise<unknown>;
+}
+export type FilterOperators<T> = {
+    eq?: T;
+    neq?: T;
+    gt?: T;
+    gte?: T;
+    lt?: T;
+    lte?: T;
+    in?: T[];
+    nin?: T[];
+    like?: string;
+    nlike?: string;
+    contains?: string;
+    startsWith?: string;
+    endsWith?: string;
+    mode?: "sensitive" | "insensitive" | "default";
+};
+export type WhereClause<T> = {
+    [P in keyof T]?: T[P] | FilterOperators<T[P]>;
+} & {
+    OR?: WhereClause<T>[];
+    AND?: WhereClause<T>[];
+};
+export interface QueryArgs<T = any> {
+    where?: WhereClause<T>;
+    sort?: string;
+    limit?: number;
+    page?: number;
+    depth?: number;
+}
+export interface PaginatedResult<T = Record<string, unknown>> {
+    docs: T[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}

package/dist/shared/core/base-sql-adapter.d.ts

@@ -0,0 +1,34 @@
+import type { CequreAdapter, ParsedConstraintError } from "./adapter";
+import type { CollectionConfig as Collection } from "./types";
+/**
+ * Base abstract class for SQL adapters (Postgres, SQLite, Turso)
+ * Encapsulates shared registry logic for fields, collections, and constraint error parsing.
+ */
+export declare abstract class BaseSqlAdapter implements CequreAdapter {
+    abstract readonly adapterType: string;
+    abstract readonly supportsGeneratedConstraintSQL?: boolean;
+    protected _createdDbName: string | null;
+    protected _numericFields: Map<string, Set<string>>;
+    protected _jsonFields: Map<string, Set<string>>;
+    protected _relationshipTargets: Map<string, string>;
+    protected _searchableFields: Map<string, Set<string>>;
+    protected _knownFields: Map<string, Set<string>>;
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract ping(): Promise<void>;
+    abstract find(collection: string, query: any): Promise<any>;
+    abstract findById(collection: string, id: string): Promise<any>;
+    abstract create(collection: string, data: any): Promise<any>;
+    abstract update(collection: string, id: string, data: any): Promise<any>;
+    abstract delete(collection: string, id: string): Promise<void>;
+    abstract count(collection: string, query?: any): Promise<number>;
+    get createdDbName(): string | null;
+    getStartupInfo(): {
+        createdResourceName?: string | null;
+    };
+    configureCollections(collections: Collection[]): void;
+    registerCollections(collections: Collection[]): void;
+    parseConstraintError(error: unknown): ParsedConstraintError | null;
+}
+export declare function sqlIdentifier(identifier: string): string;
+export declare function sqlLiteral(value: string): string;

package/dist/shared/core/cache.d.ts

@@ -0,0 +1,8 @@
+import type { CacheStore } from './types';
+export declare class MemoryCacheStore implements CacheStore {
+    private cache;
+    get(key: string): Promise<any | null>;
+    set(key: string, value: any, ttlSeconds?: number): Promise<void>;
+    del(...keys: string[]): Promise<number>;
+    close(): void;
+}

package/dist/shared/core/email.d.ts

@@ -0,0 +1,53 @@
+import type { EmailConfig, CequreEmailSendOptions, CequreEmailTransport } from "./types";
+export type { CequreEmailSendOptions, CequreEmailTransport };
+export declare class CequreMailer {
+    private transport;
+    private appName;
+    private resetTokenExpiryMinutes;
+    private from;
+    private templates?;
+    constructor(config?: EmailConfig, transport?: CequreEmailTransport);
+    send(options: CequreEmailSendOptions): Promise<{
+        messageId: string;
+    }>;
+    verify(): Promise<boolean>;
+    /**
+     * Sends a welcome / registration confirmation email.
+     */
+    sendWelcome(to: string, opts?: {
+        appName?: string;
+    }): Promise<void>;
+    /**
+     * Sends a password-reset email containing a one-time token link.
+     *
+     * @param to        - Recipient email address
+     * @param resetUrl  - Full reset URL including the token,
+     *                    e.g. https://myapp.com/reset-password?token=abc123
+     * @param opts      - Optional overrides
+     */
+    sendForgotPassword(to: string, resetUrl: string, opts?: {
+        appName?: string;
+        expiresInMinutes?: number;
+    }): Promise<void>;
+    /**
+     * Sends a confirmation email after a password has been successfully reset.
+     */
+    sendPasswordResetSuccess(to: string, opts?: {
+        appName?: string;
+    }): Promise<void>;
+    /**
+     * Sends a verification email with a one-time link.
+     *
+     * @param to        - Recipient email address
+     * @param verifyUrl - Full verification URL including the token,
+     *                    e.g. https://myapp.com/verify-email?token=abc123
+     * @param opts      - Optional overrides
+     */
+    sendVerificationEmail(to: string, verifyUrl: string, opts?: {
+        appName?: string;
+    }): Promise<void>;
+}
+/**
+ * Creates a CequreMailer instance from optional config + env vars.
+ */
+export declare function createMailer(config?: EmailConfig): CequreMailer | undefined;

package/dist/shared/core/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./types";
+export * from "./adapter";
+export * from "./base-sql-adapter";
+export * from "./cache";
+export * from "./email";
+export * from "./openapi";
+export * from "./plugins";
+export * from "./request";
+export * from "./sdk";
+export * from "./ulid";
+export * from "./validator";
+export * from "./stream";

package/dist/shared/core/index.js

@@ -0,0 +1,47 @@
+// @bun
+import {
+  BaseSqlAdapter,
+  CequreMailer,
+  MemoryCacheStore,
+  MemoryStreamStore,
+  buildCollectionCreateSchema,
+  buildCollectionUpdateSchema,
+  createMailer,
+  createRouteContext,
+  generateBackendSchemas,
+  generateOpenAPISpec,
+  generateScalarHTML,
+  generateSharedModels,
+  generateTypeScriptClientSDK,
+  parseQuery,
+  sortPlugins,
+  sqlIdentifier,
+  sqlLiteral,
+  validateCreate,
+  validateUpdate
+} from "../../index-kyvy0s1x.js";
+import {
+  ulid
+} from "../../index-17yswtmg.js";
+export {
+  validateUpdate,
+  validateCreate,
+  ulid,
+  sqlLiteral,
+  sqlIdentifier,
+  sortPlugins,
+  parseQuery,
+  generateTypeScriptClientSDK,
+  generateSharedModels,
+  generateScalarHTML,
+  generateOpenAPISpec,
+  generateBackendSchemas,
+  createRouteContext,
+  createMailer,
+  buildCollectionUpdateSchema,
+  buildCollectionCreateSchema,
+  MemoryStreamStore,
+  MemoryCacheStore,
+  CequreMailer,
+  BaseSqlAdapter
+};

package/dist/shared/core/openapi.d.ts

@@ -0,0 +1,24 @@
+import type { CequreAST } from "./types";
+export type OpenAPIRouteDetail = Record<string, unknown> & {
+    description?: string;
+    summary?: string;
+    tags?: string[];
+};
+export type OpenAPIRouteHooks = Record<string, unknown> & {
+    body?: unknown;
+    detail?: OpenAPIRouteDetail;
+    query?: unknown;
+    response?: unknown;
+    tags?: string[];
+};
+export type OpenAPIRoute = {
+    hooks?: OpenAPIRouteHooks;
+    options?: OpenAPIRouteHooks;
+    method?: string;
+    path?: string;
+};
+export type OpenAPIRouteApp = {
+    routes?: Iterable<OpenAPIRoute>;
+};
+export declare function generateScalarHTML(specUrl: string, title?: string): string;
+export declare function generateOpenAPISpec(schema: CequreAST, serverUrl: string, prefix: string, app?: OpenAPIRouteApp, includeHidden?: boolean): any;

package/dist/shared/core/plugins.d.ts

@@ -0,0 +1,2 @@
+import type { CequrePlugin } from "./types";
+export declare function sortPlugins(plugins: CequrePlugin[]): CequrePlugin[];

package/dist/shared/core/request.d.ts

@@ -0,0 +1,32 @@
+import type { AuthUser } from "../main/access";
+import type { CequreRuntime } from "../../shared/main/runtime";
+export type CequreQuery = Record<string, any>;
+export type CequreParams = Record<string, string>;
+export type ExtractAuthUser<TCollections> = TCollections extends {
+    __auth: infer A;
+} ? (A extends AuthUser ? A : AuthUser) : AuthUser;
+export interface CequreRouteContext<TCollections extends Record<string, any> = any, TState = unknown, TParams = CequreParams, TQuery = CequreQuery, TBody = unknown> {
+    request: Request;
+    url: URL;
+    params: TParams;
+    query: TQuery;
+    body?: TBody;
+    user: ExtractAuthUser<TCollections> | null;
+    cequre: CequreRuntime<TCollections>;
+    state?: TState;
+    /**
+     * Streams a chunk of data to the client instantly.
+     * Calling this will automatically hijack the response and keep the connection open.
+     */
+    /** Internal method to stream data immediately. Do not use directly unless you know what you are doing. */
+    stream: (chunk: string | Uint8Array | Record<string, any>, options?: {
+        delay?: number;
+        event?: string;
+    }) => Promise<void>;
+    /** Internal streaming state (do not use) */
+    _streamInitiated?: boolean;
+    _streamWriter?: WritableStreamDefaultWriter<any>;
+    _streamResolver?: (res: Response) => void;
+}
+export declare function parseQuery(searchParams: URLSearchParams): CequreQuery;
+export declare function createRouteContext<TCollections extends Record<string, any>, TState, TParams = CequreParams, TQuery = CequreQuery, TBody = unknown>(request: Request, params?: TParams, state?: TState, user?: ExtractAuthUser<TCollections> | null, body?: TBody, cequre?: CequreRuntime<TCollections>): CequreRouteContext<TCollections, TState, TParams, TQuery, TBody>;

package/dist/shared/core/sdk.d.ts

@@ -0,0 +1,3 @@
+export declare function generateSharedModels(schema: any, routes?: any[]): string;
+export declare function generateTypeScriptClientSDK(schema: any, routes?: any[]): string;
+export declare function generateBackendSchemas(schema: any, routes?: any[]): string;

package/dist/shared/core/stream.d.ts

@@ -0,0 +1,24 @@
+export interface StreamEvent {
+    id: string;
+    collection: string;
+    action: string;
+    data: Record<string, any>;
+    timestamp: number;
+}
+export interface DurableStreamStore {
+    publish(collection: string, action: string, data: Record<string, any>): Promise<string>;
+    read(collection: string, lastEventId?: string): Promise<StreamEvent[]>;
+}
+/**
+ * In-memory implementation of DurableStreamStore.
+ * [Development Only] This uses a local array ring buffer.
+ * It does not scale across multiple servers and loses data on restart.
+ * Use @cequrebackends/cequre-plugin-durable-streams for production.
+ */
+export declare class MemoryStreamStore implements DurableStreamStore {
+    private streams;
+    private maxCapacity;
+    constructor(maxCapacity?: number);
+    publish(collection: string, action: string, data: Record<string, any>): Promise<string>;
+    read(collection: string, lastEventId?: string): Promise<StreamEvent[]>;
+}