@ponceca/firestore-sdk 0.1.0

package/dist/types-meoR-Ecp.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Firestore SDK - Tipos TypeScript
+ * Compatible con Firebase Firestore v9
+ */
+/** Datos de un documento Firestore */
+type DocumentData = Record<string, unknown>;
+/** Tipo para campos anidados usando dot notation */
+type FieldPath = string;
+/** Unión de todos los field values especiales */
+type FieldValue = {
+    readonly isEqual: (other: FieldValue) => boolean;
+};
+/** Opciones para inicializar la app (idéntico a Firebase) */
+interface FirebaseOptions {
+    /** API Key del proyecto (para autenticación con API keys) */
+    apiKey?: string;
+    /** ID del proyecto (requerido) */
+    projectId: string;
+    /** Auth Domain para autenticación OAuth */
+    authDomain?: string;
+    /** URL del Storage Bucket */
+    storageBucket?: string;
+    /** ID del sender para mensajería */
+    messagingSenderId?: string;
+    /** App ID de Firebase */
+    appId?: string;
+    /** ID de medición para Analytics */
+    measurementId?: string;
+    /** URL base del servidor (para self-hosted, no existe en Firebase original) */
+    baseUrl?: string;
+    /** ID de la base de datos (default: "(default)") */
+    databaseId?: string;
+}
+/**
+ * Proveedor de tokens de autenticación
+ * Permite integrar cualquier sistema de auth (Firebase Auth, Auth0, custom, etc.)
+ */
+interface AuthTokenProvider {
+    /** Obtiene el token actual (puede ser async para refresh) */
+    getToken(): Promise<string | null>;
+    /** Listener para cambios de auth state */
+    onAuthStateChanged?(callback: (token: string | null) => void): () => void;
+}
+/** Configuración de Firestore (idéntico a Firebase) */
+interface FirestoreSettings {
+    /** Host del servidor (ej: "localhost:3000" o "firestore.googleapis.com") */
+    host?: string;
+    /** Usar SSL/TLS */
+    ssl?: boolean;
+    /** Ignorar certificados no válidos (solo desarrollo) */
+    experimentalForceLongPolling?: boolean;
+    /** Usar fetch en lugar de WebChannel */
+    experimentalAutoDetectLongPolling?: boolean;
+    /** Tamaño de caché en bytes */
+    cacheSizeBytes?: number;
+    /** Habilitar persistencia multi-tab */
+    synchronizeTabs?: boolean;
+    /** Timeout para requests (ms) */
+    timeout?: number;
+    /** Token de autenticación (se configura automáticamente si hay Auth) */
+    authToken?: string;
+    /** Proveedor de tokens personalizado */
+    authTokenProvider?: AuthTokenProvider;
+    /** Permite queries flexibles fuera de restricciones de Firestore (solo PostgreSQL) */
+    allowFlexibleQueries?: boolean;
+    /** Número máximo de reintentos para errores transitorios de red */
+    maxRetries?: number;
+    /** Delay inicial de reintento en ms (backoff exponencial) */
+    retryInitialDelayMs?: number;
+    /** Delay máximo de reintento en ms */
+    retryMaxDelayMs?: number;
+}
+/** Tipo de referencia */
+type ReferenceType = 'document' | 'collection';
+/** Referencia base (abstracta) */
+interface BaseReference {
+    /** Tipo de referencia */
+    readonly type: ReferenceType;
+    /** Path completo */
+    readonly path: string;
+    /** ID del elemento (último segmento del path) */
+    readonly id: string;
+    /** Referencia a Firestore */
+    readonly firestore: FirestoreInstance;
+}
+/** Referencia a un documento */
+interface DocumentReference<T = DocumentData> extends BaseReference {
+    readonly type: 'document';
+    /** Referencia a la colección padre */
+    readonly parent: CollectionReference<T>;
+}
+/** Referencia a una colección */
+interface CollectionReference<_T = DocumentData> extends BaseReference {
+    readonly type: 'collection';
+    /** Referencia al documento padre (si es subcolección) */
+    readonly parent: DocumentReference | null;
+}
+/** Query de Firestore */
+interface Query<_T = DocumentData> {
+    readonly type: 'query' | 'collectionGroup';
+    readonly firestore: FirestoreInstance;
+    /** Path de la colección */
+    readonly path: string;
+}
+/** Operadores de comparación */
+type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in';
+/** Dirección de ordenamiento */
+type OrderByDirection = 'asc' | 'desc';
+/** Constraint de query: where */
+interface WhereConstraint {
+    readonly type: 'where';
+    readonly field: string;
+    readonly op: WhereFilterOp;
+    readonly value: unknown;
+}
+/** Constraint de query: orderBy */
+interface OrderByConstraint {
+    readonly type: 'orderBy';
+    readonly field: string;
+    readonly direction: OrderByDirection;
+}
+/** Constraint de query: limit */
+interface LimitConstraint {
+    readonly type: 'limit' | 'limitToLast';
+    readonly limit: number;
+}
+/** Constraint de query: startAt/startAfter */
+interface StartAtConstraint {
+    readonly type: 'startAt' | 'startAfter';
+    readonly values: unknown[];
+    readonly inclusive: boolean;
+}
+/** Constraint de query: endAt/endBefore */
+interface EndAtConstraint {
+    readonly type: 'endAt' | 'endBefore';
+    readonly values: unknown[];
+    readonly inclusive: boolean;
+}
+/** Constraint de query: and (filtro compuesto) */
+interface AndConstraint {
+    readonly type: 'and';
+    readonly constraints: QueryConstraint[];
+}
+/** Constraint de query: or (filtro compuesto) */
+interface OrConstraint {
+    readonly type: 'or';
+    readonly constraints: QueryConstraint[];
+}
+/** Constraint de offset para paginación directa */
+interface OffsetConstraint {
+    readonly type: 'offset';
+    readonly count: number;
+}
+/** Unión de todos los constraints */
+type QueryConstraint = WhereConstraint | OrderByConstraint | LimitConstraint | StartAtConstraint | EndAtConstraint | AndConstraint | OrConstraint | OffsetConstraint;
+/** Metadatos de un snapshot */
+interface SnapshotMetadata {
+    /** Si viene de cache local */
+    readonly fromCache: boolean;
+    /** Si tiene cambios pendientes de sincronizar */
+    readonly hasPendingWrites: boolean;
+}
+/** Tipo de cambio en un documento */
+type DocumentChangeType = 'added' | 'modified' | 'removed';
+/** Snapshot de un documento */
+interface DocumentSnapshot<T = DocumentData> {
+    /** ID del documento */
+    readonly id: string;
+    /** Referencia al documento */
+    readonly ref: DocumentReference<T>;
+    /** Si el documento existe */
+    exists(): boolean;
+    /** Obtener datos del documento */
+    data(): T | undefined;
+    /** Obtener un campo específico */
+    get(fieldPath: FieldPath): unknown;
+    /** Metadatos */
+    readonly metadata: SnapshotMetadata;
+}
+/** Cambio en un documento (para onSnapshot) */
+interface DocumentChange<T = DocumentData> {
+    /** Tipo de cambio */
+    readonly type: DocumentChangeType;
+    /** Snapshot del documento */
+    readonly doc: DocumentSnapshot<T>;
+    /** Índice anterior (-1 si es nuevo) */
+    readonly oldIndex: number;
+    /** Índice nuevo (-1 si fue eliminado) */
+    readonly newIndex: number;
+}
+/** Snapshot de una query */
+interface QuerySnapshot<T = DocumentData> {
+    /** Referencia a la query */
+    readonly query: Query<T>;
+    /** Documentos en el resultado */
+    readonly docs: DocumentSnapshot<T>[];
+    /** Si está vacío */
+    readonly empty: boolean;
+    /** Número de documentos */
+    readonly size: number;
+    /** Metadatos */
+    readonly metadata: SnapshotMetadata;
+    /** Iterar sobre documentos */
+    forEach(callback: (doc: DocumentSnapshot<T>) => void): void;
+    /** Obtener cambios desde el último snapshot */
+    docChanges(): DocumentChange<T>[];
+}
+/** Instancia de FirebaseApp */
+interface FirebaseApp {
+    /** Nombre de la app */
+    readonly name: string;
+    /** Opciones de configuración */
+    readonly options: FirebaseOptions;
+}
+/** Instancia de Firestore */
+interface FirestoreInstance {
+    /** App asociada */
+    readonly app: FirebaseApp;
+    /** Tipo de instancia */
+    readonly type: 'firestore';
+    /** Configuración interna */
+    readonly _config: FirestoreSettings & {
+        host: string;
+        ssl: boolean;
+        timeout: number;
+        maxRetries: number;
+        retryInitialDelayMs: number;
+        retryMaxDelayMs: number;
+    };
+    /** Configuración pública (compatible con Firebase SDK) */
+    readonly settings: FirestoreSettings;
+    /** Project ID */
+    readonly _projectId: string;
+    /** Database ID */
+    readonly _databaseId: string;
+    /** Obtiene el token de autenticación actual */
+    getToken(): Promise<string | null>;
+}
+/** Alias para compatibilidad con Firebase SDK */
+type Firestore = FirestoreInstance;
+/** Opciones para setDoc */
+interface SetOptions {
+    /** Merge con datos existentes */
+    merge?: boolean;
+    /** Campos específicos a mergear */
+    mergeFields?: FieldPath[];
+}
+/** Función para cancelar suscripción */
+type Unsubscribe = () => void;
+/** Origen de lectura para listeners en tiempo real */
+type ListenSource = 'default' | 'cache';
+/** Opciones para onSnapshot */
+interface SnapshotListenOptions {
+    /** Incluir cambios de metadatos */
+    includeMetadataChanges?: boolean;
+    /** Origen de datos del listener (Firestore moderno) */
+    source?: ListenSource;
+}
+/** Códigos de error de Firestore */
+type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated';
+/** Error de Firestore */
+interface FirestoreError extends Error {
+    /** Código de error */
+    readonly code: FirestoreErrorCode;
+    /** Mensaje de error */
+    readonly message: string;
+}
+
+export type { AuthTokenProvider as A, CollectionReference as C, DocumentChange as D, EndAtConstraint as E, FieldPath as F, ListenSource as L, OrderByDirection as O, Query as Q, SetOptions as S, Unsubscribe as U, WhereFilterOp as W, DocumentData as a, DocumentReference as b, DocumentSnapshot as c, FieldValue as d, FirebaseApp as e, FirebaseOptions as f, Firestore as g, FirestoreError as h, FirestoreErrorCode as i, FirestoreSettings as j, QuerySnapshot as k, FirestoreInstance as l, LimitConstraint as m, OrderByConstraint as n, QueryConstraint as o, StartAtConstraint as p, WhereConstraint as q, SnapshotListenOptions as r, DocumentChangeType as s };

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@ponceca/firestore-sdk",
+  "version": "0.1.0",
+  "description": "SDK JavaScript/TypeScript compatible con Firebase Firestore v9",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./app": {
+      "types": "./dist/app.d.ts",
+      "import": "./dist/app.mjs",
+      "require": "./dist/app.js"
+    },
+    "./firestore": {
+      "types": "./dist/firestore/index.d.ts",
+      "import": "./dist/firestore/index.mjs",
+      "require": "./dist/firestore/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.mjs",
+      "require": "./dist/auth/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ponceca/firestore.git",
+    "directory": "sdk/js"
+  },
+  "bugs": {
+    "url": "https://github.com/ponceca/firestore/issues"
+  },
+  "homepage": "https://github.com/ponceca/firestore/tree/main/sdk/js#readme",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:realworld:sdk": "vitest run tests/search-real-world.test.ts --reporter=verbose",
+    "test:realworld:compiled": "npm run build && vitest run tests/search-real-world.test.ts --reporter=verbose",
+    "test:production-suite": "vitest run tests/production-suite/",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "release:check": "npm run typecheck && npm run build && npm run test:production-suite"
+  },
+  "keywords": [
+    "firestore",
+    "firebase",
+    "database",
+    "realtime",
+    "sdk"
+  ],
+  "author": "ponceca",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^1.2.0",
+    "fake-indexeddb": "^6.2.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0",
+    "ws": "^8.19.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}