@push.rocks/smartdb 1.0.1

package/ts/ts_smartdb/types/interfaces.ts

@@ -0,0 +1,433 @@
+import type * as plugins from '../plugins.js';
+
+// ============================================================================
+// Document Types
+// ============================================================================
+
+export type Document = Record<string, any>;
+
+export interface WithId<TSchema> {
+  _id: plugins.bson.ObjectId;
+}
+
+// ============================================================================
+// Client Options
+// ============================================================================
+
+export interface ISmartdbClientOptions {
+  /** Storage adapter type: 'memory' or 'file' */
+  storageType?: 'memory' | 'file';
+  /** Path for file-based storage */
+  storagePath?: string;
+  /** Enable persistence for memory adapter */
+  persist?: boolean;
+  /** Path for persistence file when using memory adapter */
+  persistPath?: string;
+}
+
+// ============================================================================
+// Connection String Parsing
+// ============================================================================
+
+export interface IParsedConnectionString {
+  protocol: 'smartdb';
+  storageType: 'memory' | 'file';
+  options: {
+    persist?: string;
+    path?: string;
+  };
+}
+
+// ============================================================================
+// CRUD Operation Options
+// ============================================================================
+
+export interface IInsertOneOptions {
+  /** Session for transaction support */
+  session?: IClientSession;
+  /** Custom write concern */
+  writeConcern?: IWriteConcern;
+}
+
+export interface IInsertManyOptions extends IInsertOneOptions {
+  /** If true, inserts are ordered and stop on first error */
+  ordered?: boolean;
+}
+
+export interface IFindOptions<TSchema = Document> {
+  /** Projection to apply */
+  projection?: Partial<Record<keyof TSchema | string, 0 | 1 | boolean>>;
+  /** Sort specification */
+  sort?: ISortSpecification;
+  /** Number of documents to skip */
+  skip?: number;
+  /** Maximum number of documents to return */
+  limit?: number;
+  /** Session for transaction support */
+  session?: IClientSession;
+  /** Hint for index usage */
+  hint?: string | Document;
+}
+
+export interface IUpdateOptions {
+  /** Create document if it doesn't exist */
+  upsert?: boolean;
+  /** Session for transaction support */
+  session?: IClientSession;
+  /** Array filters for positional updates */
+  arrayFilters?: Document[];
+  /** Custom write concern */
+  writeConcern?: IWriteConcern;
+  /** Hint for index usage */
+  hint?: string | Document;
+}
+
+export interface IReplaceOptions extends IUpdateOptions {}
+
+export interface IDeleteOptions {
+  /** Session for transaction support */
+  session?: IClientSession;
+  /** Custom write concern */
+  writeConcern?: IWriteConcern;
+  /** Hint for index usage */
+  hint?: string | Document;
+}
+
+export interface IFindOneAndUpdateOptions extends IUpdateOptions {
+  /** Return the document before or after the update */
+  returnDocument?: 'before' | 'after';
+  /** Projection to apply */
+  projection?: Document;
+  /** Sort specification to determine which document to modify */
+  sort?: ISortSpecification;
+}
+
+export interface IFindOneAndReplaceOptions extends IFindOneAndUpdateOptions {}
+
+export interface IFindOneAndDeleteOptions {
+  /** Projection to apply */
+  projection?: Document;
+  /** Sort specification to determine which document to delete */
+  sort?: ISortSpecification;
+  /** Session for transaction support */
+  session?: IClientSession;
+}
+
+// ============================================================================
+// CRUD Results
+// ============================================================================
+
+export interface IInsertOneResult {
+  acknowledged: boolean;
+  insertedId: plugins.bson.ObjectId;
+}
+
+export interface IInsertManyResult {
+  acknowledged: boolean;
+  insertedCount: number;
+  insertedIds: Record<number, plugins.bson.ObjectId>;
+}
+
+export interface IUpdateResult {
+  acknowledged: boolean;
+  matchedCount: number;
+  modifiedCount: number;
+  upsertedCount: number;
+  upsertedId: plugins.bson.ObjectId | null;
+}
+
+export interface IDeleteResult {
+  acknowledged: boolean;
+  deletedCount: number;
+}
+
+export interface IModifyResult<TSchema> {
+  value: TSchema | null;
+  ok: 1 | 0;
+  lastErrorObject?: {
+    n: number;
+    updatedExisting?: boolean;
+    upserted?: plugins.bson.ObjectId;
+  };
+}
+
+// ============================================================================
+// Sort and Index Types
+// ============================================================================
+
+export type ISortDirection = 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending';
+
+export type ISortSpecification = Record<string, ISortDirection> | [string, ISortDirection][];
+
+export interface IIndexSpecification {
+  key: Record<string, 1 | -1 | 'text' | '2dsphere'>;
+  name?: string;
+  unique?: boolean;
+  sparse?: boolean;
+  expireAfterSeconds?: number;
+  background?: boolean;
+  partialFilterExpression?: Document;
+}
+
+export interface IIndexInfo {
+  v: number;
+  key: Record<string, 1 | -1 | string>;
+  name: string;
+  unique?: boolean;
+  sparse?: boolean;
+  expireAfterSeconds?: number;
+}
+
+export interface ICreateIndexOptions {
+  unique?: boolean;
+  sparse?: boolean;
+  expireAfterSeconds?: number;
+  name?: string;
+  background?: boolean;
+  partialFilterExpression?: Document;
+}
+
+// ============================================================================
+// Write Concern
+// ============================================================================
+
+export interface IWriteConcern {
+  w?: number | 'majority';
+  j?: boolean;
+  wtimeout?: number;
+}
+
+// ============================================================================
+// Aggregation Types
+// ============================================================================
+
+export interface IAggregateOptions {
+  /** Allow disk use for large aggregations */
+  allowDiskUse?: boolean;
+  /** Maximum time in ms */
+  maxTimeMS?: number;
+  /** Session for transaction support */
+  session?: IClientSession;
+  /** Batch size for cursor */
+  batchSize?: number;
+  /** Collation settings */
+  collation?: ICollation;
+  /** Hint for index usage */
+  hint?: string | Document;
+  /** Comment for profiling */
+  comment?: string;
+}
+
+export interface ICollation {
+  locale: string;
+  caseLevel?: boolean;
+  caseFirst?: string;
+  strength?: number;
+  numericOrdering?: boolean;
+  alternate?: string;
+  maxVariable?: string;
+  backwards?: boolean;
+}
+
+// ============================================================================
+// Change Stream Types
+// ============================================================================
+
+export interface IChangeStreamOptions {
+  /** Resume after this token */
+  resumeAfter?: IResumeToken;
+  /** Start at this operation time */
+  startAtOperationTime?: plugins.bson.Timestamp;
+  /** Start after this token */
+  startAfter?: IResumeToken;
+  /** Full document lookup mode */
+  fullDocument?: 'default' | 'updateLookup' | 'whenAvailable' | 'required';
+  /** Full document before change */
+  fullDocumentBeforeChange?: 'off' | 'whenAvailable' | 'required';
+  /** Batch size */
+  batchSize?: number;
+  /** Maximum await time in ms */
+  maxAwaitTimeMS?: number;
+}
+
+export interface IResumeToken {
+  _data: string;
+}
+
+export type ChangeStreamOperationType =
+  | 'insert'
+  | 'update'
+  | 'replace'
+  | 'delete'
+  | 'drop'
+  | 'rename'
+  | 'dropDatabase'
+  | 'invalidate';
+
+export interface IChangeStreamDocument<TSchema = Document> {
+  _id: IResumeToken;
+  operationType: ChangeStreamOperationType;
+  fullDocument?: TSchema;
+  fullDocumentBeforeChange?: TSchema;
+  ns: {
+    db: string;
+    coll?: string;
+  };
+  documentKey?: { _id: plugins.bson.ObjectId };
+  updateDescription?: {
+    updatedFields?: Document;
+    removedFields?: string[];
+    truncatedArrays?: Array<{ field: string; newSize: number }>;
+  };
+  clusterTime?: plugins.bson.Timestamp;
+  txnNumber?: number;
+  lsid?: { id: plugins.bson.Binary; uid: plugins.bson.Binary };
+}
+
+// ============================================================================
+// Transaction Types
+// ============================================================================
+
+export interface IClientSession {
+  id: { id: plugins.bson.Binary };
+  inTransaction(): boolean;
+  startTransaction(options?: ITransactionOptions): void;
+  commitTransaction(): Promise<void>;
+  abortTransaction(): Promise<void>;
+  withTransaction<T>(fn: () => Promise<T>, options?: ITransactionOptions): Promise<T>;
+  endSession(): Promise<void>;
+}
+
+export interface ITransactionOptions {
+  readConcern?: IReadConcern;
+  writeConcern?: IWriteConcern;
+  readPreference?: string;
+  maxCommitTimeMS?: number;
+}
+
+export interface IReadConcern {
+  level: 'local' | 'available' | 'majority' | 'linearizable' | 'snapshot';
+}
+
+// ============================================================================
+// Bulk Operation Types
+// ============================================================================
+
+export interface IBulkWriteOptions {
+  ordered?: boolean;
+  session?: IClientSession;
+  writeConcern?: IWriteConcern;
+}
+
+export interface IBulkWriteOperation<TSchema = Document> {
+  insertOne?: { document: TSchema };
+  updateOne?: { filter: Document; update: Document; upsert?: boolean; arrayFilters?: Document[]; hint?: Document | string };
+  updateMany?: { filter: Document; update: Document; upsert?: boolean; arrayFilters?: Document[]; hint?: Document | string };
+  replaceOne?: { filter: Document; replacement: TSchema; upsert?: boolean; hint?: Document | string };
+  deleteOne?: { filter: Document; hint?: Document | string };
+  deleteMany?: { filter: Document; hint?: Document | string };
+}
+
+export interface IBulkWriteResult {
+  acknowledged: boolean;
+  insertedCount: number;
+  matchedCount: number;
+  modifiedCount: number;
+  deletedCount: number;
+  upsertedCount: number;
+  insertedIds: Record<number, plugins.bson.ObjectId>;
+  upsertedIds: Record<number, plugins.bson.ObjectId>;
+}
+
+// ============================================================================
+// Storage Types
+// ============================================================================
+
+export interface IStoredDocument extends Document {
+  _id: plugins.bson.ObjectId;
+}
+
+export interface IOpLogEntry {
+  ts: plugins.bson.Timestamp;
+  op: 'i' | 'u' | 'd' | 'c' | 'n';
+  ns: string;
+  o: Document;
+  o2?: Document;
+  txnNumber?: number;
+  lsid?: { id: plugins.bson.Binary };
+}
+
+// ============================================================================
+// Admin Types
+// ============================================================================
+
+export interface IDatabaseInfo {
+  name: string;
+  sizeOnDisk: number;
+  empty: boolean;
+}
+
+export interface ICollectionInfo {
+  name: string;
+  type: 'collection' | 'view';
+  options: Document;
+  info: {
+    readOnly: boolean;
+    uuid?: plugins.bson.Binary;
+  };
+  idIndex?: IIndexInfo;
+}
+
+export interface IServerStatus {
+  host: string;
+  version: string;
+  process: string;
+  pid: number;
+  uptime: number;
+  uptimeMillis: number;
+  uptimeEstimate: number;
+  localTime: Date;
+  mem: {
+    resident: number;
+    virtual: number;
+  };
+  connections: {
+    current: number;
+    available: number;
+    totalCreated: number;
+  };
+  ok: 1;
+}
+
+export interface ICollectionStats {
+  ns: string;
+  count: number;
+  size: number;
+  avgObjSize: number;
+  storageSize: number;
+  totalIndexSize: number;
+  indexSizes: Record<string, number>;
+  nindexes: number;
+  ok: 1;
+}
+
+// ============================================================================
+// Count Types
+// ============================================================================
+
+export interface ICountDocumentsOptions {
+  skip?: number;
+  limit?: number;
+  session?: IClientSession;
+  hint?: string | Document;
+  maxTimeMS?: number;
+}
+
+export interface IEstimatedDocumentCountOptions {
+  maxTimeMS?: number;
+}
+
+export interface IDistinctOptions {
+  session?: IClientSession;
+  maxTimeMS?: number;
+}

