@boltstore/utils 0.5.0

package/README.md

@@ -0,0 +1,61 @@
+# @boltstore/shared
+
+Shared TypeScript types, validation, and utilities for Boltstore. Zero dependencies. Tree-shakeable.
+
+## Installation
+
+```bash
+npm install @boltstore/shared
+```
+
+## Usage
+
+### Tree-shakeable imports (recommended)
+
+```ts
+// Only auth types are bundled
+import { JwtPayload, ApiKeyClaims } from "@boltstore/shared/auth-types";
+
+// Only validation functions are bundled
+import { validateField, validateRecord } from "@boltstore/shared/validation";
+
+// Only filter parser is bundled
+import { parseFilter, parseQuery } from "@boltstore/shared/filter";
+
+// Only sync types
+import { VersionVector, MergeResult } from "@boltstore/shared/sync-types";
+
+// Only constants
+import { ErrorCodes, Limits } from "@boltstore/shared/constants";
+```
+
+### Convenience barrel (imports everything)
+
+```ts
+import {
+  JwtPayload,
+  MergeResult,
+  validateField,
+  parseFilter,
+  ErrorCodes,
+} from "@boltstore/shared";
+```
+
+## Exports
+
+| Entrypoint              | Contents                                           |
+|-------------------------|----------------------------------------------------|
+| `@boltstore/shared`     | Barrel (all exports)                               |
+| `./types`               | Record, Collection, User, Application, ApiKey types |
+| `./validation`          | Field validators (email, url, required, etc.)       |
+| `./filter`              | Filter expression parser & SQL compiler             |
+| `./sync-types`          | Sync protocol types (VersionVector, LamportClock)   |
+| `./realtime-types`      | Realtime/WebSocket message types                    |
+| `./auth-types`          | JWT, OAuth2, API key types                          |
+| `./storage-types`       | File storage types (FileInfo, S3Config)             |
+| `./constants`           | Error codes, limits, defaults                       |
+| `./schema`              | JSON Schema exports for cross-language SDKs         |
+
+## License
+
+MIT

package/dist/auth-types.d.ts

@@ -0,0 +1,138 @@
+import type { UserRole, ApiKeyScope } from "./types";
+export interface JwtHeader {
+    alg: "HS256";
+    typ: "JWT";
+}
+export interface JwtPayload {
+    /** Subject — user ID */
+    sub: string;
+    /** Issuer — always "boltstore" */
+    iss: string;
+    /** Audience — the application ID (or "system" for admin tokens) */
+    aud: string;
+    /** Issued at (Unix timestamp) */
+    iat: number;
+    /** Expiration (Unix timestamp) */
+    exp: number;
+    /** User role — default "user" for end users, custom roles allowed */
+    role: UserRole;
+    /** User email */
+    email?: string;
+    /** Application ID this token is scoped to */
+    application: string;
+    /** Token type */
+    type: "access" | "refresh";
+    /** Unique token ID (jti) */
+    jti: string;
+    /** Whether this is an admin token or a user token */
+    userType: "admin" | "user";
+}
+export interface RefreshToken {
+    id: string;
+    userId: string;
+    /** SHA-256 hash of the token */
+    tokenHash: string;
+    applicationId: string;
+    expiresAt: string;
+    createdAt: string;
+    /** Track token family for rotation detection */
+    family: string;
+    /** Incremented on each rotation */
+    rotationCount: number;
+    /** "admin" or "user" — determines which table to validate against */
+    userType: "admin" | "user";
+}
+export interface ApiKeyClaims {
+    /** API key record ID */
+    sub: string;
+    /** "apikey" */
+    type: "apikey";
+    scope: ApiKeyScope;
+    applicationId: string;
+    /** API key name (for audit logging) */
+    name: string;
+}
+export interface AuthResult {
+    type: "jwt" | "apikey";
+    /** Authenticated user ID (for JWT auth) */
+    userId?: string;
+    /** JWT claims */
+    jwt?: JwtPayload;
+    /** API key claims */
+    apiKey?: ApiKeyClaims;
+}
+export interface LoginRequest {
+    email: string;
+    password: string;
+    /** Duration in seconds for the session */
+    sessionDuration?: number;
+}
+export interface LoginResponse {
+    accessToken: string;
+    refreshToken: string;
+    user: {
+        id: string;
+        email: string;
+        role: UserRole;
+        name?: string;
+    };
+    expiresAt: number;
+}
+export interface RegisterRequest {
+    email: string;
+    password: string;
+    passwordConfirm: string;
+    name?: string;
+}
+export interface RefreshRequest {
+    refreshToken: string;
+}
+export interface RefreshResponse {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+export type OAuth2Provider = "google" | "github";
+export interface OAuth2Config {
+    provider: OAuth2Provider;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    /** URL to the provider's authorization endpoint */
+    authUrl: string;
+    /** URL to the provider's token endpoint */
+    tokenUrl: string;
+    /** URL to the provider's userinfo endpoint */
+    userInfoUrl: string;
+    /** Additional scopes to request */
+    scopes?: string[];
+}
+export interface OAuth2TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+}
+export interface OAuth2UserInfo {
+    id: string;
+    email: string;
+    name?: string;
+    avatar?: string;
+}
+export interface EmailVerification {
+    id: string;
+    userId: string;
+    token: string;
+    expiresAt: string;
+    createdAt: string;
+}
+export interface PasswordReset {
+    id: string;
+    userId: string;
+    token: string;
+    expiresAt: string;
+    createdAt: string;
+    used: boolean;
+}
+//# sourceMappingURL=auth-types.d.ts.map

