@base44-preview/sdk 0.8.26-pr.167.9a82260 → 0.8.26-pr.167.fdb48d8

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
 export type { Base44Client, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
 export * from "./types.js";
-export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
+export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
 export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
 export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";

package/dist/modules/entities.js

@@ -41,34 +41,6 @@ function parseRealtimeMessage(dataStr) {
         return null;
     }
 }
-// In-flight HTTP refetches for oversize realtime events. Lets multiple
-// subscribers in the same browser (e.g. several React components subscribed
-// to the same entity) share one HTTP call when they all receive the same
-// oversize event. Keyed by `${entityName}:${id}:${timestamp}` so distinct
-// updates are not collapsed.
-const inflightRefetches = new Map();
-/**
- * Refetches a record over HTTP after the server signaled it had to slim the
- * realtime broadcast (`_oversize: true`). Reuses an in-flight promise if
- * one exists for the same (entityName, id, timestamp) so concurrent
- * subscribers in the same browser fan out to a single HTTP call.
- * @internal
- */
-function refetchTruncated(axios, baseURL, entityName, id, timestamp) {
-    const key = `${entityName}:${id}:${timestamp}`;
-    let promise = inflightRefetches.get(key);
-    if (!promise) {
-        promise = axios.get(`${baseURL}/${id}`);
-        inflightRefetches.set(key, promise);
-        // Clear the cache entry after the promise settles plus a short grace
-        // window so late subscribers can still piggy-back on the result. Use
-        // .then(success, failure) instead of .finally to avoid creating an
-        // unhandled rejection tail when the underlying axios call rejects.
-        const cleanup = () => setTimeout(() => inflightRefetches.delete(key), 5000);
-        promise.then(cleanup, cleanup);
-    }
-    return promise;
-}
 /**
  * Creates a handler for a specific entity.
  *
@@ -158,25 +130,24 @@ function createEntityHandler(axios, appId, entityName, getSocket) {
             // Get the socket and subscribe to the room
             const socket = getSocket();
             const unsubscribe = socket.subscribeToRoom(room, {
-                update_model: async (msg) => {
+                update_model: (msg) => {
                     var _a;
                     const event = parseRealtimeMessage(msg.data);
                     if (!event) {
                         return;
                     }
                     // Server signals oversize broadcasts with `_oversize: true` on
-                    // `data`. The wire payload is bounded for transport; we transparently
-                    // refetch the full record over HTTP so callers always see complete
-                    // data. Skip on delete events — the record no longer exists.
+                    // `data`. The wire payload was slimmed to fit under the realtime
+                    // transport cap, so big string fields arrive as empty strings (or
+                    // the whole record collapses to a stub). Surface this to the
+                    // developer console so they know to fetch the full record on
+                    // demand (e.g. a follow-up entities.X.get(id) call) instead of
+                    // rendering the slimmed payload directly. Skip on delete events
+                    // — the record no longer exists.
                     if (event.type !== "delete" && ((_a = event.data) === null || _a === void 0 ? void 0 : _a._oversize)) {
-                        try {
-                            event.data = await refetchTruncated(axios, baseURL, entityName, event.id, event.timestamp);
-                        }
-                        catch (error) {
-                            console.warn("[Base44 SDK] Failed to refetch oversize entity, falling through with stub payload:", error);
-                            // event.data stays as the `{id, _oversize: true}` stub; user
-                            // code receives partial data — same UX as today's drop-and-stale.
-                        }
+                        console.error(`[Base44 SDK] Realtime broadcast for ${entityName}#${event.id} was oversize and got slimmed for transport. ` +
+                            `Fields >10 KB are empty and the rest of the record may be a stub. ` +
+                            `Call \`entities.${entityName}.get("${event.id}")\` to fetch the full record.`);
                     }
                     try {
                         callback(event);

package/dist/modules/entities.types.d.ts

@@ -84,6 +84,74 @@ export interface ImportResult<T = any> {
  * ```
  */
 export type SortField<T> = (keyof T & string) | `+${keyof T & string}` | `-${keyof T & string}`;