package/ts/ts_smartdb/utils/checksum.ts

@@ -0,0 +1,88 @@
+/**
+ * CRC32 checksum utilities for data integrity
+ */
+
+// CRC32 lookup table
+const CRC32_TABLE: number[] = [];
+
+// Initialize the CRC32 table
+function initCRC32Table(): void {
+  if (CRC32_TABLE.length > 0) return;
+
+  for (let i = 0; i < 256; i++) {
+    let crc = i;
+    for (let j = 0; j < 8; j++) {
+      crc = (crc & 1) ? (0xEDB88320 ^ (crc >>> 1)) : (crc >>> 1);
+    }
+    CRC32_TABLE[i] = crc >>> 0;
+  }
+}
+
+/**
+ * Calculate CRC32 checksum for a string
+ */
+export function calculateCRC32(data: string): number {
+  initCRC32Table();
+
+  let crc = 0xFFFFFFFF;
+  for (let i = 0; i < data.length; i++) {
+    const byte = data.charCodeAt(i) & 0xFF;
+    crc = CRC32_TABLE[(crc ^ byte) & 0xFF] ^ (crc >>> 8);
+  }
+  return (~crc) >>> 0;
+}
+
+/**
+ * Calculate CRC32 checksum for a Buffer
+ */
+export function calculateCRC32Buffer(data: Buffer): number {
+  initCRC32Table();
+
+  let crc = 0xFFFFFFFF;
+  for (let i = 0; i < data.length; i++) {
+    crc = CRC32_TABLE[(crc ^ data[i]) & 0xFF] ^ (crc >>> 8);
+  }
+  return (~crc) >>> 0;
+}
+
+/**
+ * Calculate checksum for a document (serialized as JSON)
+ */
+export function calculateDocumentChecksum(doc: Record<string, any>): number {
+  // Exclude _checksum field from calculation
+  const { _checksum, ...docWithoutChecksum } = doc;
+  const json = JSON.stringify(docWithoutChecksum);
+  return calculateCRC32(json);
+}
+
+/**
+ * Add checksum to a document
+ */
+export function addChecksum<T extends Record<string, any>>(doc: T): T & { _checksum: number } {
+  const checksum = calculateDocumentChecksum(doc);
+  return { ...doc, _checksum: checksum };
+}
+
+/**
+ * Verify checksum of a document
+ * Returns true if checksum is valid or if document has no checksum
+ */
+export function verifyChecksum(doc: Record<string, any>): boolean {
+  if (!('_checksum' in doc)) {
+    // No checksum to verify
+    return true;
+  }
+
+  const storedChecksum = doc._checksum;
+  const calculatedChecksum = calculateDocumentChecksum(doc);
+
+  return storedChecksum === calculatedChecksum;
+}
+
+/**
+ * Remove checksum from a document
+ */
+export function removeChecksum<T extends Record<string, any>>(doc: T): Omit<T, '_checksum'> {
+  const { _checksum, ...docWithoutChecksum } = doc;
+  return docWithoutChecksum as Omit<T, '_checksum'>;
+}

package/ts/ts_smartdb/utils/index.ts

@@ -0,0 +1 @@
+export * from './checksum.js';