package/dist/auth-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-types.d.ts","sourceRoot":"","sources":["../src/auth-types.ts"],"names":[],"mappings":"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"}

package/dist/auth-types.js

@@ -0,0 +1,4 @@
+// ── Authentication & Authorization Types ──
+// Shared between server and client.
+export {};
+//# sourceMappingURL=auth-types.js.map

package/dist/auth-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-types.js","sourceRoot":"","sources":["../src/auth-types.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,oCAAoC"}

package/dist/constants.d.ts

@@ -0,0 +1,123 @@
+export declare const ErrorCodes: {
+    readonly UNAUTHORIZED: "unauthorized";
+    readonly FORBIDDEN: "forbidden";
+    readonly TOKEN_EXPIRED: "token_expired";
+    readonly INVALID_TOKEN: "invalid_token";
+    readonly INVALID_CREDENTIALS: "invalid_credentials";
+    readonly EMAIL_NOT_VERIFIED: "email_not_verified";
+    readonly EMAIL_ALREADY_EXISTS: "email_already_exists";
+    readonly COLLECTION_NOT_FOUND: "collection_not_found";
+    readonly RECORD_NOT_FOUND: "record_not_found";
+    readonly VALIDATION_ERROR: "validation_error";
+    readonly DUPLICATE_ENTRY: "duplicate_entry";
+    readonly RLS_FORBIDDEN: "rls_forbidden";
+    readonly RLS_NO_POLICY: "rls_no_policy";
+    readonly FILE_TOO_LARGE: "file_too_large";
+    readonly INVALID_FILE_TYPE: "invalid_file_type";
+    readonly FILE_NOT_FOUND: "file_not_found";
+    readonly STORAGE_ERROR: "storage_error";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly INTERNAL_ERROR: "internal_error";
+    readonly NOT_IMPLEMENTED: "not_implemented";
+    readonly SERVICE_UNAVAILABLE: "service_unavailable";
+    readonly SYNC_CONFLICT: "sync_conflict";
+    readonly SYNC_REJECTED: "sync_rejected";
+    readonly SYNC_CLOCK_SKEW: "sync_clock_skew";
+    readonly APPLICATION_NOT_FOUND: "application_not_found";
+    readonly APPLICATION_LIMIT_REACHED: "application_limit_reached";
+    readonly BACKUP_FAILED: "backup_failed";
+    readonly BACKUP_NOT_FOUND: "backup_not_found";
+    readonly RESTORE_FAILED: "restore_failed";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+export declare const FieldTypes: {
+    readonly TEXT: "text";
+    readonly NUMBER: "number";
+    readonly BOOL: "bool";
+    readonly DATE: "date";
+    readonly JSON: "json";
+    readonly FILE: "file";
+    readonly RELATION: "relation";
+    readonly EMAIL: "email";
+    readonly URL: "url";
+    readonly SELECT: "select";
+};
+export declare const UserRoles: {
+    readonly USER: "user";
+};
+export declare const AdminRoles: {
+    readonly ADMIN: "admin";
+};
+export declare const ApiKeyScopes: {
+    readonly READ_ONLY: "read-only";
+    readonly READ_WRITE: "read-write";
+    readonly ADMIN: "admin";
+};
+export declare const SyncStrategies: {
+    readonly SERVER_WINS: "server-wins";
+    readonly LAST_WRITE_WINS: "last-write-wins";
+    readonly CLIENT_WINS: "client-wins";
+    readonly CUSTOM: "custom";
+};
+export declare const Limits: {
+    /** Maximum records per page */
+    readonly MAX_PER_PAGE: 200;
+    /** Default records per page */
+    readonly DEFAULT_PER_PAGE: 30;
+    /** Maximum filter query length */
+    readonly MAX_FILTER_LENGTH: 1000;
+    /** Maximum collection name length */
+    readonly MAX_COLLECTION_NAME: 64;
+    /** Maximum field name length */
+    readonly MAX_FIELD_NAME: 64;
+    /** Maximum fields per collection */
+    readonly MAX_FIELDS_PER_COLLECTION: 100;
+    /** Maximum file upload size (50MB) */
+    readonly MAX_FILE_SIZE: number;
+    /** Multipart upload threshold (5MB) */
+    readonly MULTIPART_THRESHOLD: number;
+    /** Maximum WebSocket message size (16MB) */
+    readonly MAX_WS_MESSAGE_SIZE: number;
+};
+export declare const Auth: {
+    /** Access token TTL in seconds (15 minutes) */
+    readonly ACCESS_TOKEN_TTL: number;
+    /** Refresh token TTL in seconds (7 days) */
+    readonly REFRESH_TOKEN_TTL: number;
+    /** API key prefix for identification */
+    readonly API_KEY_PREFIX: "bs_";
+    /** bcrypt cost factor */
+    readonly BCRYPT_COST: 12;
+};
+export declare const ServerDefaults: {
+    readonly DEFAULT_PORT: 8090;
+    readonly DEFAULT_HOST: "127.0.0.1";
+    /** Graceful shutdown timeout in ms */
+    readonly SHUTDOWN_TIMEOUT: 10000;
+    /** WebSocket idle timeout in seconds */
+    readonly WS_IDLE_TIMEOUT: 120;
+    /** Rate limit window in seconds */
+    readonly RATE_LIMIT_WINDOW: 60;
+    /** Default rate limit per window */
+    readonly RATE_LIMIT_MAX: 300;
+    /** Backup interval in hours */
+    readonly BACKUP_INTERVAL_HOURS: 6;
+    /** Full backup interval in days */
+    readonly FULL_BACKUP_INTERVAL_DAYS: 1;
+    /** Log retention in days */
+    readonly LOG_RETENTION_DAYS: 30;
+};
+export declare const HttpStatus: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly NO_CONTENT: 204;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly CONFLICT: 409;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_ERROR: 500;
+    readonly SERVICE_UNAVAILABLE: 503;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+Cb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAIrE,eAAO,MAAM,UAAU;;;;;;;;;;;CAWb,CAAC;AAKX,eAAO,MAAM,SAAS;;CAEZ,CAAC;AAIX,eAAO,MAAM,UAAU;;CAEb,CAAC;AAIX,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAIX,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAIX,eAAO,MAAM,MAAM;IACjB,+BAA+B;;IAE/B,+BAA+B;;IAE/B,kCAAkC;;IAElC,qCAAqC;;IAErC,gCAAgC;;IAEhC,oCAAoC;;IAEpC,sCAAsC;;IAEtC,uCAAuC;;IAEvC,4CAA4C;;CAEpC,CAAC;AAIX,eAAO,MAAM,IAAI;IACf,+CAA+C;;IAE/C,4CAA4C;;IAE5C,wCAAwC;;IAExC,yBAAyB;;CAEjB,CAAC;AAIX,eAAO,MAAM,cAAc;;;IAGzB,sCAAsC;;IAEtC,wCAAwC;;IAExC,mCAAmC;;IAEnC,oCAAoC;;IAEpC,+BAA+B;;IAE/B,mCAAmC;;IAEnC,4BAA4B;;CAEpB,CAAC;AAIX,eAAO,MAAM,UAAU;;;;;;;;;;;;CAYb,CAAC"}

package/dist/constants.js

@@ -0,0 +1,144 @@
+// ── Boltstore Constants ──
+// Shared between server and client. Zero dependencies.
+// ── Error Codes ──
+export const ErrorCodes = {
+    // Auth
+    UNAUTHORIZED: "unauthorized",
+    FORBIDDEN: "forbidden",
+    TOKEN_EXPIRED: "token_expired",
+    INVALID_TOKEN: "invalid_token",
+    INVALID_CREDENTIALS: "invalid_credentials",
+    EMAIL_NOT_VERIFIED: "email_not_verified",
+    EMAIL_ALREADY_EXISTS: "email_already_exists",
+    // Collections & Records
+    COLLECTION_NOT_FOUND: "collection_not_found",
+    RECORD_NOT_FOUND: "record_not_found",
+    VALIDATION_ERROR: "validation_error",
+    DUPLICATE_ENTRY: "duplicate_entry",
+    // RLS
+    RLS_FORBIDDEN: "rls_forbidden",
+    RLS_NO_POLICY: "rls_no_policy",
+    // Storage
+    FILE_TOO_LARGE: "file_too_large",
+    INVALID_FILE_TYPE: "invalid_file_type",
+    FILE_NOT_FOUND: "file_not_found",
+    STORAGE_ERROR: "storage_error",
+    // Rate Limiting
+    RATE_LIMITED: "rate_limited",
+    // Server
+    INTERNAL_ERROR: "internal_error",
+    NOT_IMPLEMENTED: "not_implemented",
+    SERVICE_UNAVAILABLE: "service_unavailable",
+    // Sync
+    SYNC_CONFLICT: "sync_conflict",
+    SYNC_REJECTED: "sync_rejected",
+    SYNC_CLOCK_SKEW: "sync_clock_skew",
+    // Application
+    APPLICATION_NOT_FOUND: "application_not_found",
+    APPLICATION_LIMIT_REACHED: "application_limit_reached",
+    // Backup
+    BACKUP_FAILED: "backup_failed",
+    BACKUP_NOT_FOUND: "backup_not_found",
+    RESTORE_FAILED: "restore_failed",
+};
+// ── Field Type Enum ──
+export const FieldTypes = {
+    TEXT: "text",
+    NUMBER: "number",
+    BOOL: "bool",
+    DATE: "date",
+    JSON: "json",
+    FILE: "file",
+    RELATION: "relation",
+    EMAIL: "email",
+    URL: "url",
+    SELECT: "select",
+};
+// ── User Roles ──
+// End-user default role. Developers define custom roles via RLS policies.
+export const UserRoles = {
+    USER: "user",
+};
+// ── Admin Roles ──
+export const AdminRoles = {
+    ADMIN: "admin",
+};
+// ── API Key Scopes ──
+export const ApiKeyScopes = {
+    READ_ONLY: "read-only",
+    READ_WRITE: "read-write",
+    ADMIN: "admin",
+};
+// ── Sync Strategies ──
+export const SyncStrategies = {
+    SERVER_WINS: "server-wins",
+    LAST_WRITE_WINS: "last-write-wins",
+    CLIENT_WINS: "client-wins",
+    CUSTOM: "custom",
+};
+// ── Limits ──
+export const Limits = {
+    /** Maximum records per page */
+    MAX_PER_PAGE: 200,
+    /** Default records per page */
+    DEFAULT_PER_PAGE: 30,
+    /** Maximum filter query length */
+    MAX_FILTER_LENGTH: 1000,
+    /** Maximum collection name length */
+    MAX_COLLECTION_NAME: 64,
+    /** Maximum field name length */
+    MAX_FIELD_NAME: 64,
+    /** Maximum fields per collection */
+    MAX_FIELDS_PER_COLLECTION: 100,
+    /** Maximum file upload size (50MB) */
+    MAX_FILE_SIZE: 50 * 1024 * 1024,
+    /** Multipart upload threshold (5MB) */
+    MULTIPART_THRESHOLD: 5 * 1024 * 1024,
+    /** Maximum WebSocket message size (16MB) */
+    MAX_WS_MESSAGE_SIZE: 16 * 1024 * 1024,
+};
+// ── Auth ──
+export const Auth = {
+    /** Access token TTL in seconds (15 minutes) */
+    ACCESS_TOKEN_TTL: 15 * 60,
+    /** Refresh token TTL in seconds (7 days) */
+    REFRESH_TOKEN_TTL: 7 * 24 * 60 * 60,
+    /** API key prefix for identification */
+    API_KEY_PREFIX: "bs_",
+    /** bcrypt cost factor */
+    BCRYPT_COST: 12,
+};
+// ── Server ──
+export const ServerDefaults = {
+    DEFAULT_PORT: 8090,
+    DEFAULT_HOST: "127.0.0.1",
+    /** Graceful shutdown timeout in ms */
+    SHUTDOWN_TIMEOUT: 10_000,
+    /** WebSocket idle timeout in seconds */
+    WS_IDLE_TIMEOUT: 120,
+    /** Rate limit window in seconds */
+    RATE_LIMIT_WINDOW: 60,
+    /** Default rate limit per window */
+    RATE_LIMIT_MAX: 300,
+    /** Backup interval in hours */
+    BACKUP_INTERVAL_HOURS: 6,
+    /** Full backup interval in days */
+    FULL_BACKUP_INTERVAL_DAYS: 1,
+    /** Log retention in days */
+    LOG_RETENTION_DAYS: 30,
+};
+// ── HTTP Status Codes ──
+export const HttpStatus = {
+    OK: 200,
+    CREATED: 201,
+    NO_CONTENT: 204,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    TOO_MANY_REQUESTS: 429,
+    INTERNAL_ERROR: 500,
+    SERVICE_UNAVAILABLE: 503,
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,uDAAuD;AAEvD,oBAAoB;AAEpB,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO;IACP,YAAY,EAAE,cAAc;IAC5B,SAAS,EAAE,WAAW;IACtB,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAC9B,mBAAmB,EAAE,qBAAqB;IAC1C,kBAAkB,EAAE,oBAAoB;IACxC,oBAAoB,EAAE,sBAAsB;IAE5C,wBAAwB;IACxB,oBAAoB,EAAE,sBAAsB;IAC5C,gBAAgB,EAAE,kBAAkB;IACpC,gBAAgB,EAAE,kBAAkB;IACpC,eAAe,EAAE,iBAAiB;IAElC,MAAM;IACN,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAE9B,UAAU;IACV,cAAc,EAAE,gBAAgB;IAChC,iBAAiB,EAAE,mBAAmB;IACtC,cAAc,EAAE,gBAAgB;IAChC,aAAa,EAAE,eAAe;IAE9B,gBAAgB;IAChB,YAAY,EAAE,cAAc;IAE5B,SAAS;IACT,cAAc,EAAE,gBAAgB;IAChC,eAAe,EAAE,iBAAiB;IAClC,mBAAmB,EAAE,qBAAqB;IAE1C,OAAO;IACP,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAC9B,eAAe,EAAE,iBAAiB;IAElC,cAAc;IACd,qBAAqB,EAAE,uBAAuB;IAC9C,yBAAyB,EAAE,2BAA2B;IAEtD,SAAS;IACT,aAAa,EAAE,eAAe;IAC9B,gBAAgB,EAAE,kBAAkB;IACpC,cAAc,EAAE,gBAAgB;CACxB,CAAC;AAIX,wBAAwB;AAExB,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,QAAQ;CACR,CAAC;AAEX,mBAAmB;AACnB,0EAA0E;AAE1E,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,MAAM;CACJ,CAAC;AAEX,oBAAoB;AAEpB,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,KAAK,EAAE,OAAO;CACN,CAAC;AAEX,uBAAuB;AAEvB,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,SAAS,EAAE,WAAW;IACtB,UAAU,EAAE,YAAY;IACxB,KAAK,EAAE,OAAO;CACN,CAAC;AAEX,wBAAwB;AAExB,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,WAAW,EAAE,aAAa;IAC1B,eAAe,EAAE,iBAAiB;IAClC,WAAW,EAAE,aAAa;IAC1B,MAAM,EAAE,QAAQ;CACR,CAAC;AAEX,eAAe;AAEf,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,+BAA+B;IAC/B,YAAY,EAAE,GAAG;IACjB,+BAA+B;IAC/B,gBAAgB,EAAE,EAAE;IACpB,kCAAkC;IAClC,iBAAiB,EAAE,IAAI;IACvB,qCAAqC;IACrC,mBAAmB,EAAE,EAAE;IACvB,gCAAgC;IAChC,cAAc,EAAE,EAAE;IAClB,oCAAoC;IACpC,yBAAyB,EAAE,GAAG;IAC9B,sCAAsC;IACtC,aAAa,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;IAC/B,uCAAuC;IACvC,mBAAmB,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI;IACpC,4CAA4C;IAC5C,mBAAmB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;CAC7B,CAAC;AAEX,aAAa;AAEb,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,+CAA+C;IAC/C,gBAAgB,EAAE,EAAE,GAAG,EAAE;IACzB,4CAA4C;IAC5C,iBAAiB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;IACnC,wCAAwC;IACxC,cAAc,EAAE,KAAK;IACrB,yBAAyB;IACzB,WAAW,EAAE,EAAE;CACP,CAAC;AAEX,eAAe;AAEf,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,WAAW;IACzB,sCAAsC;IACtC,gBAAgB,EAAE,MAAM;IACxB,wCAAwC;IACxC,eAAe,EAAE,GAAG;IACpB,mCAAmC;IACnC,iBAAiB,EAAE,EAAE;IACrB,oCAAoC;IACpC,cAAc,EAAE,GAAG;IACnB,+BAA+B;IAC/B,qBAAqB,EAAE,CAAC;IACxB,mCAAmC;IACnC,yBAAyB,EAAE,CAAC;IAC5B,4BAA4B;IAC5B,kBAAkB,EAAE,EAAE;CACd,CAAC;AAEX,0BAA0B;AAE1B,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,EAAE,EAAE,GAAG;IACP,OAAO,EAAE,GAAG;IACZ,UAAU,EAAE,GAAG;IACf,WAAW,EAAE,GAAG;IAChB,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,iBAAiB,EAAE,GAAG;IACtB,cAAc,EAAE,GAAG;IACnB,mBAAmB,EAAE,GAAG;CAChB,CAAC"}

package/dist/filter/compiler.d.ts

@@ -0,0 +1,14 @@
+import type { FilterCondition, FilterGroup } from "./types";
+export interface CompiledSQL {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Compile a filter expression into a SQL WHERE clause with parameters.
+ *
+ * @example
+ * filterToSQL(parseFilter("status = 'active'"))
+ * // => { sql: "status = $0", params: ["active"] }
+ */
+export declare function filterToSQL(filter: FilterGroup | FilterCondition | undefined, paramPrefix?: string): CompiledSQL;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/filter/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../src/filter/compiler.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE5D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,WAAW,GAAG,eAAe,GAAG,SAAS,EACjD,WAAW,CAAC,EAAE,MAAM,GACnB,WAAW,CAiFb"}

package/dist/filter/compiler.js

@@ -0,0 +1,93 @@
+// ── Filter → SQL Compiler ──
+// Converts a parsed filter expression tree into a SQL WHERE clause.
+// Uses parameterized queries — callers must handle value binding.
+/**
+ * Compile a filter expression into a SQL WHERE clause with parameters.
+ *
+ * @example
+ * filterToSQL(parseFilter("status = 'active'"))
+ * // => { sql: "status = $0", params: ["active"] }
+ */
+export function filterToSQL(filter, paramPrefix) {
+    if (!filter)
+        return { sql: "1=1", params: [] };
+    const params = [];
+    let counter = 0;
+    const p = () => `${paramPrefix ?? "$"}${counter++}`;
+    function buildCondition(c) {
+        const { field, operator, value } = c;
+        switch (operator) {
+            case "eq": {
+                if (value === null)
+                    return `${field} IS NULL`;
+                params.push(value);
+                return `${field} = ${p()}`;
+            }
+            case "neq": {
+                if (value === null)
+                    return `${field} IS NOT NULL`;
+                params.push(value);
+                return `${field} != ${p()}`;
+            }
+            case "gt":
+                params.push(value);
+                return `${field} > ${p()}`;
+            case "gte":
+                params.push(value);
+                return `${field} >= ${p()}`;
+            case "lt":
+                params.push(value);
+                return `${field} < ${p()}`;
+            case "lte":
+                params.push(value);
+                return `${field} <= ${p()}`;
+            case "like":
+                params.push(value);
+                return `${field} LIKE ${p()}`;
+            case "not_like":
+                params.push(value);
+                return `${field} NOT LIKE ${p()}`;
+            case "in": {
+                const values = Array.isArray(value) ? value : [value];
+                const placeholders = values.map((v, i) => {
+                    params.push(values[i]);
+                    return p();
+                });
+                return `${field} IN (${placeholders.join(", ")})`;
+            }
+            case "not_in": {
+                const values = Array.isArray(value) ? value : [value];
+                const placeholders = values.map((v, i) => {
+                    params.push(values[i]);
+                    return p();
+                });
+                return `${field} NOT IN (${placeholders.join(", ")})`;
+            }
+            default:
+                params.push(value);
+                return `${field} = ${p()}`;
+        }
+    }
+    function buildGroup(g) {
+        if (g.conditions.length === 0)
+            return "1=1";
+        const parts = g.conditions.map((c) => {
+            if ("operator" in c && ("field" in c || "conditions" in c)) {
+                if ("conditions" in c)
+                    return buildGroup(c);
+                return buildCondition(c);
+            }
+            return "1=1";
+        });
+        return `(${parts.join(` ${g.operator.toUpperCase()} `)})`;
+    }
+    let sql;
+    if ("conditions" in filter) {
+        sql = buildGroup(filter);
+    }
+    else {
+        sql = buildCondition(filter);
+    }
+    return { sql, params };
+}
+//# sourceMappingURL=compiler.js.map

package/dist/filter/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../../src/filter/compiler.ts"],"names":[],"mappings":"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"}

package/dist/filter/parser.d.ts

@@ -0,0 +1,15 @@
+import type { FilterGroup } from "./types";
+import type { SortClause } from "./types";
+export declare function parseSort(sortStr: string): SortClause[];
+/**
+ * Parse a filter string into a structured filter expression.
+ *
+ * @example
+ * parseFilter("status = 'active' && priority > 3")
+ * // => { operator: "and", conditions: [
+ * //      { field: "status", operator: "eq", value: "active" },
+ * //      { field: "priority", operator: "gt", value: 3 }
+ * //    ]}
+ */
+export declare function parseFilter(filterStr: string): FilterGroup | undefined;
+//# sourceMappingURL=parser.d.ts.map

package/dist/filter/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/filter/parser.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAmB,WAAW,EAAmB,MAAM,SAAS,CAAC;AA8H7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAYvD;AAID;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAKtE"}