+/**
+ * Entity filter query type system.
+ *
+ * `EntityFilterQuery<T>` keeps field names tied to the entity schema while
+ * allowing Base44's documented filtering syntax. Each field can use an exact
+ * value, `null`, an array shorthand for matching any listed value, or a
+ * field-level operator object. Root-level `$and`, `$or`, and `$nor` combine
+ * nested filter queries.
+ *
+ * Operator values are typed from the field they filter where possible. For
+ * example, numeric fields accept numeric comparison values, string fields
+ * accept `$regex`, and array fields accept `$all` and `$size`.
+ */
+/**
+ * Value accepted when filtering an entity field.
+ *
+ * Supports exact matches, `null`, array shorthand for matching any of the
+ * provided values, and documented MongoDB-style query operators.
+ *
+ * @typeParam T - Field value type.
+ */
+export type EntityFilterValue<T> = EntityFilterComparable<T> | EntityFilterComparable<T>[] | EntityFilterOperators<T>;
+/**
+ * MongoDB-style query operators accepted for a single entity field.
+ *
+ * @typeParam T - Field value type.
+ */
+export type EntityFilterOperators<T> = EntityFilterCommonOperators<T> & {
+    /** Negates another field-level filter expression. */
+    $not?: EntityFilterCommonOperators<T>;
+};
+type EntityFilterComparable<T> = Exclude<T, undefined> | null;
+type EntityFilterCommonOperators<T> = {
+    $eq?: EntityFilterComparable<T>;
+    $ne?: EntityFilterComparable<T>;
+    $gt?: EntityFilterComparable<T>;
+    $gte?: EntityFilterComparable<T>;
+    $lt?: EntityFilterComparable<T>;
+    $lte?: EntityFilterComparable<T>;
+    $in?: EntityFilterComparable<T>[];
+    $nin?: EntityFilterComparable<T>[];
+    $exists?: boolean;
+} & EntityFilterStringOperators<T> & EntityFilterArrayOperators<T>;
+type EntityFilterStringOperators<T> = Extract<Exclude<T, undefined | null>, string> extends never ? {} : {
+    $regex?: string;
+};
+type EntityFilterArrayElement<T> = T extends readonly (infer U)[] ? U : never;
+type EntityFilterArrayOperators<T> = [
+    EntityFilterArrayElement<Exclude<T, undefined | null>>
+] extends [never] ? {} : {
+    $all?: EntityFilterArrayElement<Exclude<T, undefined | null>>[];
+    $size?: number;
+};
+/**
+ * Query object accepted by entity filtering methods.
+ *
+ * Field keys are typed from the entity schema. `$and`, `$or`, and `$nor`
+ * combine nested filter queries at the root level.
+ *
+ * @typeParam T - Entity record type.
+ */
+export type EntityFilterQuery<T> = {
+    [K in keyof T]?: EntityFilterValue<T[K]>;
+} & {
+    $and?: EntityFilterQuery<T>[];
+    $or?: EntityFilterQuery<T>[];
+    $nor?: EntityFilterQuery<T>[];
+};
 /**
  * Fields added by the server to every entity record, such as `id`, `created_date`, `updated_date`, and `created_by`.
  */
@@ -189,7 +257,9 @@ export interface EntityHandler<T = any> {
      * @typeParam K - The fields to include in the response. Defaults to all fields.
      * @param query - Query object with field-value pairs. Each key should be a field name
      * from your entity schema, and each value is the criteria to match. Records matching all
-     * specified criteria are returned. Field names are case-sensitive.
+     * specified criteria are returned. Field names are case-sensitive. Use field-value pairs
+     * for exact matches, `null` for null values, arrays as shorthand for matching any of the
+     * provided values, or documented MongoDB query operators for advanced filtering.
      * @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
      * @param limit - Maximum number of results to return. Defaults to `50`.
      * @param skip - Number of results to skip for pagination. Defaults to `0`.
@@ -215,6 +285,42 @@ export interface EntityHandler<T = any> {
      *
      * @example
      * ```typescript
+     * // Filter by any matching value
+     * const records = await base44.entities.MyEntity.filter({
+     *   external_id: ['item-1', 'item-2']
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter with query operators
+     * const popularRecords = await base44.entities.MyEntity.filter({
+     *   count: { $gte: 100 },
+     *   external_id: { $in: ['item-1', 'item-2'] }
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter with logical operators
+     * const records = await base44.entities.MyEntity.filter({
+     *   $or: [
+     *     { name: 'Example item' },
+     *     { slug: 'example-item' }
+     *   ]
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter null values
+     * const recordsWithoutDescription = await base44.entities.MyEntity.filter({
+     *   description: null
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
      * // Filter with sorting and pagination
      * const results = await base44.entities.MyEntity.filter(
      *   { status: 'active' },
@@ -236,7 +342,7 @@ export interface EntityHandler<T = any> {
      * );
      * ```
      */
-    filter<K extends keyof T = keyof T>(query: Partial<T>, sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
+    filter<K extends keyof T = keyof T>(query: EntityFilterQuery<T>, sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
     /**
      * Gets a single record by ID.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.26-pr.167.9a82260",
+  "version": "0.8.26-pr.167.fdb48d8",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,8 @@
   "scripts": {
     "build": "tsc",
     "lint": "eslint src",
-    "test": "vitest run",
+    "test": "npm run test:types && vitest run",
+    "test:types": "tsc --noEmit -p tsconfig.type-tests.json",
     "test:unit": "vitest run tests/unit",
     "test:e2e": "vitest run tests/e2e",
     "test:watch": "vitest",