s3db.js 4.1.6 → 4.1.8

package/dist/s3db.es.js

@@ -8566,6 +8566,14 @@ function calculateUTF8Bytes(str) {
   }
   return bytes;
 }
+function calculateAttributeNamesSize(mappedObject) {
+  let totalSize = 0;
+  for (const key of Object.keys(mappedObject)) {
+    if (key === "_v") continue;
+    totalSize += calculateUTF8Bytes(key);
+  }
+  return totalSize;
+}
 function transformValue(value) {
   if (value === null || value === void 0) {
     return "";
@@ -8600,49 +8608,31 @@ function calculateAttributeSizes(mappedObject) {
   return sizes;
 }
 function calculateTotalSize(mappedObject) {
-  const sizes = calculateAttributeSizes(mappedObject);
-  return Object.values(sizes).reduce((total, size) => total + size, 0);
+  const valueSizes = calculateAttributeSizes(mappedObject);
+  const valueTotal = Object.values(valueSizes).reduce((total, size) => total + size, 0);
+  const namesSize = calculateAttributeNamesSize(mappedObject);
+  return valueTotal + namesSize;
 }
 
-const S3_METADATA_LIMIT_BYTES$3 = 2e3;
+const S3_METADATA_LIMIT_BYTES = 2048;
 async function handleInsert$3({ resource, data, mappedData }) {
   const totalSize = calculateTotalSize(mappedData);
-  if (totalSize > S3_METADATA_LIMIT_BYTES$3) {
-    resource.emit("exceedsLimit", {
-      operation: "insert",
-      totalSize,
-      limit: S3_METADATA_LIMIT_BYTES$3,
-      excess: totalSize - S3_METADATA_LIMIT_BYTES$3,
-      data
-    });
+  if (totalSize > S3_METADATA_LIMIT_BYTES) {
+    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
   }
   return { mappedData, body: "" };
 }
 async function handleUpdate$3({ resource, id, data, mappedData }) {
   const totalSize = calculateTotalSize(mappedData);
-  if (totalSize > S3_METADATA_LIMIT_BYTES$3) {
-    resource.emit("exceedsLimit", {
-      operation: "update",
-      id,
-      totalSize,
-      limit: S3_METADATA_LIMIT_BYTES$3,
-      excess: totalSize - S3_METADATA_LIMIT_BYTES$3,
-      data
-    });
+  if (totalSize > S3_METADATA_LIMIT_BYTES) {
+    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
   }
   return { mappedData, body: "" };
 }
 async function handleUpsert$3({ resource, id, data, mappedData }) {
   const totalSize = calculateTotalSize(mappedData);
-  if (totalSize > S3_METADATA_LIMIT_BYTES$3) {
-    resource.emit("exceedsLimit", {
-      operation: "upsert",
-      id,
-      totalSize,
-      limit: S3_METADATA_LIMIT_BYTES$3,
-      excess: totalSize - S3_METADATA_LIMIT_BYTES$3,
-      data
-    });
+  if (totalSize > S3_METADATA_LIMIT_BYTES) {
+    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
   }
   return { mappedData, body: "" };
 }
@@ -8650,33 +8640,53 @@ async function handleGet$3({ resource, metadata, body }) {
   return { metadata, body };
 }
 
-var userManagement = /*#__PURE__*/Object.freeze({
+var enforceLimits = /*#__PURE__*/Object.freeze({
   __proto__: null,
+  S3_METADATA_LIMIT_BYTES: S3_METADATA_LIMIT_BYTES,
   handleGet: handleGet$3,
   handleInsert: handleInsert$3,
   handleUpdate: handleUpdate$3,
   handleUpsert: handleUpsert$3
 });
 
-const S3_METADATA_LIMIT_BYTES$2 = 2e3;
 async function handleInsert$2({ resource, data, mappedData }) {
   const totalSize = calculateTotalSize(mappedData);
-  if (totalSize > S3_METADATA_LIMIT_BYTES$2) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, limit: ${S3_METADATA_LIMIT_BYTES$2} bytes`);
+  if (totalSize > S3_METADATA_LIMIT_BYTES) {
+    resource.emit("exceedsLimit", {
+      operation: "insert",
+      totalSize,
+      limit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - S3_METADATA_LIMIT_BYTES,
+      data
+    });
   }
   return { mappedData, body: "" };
 }
 async function handleUpdate$2({ resource, id, data, mappedData }) {
   const totalSize = calculateTotalSize(mappedData);
-  if (totalSize > S3_METADATA_LIMIT_BYTES$2) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, limit: ${S3_METADATA_LIMIT_BYTES$2} bytes`);
+  if (totalSize > S3_METADATA_LIMIT_BYTES) {
+    resource.emit("exceedsLimit", {
+      operation: "update",
+      id,
+      totalSize,
+      limit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - S3_METADATA_LIMIT_BYTES,
+      data
+    });
   }
   return { mappedData, body: "" };
 }
 async function handleUpsert$2({ resource, id, data, mappedData }) {
   const totalSize = calculateTotalSize(mappedData);
-  if (totalSize > S3_METADATA_LIMIT_BYTES$2) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, limit: ${S3_METADATA_LIMIT_BYTES$2} bytes`);
+  if (totalSize > S3_METADATA_LIMIT_BYTES) {
+    resource.emit("exceedsLimit", {
+      operation: "upsert",
+      id,
+      totalSize,
+      limit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - S3_METADATA_LIMIT_BYTES,
+      data
+    });
   }
   return { mappedData, body: "" };
 }
@@ -8684,7 +8694,7 @@ async function handleGet$2({ resource, metadata, body }) {
   return { metadata, body };
 }
 
-var enforceLimits = /*#__PURE__*/Object.freeze({
+var userManagement = /*#__PURE__*/Object.freeze({
   __proto__: null,
   handleGet: handleGet$2,
   handleInsert: handleInsert$2,
@@ -8692,7 +8702,6 @@ var enforceLimits = /*#__PURE__*/Object.freeze({
   handleUpsert: handleUpsert$2
 });
 
-const S3_METADATA_LIMIT_BYTES$1 = 2e3;
 const TRUNCATE_SUFFIX = "...";
 const TRUNCATE_SUFFIX_BYTES = calculateUTF8Bytes(TRUNCATE_SUFFIX);
 async function handleInsert$1({ resource, data, mappedData }) {
@@ -8713,7 +8722,7 @@ function handleTruncate({ resource, data, mappedData }) {
   const result = {};
   let currentSize = 0;
   for (const [key, size] of sortedAttributes) {
-    const availableSpace = S3_METADATA_LIMIT_BYTES$1 - currentSize;
+    const availableSpace = S3_METADATA_LIMIT_BYTES - currentSize;
     if (size <= availableSpace) {
       result[key] = mappedData[key];
       currentSize += size;
@@ -8733,7 +8742,7 @@ function handleTruncate({ resource, data, mappedData }) {
         }
       }
       result[key] = truncatedValue + TRUNCATE_SUFFIX;
-      currentSize = S3_METADATA_LIMIT_BYTES$1;
+      currentSize = S3_METADATA_LIMIT_BYTES;
       break;
     } else {
       break;
@@ -8750,7 +8759,6 @@ var dataTruncate = /*#__PURE__*/Object.freeze({
   handleUpsert: handleUpsert$1
 });
 
-const S3_METADATA_LIMIT_BYTES = 2e3;
 const OVERFLOW_FLAG = "$overflow";
 const OVERFLOW_FLAG_VALUE = "true";
 const OVERFLOW_FLAG_BYTES = calculateUTF8Bytes(OVERFLOW_FLAG) + calculateUTF8Bytes(OVERFLOW_FLAG_VALUE);
@@ -9093,13 +9101,29 @@ class Resource extends EventEmitter {
     return join(`resource=${this.name}`, `v=${this.version}`, `id=${id}`);
   }
   /**
-   * Get partition reference key for a specific partition
-   * @param {string} partitionName - Name of the partition
-   * @param {string} id - Resource ID  
-   * @param {Object} data - Data object for partition value generation
-   * @returns {string|null} The partition reference S3 key path
+   * Generate partition key for a resource in a specific partition
+   * @param {Object} params - Partition key parameters
+   * @param {string} params.partitionName - Name of the partition
+   * @param {string} params.id - Resource ID
+   * @param {Object} params.data - Resource data for partition value extraction
+   * @returns {string|null} The partition key path or null if required fields are missing
+   * @example
+   * const partitionKey = resource.getPartitionKey({
+   *   partitionName: 'byUtmSource',
+   *   id: 'user-123',
+   *   data: { utm: { source: 'google' } }
+   * });
+   * // Returns: 'resource=users/partition=byUtmSource/utm.source=google/id=user-123'
+   * 
+   * // Returns null if required field is missing
+   * const nullKey = resource.getPartitionKey({
+   *   partitionName: 'byUtmSource',
+   *   id: 'user-123',
+   *   data: { name: 'John' } // Missing utm.source
+   * });
+   * // Returns: null
    */
-  getPartitionKey(partitionName, id, data) {
+  getPartitionKey({ partitionName, id, data }) {
     const partition = this.options.partitions[partitionName];
     if (!partition) {
       throw new Error(`Partition '${partitionName}' not found`);
@@ -9130,15 +9154,36 @@ class Resource extends EventEmitter {
       return data[fieldPath];
     }
     const keys = fieldPath.split(".");
-    let value = data;
+    let currentLevel = data;
     for (const key of keys) {
-      if (value === null || value === void 0 || typeof value !== "object") {
+      if (!currentLevel || typeof currentLevel !== "object" || !(key in currentLevel)) {
         return void 0;
       }
-      value = value[key];
+      currentLevel = currentLevel[key];
     }
-    return value;
+    return currentLevel;
   }
+  /**
+   * Insert a new resource object
+   * @param {Object} params - Insert parameters
+   * @param {string} [params.id] - Resource ID (auto-generated if not provided)
+   * @param {...Object} params - Resource attributes (any additional properties)
+   * @returns {Promise<Object>} The inserted resource object with all attributes and generated ID
+   * @example
+   * // Insert with auto-generated ID
+   * const user = await resource.insert({
+   *   name: 'John Doe',
+   *   email: 'john@example.com',
+   *   age: 30
+   * });
+   * 
+   * // Insert with custom ID
+   * const user = await resource.insert({
+   *   id: 'custom-id-123',
+   *   name: 'Jane Smith',
+   *   email: 'jane@example.com'
+   * });
+   */
   async insert({ id, ...attributes }) {
     if (this.options.timestamps) {
       attributes.createdAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -9177,39 +9222,68 @@ class Resource extends EventEmitter {
     this.emit("insert", final);
     return final;
   }
+  /**
+   * Retrieve a resource object by ID
+   * @param {string} id - Resource ID
+   * @returns {Promise<Object>} The resource object with all attributes and metadata
+   * @example
+   * const user = await resource.get('user-123');
+   * console.log(user.name); // 'John Doe'
+   * console.log(user._lastModified); // Date object
+   * console.log(user._hasContent); // boolean
+   */
   async get(id) {
     const key = this.getResourceKey(id);
-    const request = await this.client.headObject(key);
-    const objectVersion = this.extractVersionFromKey(key) || this.version;
-    const schema = await this.getSchemaForVersion(objectVersion);
-    let metadata = await schema.unmapper(request.Metadata);
-    const behaviorImpl = getBehavior(this.behavior);
-    let body = "";
-    if (request.ContentLength > 0) {
-      try {
-        const fullObject = await this.client.getObject(key);
-        body = await streamToString(fullObject.Body);
-      } catch (error) {
-        body = "";
+    try {
+      const request = await this.client.headObject(key);
+      const objectVersion = this.extractVersionFromKey(key) || this.version;
+      const schema = await this.getSchemaForVersion(objectVersion);
+      let metadata = await schema.unmapper(request.Metadata);
+      const behaviorImpl = getBehavior(this.behavior);
+      let body = "";
+      if (request.ContentLength > 0) {
+        try {
+          const fullObject = await this.client.getObject(key);
+          body = await streamToString(fullObject.Body);
+        } catch (error) {
+          console.warn(`Failed to read body for resource ${id}:`, error.message);
+          body = "";
+        }
       }
+      const { metadata: processedMetadata } = await behaviorImpl.handleGet({
+        resource: this,
+        metadata,
+        body
+      });
+      let data = processedMetadata;
+      data.id = id;
+      data._contentLength = request.ContentLength;
+      data._lastModified = request.LastModified;
+      data._hasContent = request.ContentLength > 0;
+      data._mimeType = request.ContentType || null;
+      if (request.VersionId) data._versionId = request.VersionId;
+      if (request.Expiration) data._expiresAt = request.Expiration;
+      data._definitionHash = this.getDefinitionHash();
+      this.emit("get", data);
+      return data;
+    } catch (error) {
+      const enhancedError = new Error(`Failed to get resource with id '${id}': ${error.message}`);
+      enhancedError.originalError = error;
+      enhancedError.resourceId = id;
+      enhancedError.resourceKey = key;
+      throw enhancedError;
     }
-    const { metadata: processedMetadata } = await behaviorImpl.handleGet({
-      resource: this,
-      metadata,
-      body
-    });
-    let data = processedMetadata;
-    data.id = id;
-    data._contentLength = request.ContentLength;
-    data._lastModified = request.LastModified;
-    data._hasContent = request.ContentLength > 0;
-    data._mimeType = request.ContentType || null;
-    if (request.VersionId) data._versionId = request.VersionId;
-    if (request.Expiration) data._expiresAt = request.Expiration;
-    data._definitionHash = this.getDefinitionHash();
-    this.emit("get", data);
-    return data;
   }
+  /**
+   * Check if a resource exists by ID
+   * @param {string} id - Resource ID
+   * @returns {Promise<boolean>} True if resource exists, false otherwise
+   * @example
+   * const exists = await resource.exists('user-123');
+   * if (exists) {
+   *   console.log('User exists');
+   * }
+   */
   async exists(id) {
     try {
       const key = this.getResourceKey(id);
@@ -9219,6 +9293,24 @@ class Resource extends EventEmitter {
       return false;
     }
   }
+  /**
+   * Update an existing resource object
+   * @param {string} id - Resource ID
+   * @param {Object} attributes - Attributes to update (partial update supported)
+   * @returns {Promise<Object>} The updated resource object with all attributes
+   * @example
+   * // Update specific fields
+   * const updatedUser = await resource.update('user-123', {
+   *   name: 'John Updated',
+   *   age: 31
+   * });
+   * 
+   * // Update with timestamps (if enabled)
+   * const updatedUser = await resource.update('user-123', {
+   *   email: 'newemail@example.com'
+   * });
+   * console.log(updatedUser.updatedAt); // ISO timestamp
+   */
   async update(id, attributes) {
     const live = await this.get(id);
     if (this.options.timestamps) {
@@ -9275,6 +9367,14 @@ class Resource extends EventEmitter {
     this.emit("update", preProcessedData, validated);
     return validated;
   }
+  /**
+   * Delete a resource object by ID
+   * @param {string} id - Resource ID
+   * @returns {Promise<Object>} S3 delete response
+   * @example
+   * await resource.delete('user-123');
+   * console.log('User deleted successfully');
+   */
   async delete(id) {
     let objectData;
     try {
@@ -9289,6 +9389,20 @@ class Resource extends EventEmitter {
     this.emit("delete", id);
     return response;
   }
+  /**
+   * Insert or update a resource object (upsert operation)
+   * @param {Object} params - Upsert parameters
+   * @param {string} params.id - Resource ID (required for upsert)
+   * @param {...Object} params - Resource attributes (any additional properties)
+   * @returns {Promise<Object>} The inserted or updated resource object
+   * @example
+   * // Will insert if doesn't exist, update if exists
+   * const user = await resource.upsert({
+   *   id: 'user-123',
+   *   name: 'John Doe',
+   *   email: 'john@example.com'
+   * });
+   */
   async upsert({ id, ...attributes }) {
     const exists = await this.exists(id);
     if (exists) {
@@ -9296,6 +9410,28 @@ class Resource extends EventEmitter {
     }
     return this.insert({ id, ...attributes });
   }
+  /**
+   * Count resources with optional partition filtering
+   * @param {Object} [params] - Count parameters
+   * @param {string} [params.partition] - Partition name to count in
+   * @param {Object} [params.partitionValues] - Partition field values to filter by
+   * @returns {Promise<number>} Total count of matching resources
+   * @example
+   * // Count all resources
+   * const total = await resource.count();
+   * 
+   * // Count in specific partition
+   * const googleUsers = await resource.count({
+   *   partition: 'byUtmSource',
+   *   partitionValues: { 'utm.source': 'google' }
+   * });
+   * 
+   * // Count in multi-field partition
+   * const usElectronics = await resource.count({
+   *   partition: 'byCategoryRegion',
+   *   partitionValues: { category: 'electronics', region: 'US' }
+   * });
+   */
   async count({ partition = null, partitionValues = {} } = {}) {
     let prefix;
     if (partition && Object.keys(partitionValues).length > 0) {
@@ -9326,6 +9462,19 @@ class Resource extends EventEmitter {
     this.emit("count", count);
     return count;
   }
+  /**
+   * Insert multiple resources in parallel
+   * @param {Object[]} objects - Array of resource objects to insert
+   * @returns {Promise<Object[]>} Array of inserted resource objects
+   * @example
+   * const users = [
+   *   { name: 'John', email: 'john@example.com' },
+   *   { name: 'Jane', email: 'jane@example.com' },
+   *   { name: 'Bob', email: 'bob@example.com' }
+   * ];
+   * const insertedUsers = await resource.insertMany(users);
+   * console.log(`Inserted ${insertedUsers.length} users`);
+   */
   async insertMany(objects) {
     const { results } = await PromisePool.for(objects).withConcurrency(this.parallelism).handleError(async (error, content) => {
       this.emit("error", error, content);
@@ -9337,6 +9486,15 @@ class Resource extends EventEmitter {
     this.emit("insertMany", objects.length);
     return results;
   }
+  /**
+   * Delete multiple resources by their IDs in parallel
+   * @param {string[]} ids - Array of resource IDs to delete
+   * @returns {Promise<Object[]>} Array of S3 delete responses
+   * @example
+   * const deletedIds = ['user-1', 'user-2', 'user-3'];
+   * const results = await resource.deleteMany(deletedIds);
+   * console.log(`Deleted ${deletedIds.length} users`);
+   */
   async deleteMany(ids) {
     const packages = chunk(
       ids.map((id) => this.getResourceKey(id)),
@@ -9395,7 +9553,35 @@ class Resource extends EventEmitter {
     });
     return { deletedCount, resource: this.name };
   }
-  async listIds({ partition = null, partitionValues = {} } = {}) {
+  /**
+   * List resource IDs with optional partition filtering and pagination
+   * @param {Object} [params] - List parameters
+   * @param {string} [params.partition] - Partition name to list from
+   * @param {Object} [params.partitionValues] - Partition field values to filter by
+   * @param {number} [params.limit] - Maximum number of results to return
+   * @param {number} [params.offset=0] - Offset for pagination
+   * @returns {Promise<string[]>} Array of resource IDs (strings)
+   * @example
+   * // List all IDs
+   * const allIds = await resource.listIds();
+   * 
+   * // List IDs with pagination
+   * const firstPageIds = await resource.listIds({ limit: 10, offset: 0 });
+   * const secondPageIds = await resource.listIds({ limit: 10, offset: 10 });
+   * 
+   * // List IDs from specific partition
+   * const googleUserIds = await resource.listIds({
+   *   partition: 'byUtmSource',
+   *   partitionValues: { 'utm.source': 'google' }
+   * });
+   * 
+   * // List IDs from multi-field partition
+   * const usElectronicsIds = await resource.listIds({
+   *   partition: 'byCategoryRegion',
+   *   partitionValues: { category: 'electronics', region: 'US' }
+   * });
+   */
+  async listIds({ partition = null, partitionValues = {}, limit, offset = 0 } = {}) {
     let prefix;
     if (partition && Object.keys(partitionValues).length > 0) {
       const partitionDef = this.options.partitions[partition];
@@ -9419,8 +9605,11 @@ class Resource extends EventEmitter {
     } else {
       prefix = `resource=${this.name}/v=${this.version}`;
     }
-    const keys = await this.client.getAllKeys({
-      prefix
+    const keys = await this.client.getKeysPage({
+      prefix,
+      offset,
+      amount: limit || 1e3
+      // Default to 1000 if no limit specified
     });
     const ids = keys.map((key) => {
       const parts = key.split("/");
@@ -9431,13 +9620,36 @@ class Resource extends EventEmitter {
     return ids;
   }
   /**
-   * List objects by partition name and values
-   * @param {Object} partitionOptions - Partition options
-   * @param {Object} options - Listing options
-   * @returns {Array} Array of objects
+   * List resource objects with optional partition filtering and pagination
+   * @param {Object} [params] - List parameters
+   * @param {string} [params.partition] - Partition name to list from
+   * @param {Object} [params.partitionValues] - Partition field values to filter by
+   * @param {number} [params.limit] - Maximum number of results to return
+   * @param {number} [params.offset=0] - Offset for pagination
+   * @returns {Promise<Object[]>} Array of resource objects with all attributes
+   * @example
+   * // List all resources
+   * const allUsers = await resource.list();
+   * 
+   * // List with pagination
+   * const firstPage = await resource.list({ limit: 10, offset: 0 });
+   * const secondPage = await resource.list({ limit: 10, offset: 10 });
+   * 
+   * // List from specific partition
+   * const googleUsers = await resource.list({
+   *   partition: 'byUtmSource',
+   *   partitionValues: { 'utm.source': 'google' }
+   * });
+   * 
+   * // List from partition with pagination
+   * const googleUsersPage = await resource.list({
+   *   partition: 'byUtmSource',
+   *   partitionValues: { 'utm.source': 'google' },
+   *   limit: 5,
+   *   offset: 0
+   * });
    */
-  async listByPartition({ partition = null, partitionValues = {} } = {}, options = {}) {
-    const { limit, offset = 0 } = options;
+  async list({ partition = null, partitionValues = {}, limit, offset = 0 } = {}) {
     if (!partition) {
       const ids2 = await this.listIds({ partition, partitionValues });
       let filteredIds2 = ids2.slice(offset);
@@ -9447,7 +9659,7 @@ class Resource extends EventEmitter {
       const { results: results2 } = await PromisePool.for(filteredIds2).withConcurrency(this.parallelism).process(async (id) => {
         return await this.get(id);
       });
-      this.emit("listByPartition", { partition, partitionValues, count: results2.length });
+      this.emit("list", { partition, partitionValues, count: results2.length });
       return results2;
     }
     const partitionDef = this.options.partitions[partition];
@@ -9480,11 +9692,19 @@ class Resource extends EventEmitter {
       filteredIds = filteredIds.slice(0, limit);
     }
     const { results } = await PromisePool.for(filteredIds).withConcurrency(this.parallelism).process(async (id) => {
-      return await this.getFromPartition(id, partition, partitionValues);
+      return await this.getFromPartition({ id, partitionName: partition, partitionValues });
     });
-    this.emit("listByPartition", { partition, partitionValues, count: results.length });
+    this.emit("list", { partition, partitionValues, count: results.length });
     return results;
   }
+  /**
+   * Get multiple resources by their IDs
+   * @param {string[]} ids - Array of resource IDs
+   * @returns {Promise<Object[]>} Array of resource objects
+   * @example
+   * const users = await resource.getMany(['user-1', 'user-2', 'user-3']);
+   * users.forEach(user => console.log(user.name));
+   */
   async getMany(ids) {
     const { results } = await PromisePool.for(ids).withConcurrency(this.client.parallelism).process(async (id) => {
       this.emit("id", id);
@@ -9495,6 +9715,13 @@ class Resource extends EventEmitter {
     this.emit("getMany", ids.length);
     return results;
   }
+  /**
+   * Get all resources (equivalent to list() without pagination)
+   * @returns {Promise<Object[]>} Array of all resource objects
+   * @example
+   * const allUsers = await resource.getAll();
+   * console.log(`Total users: ${allUsers.length}`);
+   */
   async getAll() {
     let ids = await this.listIds();
     if (ids.length === 0) return [];
@@ -9505,20 +9732,65 @@ class Resource extends EventEmitter {
     this.emit("getAll", results.length);
     return results;
   }
-  async page(offset = 0, size = 100, { partition = null, partitionValues = {} } = {}) {
-    const allIds = await this.listIds({ partition, partitionValues });
-    const totalItems = allIds.length;
-    const totalPages = Math.ceil(totalItems / size);
-    const paginatedIds = allIds.slice(offset * size, (offset + 1) * size);
-    const items = await Promise.all(
-      paginatedIds.map((id) => this.get(id))
-    );
+  /**
+   * Get a page of resources with pagination metadata
+   * @param {Object} [params] - Page parameters
+   * @param {number} [params.offset=0] - Offset for pagination
+   * @param {number} [params.size=100] - Page size
+   * @param {string} [params.partition] - Partition name to page from
+   * @param {Object} [params.partitionValues] - Partition field values to filter by
+   * @param {boolean} [params.skipCount=false] - Skip total count for performance (useful for large collections)
+   * @returns {Promise<Object>} Page result with items and pagination info
+   * @example
+   * // Get first page of all resources
+   * const page = await resource.page({ offset: 0, size: 10 });
+   * console.log(`Page ${page.page + 1} of ${page.totalPages}`);
+   * console.log(`Showing ${page.items.length} of ${page.totalItems} total`);
+   * 
+   * // Get page from specific partition
+   * const googlePage = await resource.page({
+   *   partition: 'byUtmSource',
+   *   partitionValues: { 'utm.source': 'google' },
+   *   offset: 0,
+   *   size: 5
+   * });
+   * 
+   * // Skip count for performance in large collections
+   * const fastPage = await resource.page({ 
+   *   offset: 0, 
+   *   size: 100, 
+   *   skipCount: true 
+   * });
+   * console.log(`Got ${fastPage.items.length} items`); // totalItems will be null
+   */
+  async page({ offset = 0, size = 100, partition = null, partitionValues = {}, skipCount = false } = {}) {
+    let totalItems = null;
+    let totalPages = null;
+    if (!skipCount) {
+      totalItems = await this.count({ partition, partitionValues });
+      totalPages = Math.ceil(totalItems / size);
+    }
+    const page = Math.floor(offset / size);
+    const items = await this.list({
+      partition,
+      partitionValues,
+      limit: size,
+      offset
+    });
     const result = {
       items,
       totalItems,
-      page: offset,
+      page,
       pageSize: size,
-      totalPages
+      totalPages,
+      // Add additional metadata for debugging
+      _debug: {
+        requestedSize: size,
+        requestedOffset: offset,
+        actualItemsReturned: items.length,
+        skipCount,
+        hasTotalItems: totalItems !== null
+      }
     };
     this.emit("page", result);
     return result;
@@ -9532,36 +9804,62 @@ class Resource extends EventEmitter {
     return stream.build();
   }
   /**
-   * Store binary content associated with a resource
-   * @param {string} id - Resource ID
-   * @param {Buffer} buffer - Binary content
-   * @param {string} contentType - Optional content type
+   * Set binary content for a resource
+   * @param {Object} params - Content parameters
+   * @param {string} params.id - Resource ID
+   * @param {Buffer|string} params.buffer - Content buffer or string
+   * @param {string} [params.contentType='application/octet-stream'] - Content type
+   * @returns {Promise<Object>} Updated resource data
+   * @example
+   * // Set image content
+   * const imageBuffer = fs.readFileSync('image.jpg');
+   * await resource.setContent({
+   *   id: 'user-123',
+   *   buffer: imageBuffer,
+   *   contentType: 'image/jpeg'
+   * });
+   * 
+   * // Set text content
+   * await resource.setContent({
+   *   id: 'document-456',
+   *   buffer: 'Hello World',
+   *   contentType: 'text/plain'
+   * });
    */
-  async setContent(id, buffer, contentType = "application/octet-stream") {
-    if (!Buffer.isBuffer(buffer)) {
-      throw new Error("Content must be a Buffer");
-    }
-    const key = this.getResourceKey(id);
-    let existingMetadata = {};
-    try {
-      const existingObject = await this.client.headObject(key);
-      existingMetadata = existingObject.Metadata || {};
-    } catch (error) {
-    }
-    const response = await this.client.putObject({
-      key,
+  async setContent({ id, buffer, contentType = "application/octet-stream" }) {
+    const currentData = await this.get(id);
+    if (!currentData) {
+      throw new Error(`Resource with id '${id}' not found`);
+    }
+    const updatedData = {
+      ...currentData,
+      _hasContent: true,
+      _contentLength: buffer.length,
+      _mimeType: contentType
+    };
+    await this.client.putObject({
+      key: this.getResourceKey(id),
+      metadata: await this.schema.mapper(updatedData),
       body: buffer,
-      contentType,
-      metadata: existingMetadata
-      // Preserve existing metadata
+      contentType
     });
-    this.emit("setContent", id, buffer.length, contentType);
-    return response;
+    this.emit("setContent", { id, contentType, contentLength: buffer.length });
+    return updatedData;
   }
   /**
    * Retrieve binary content associated with a resource
    * @param {string} id - Resource ID
-   * @returns {Object} Object with buffer and contentType
+   * @returns {Promise<Object>} Object with buffer and contentType
+   * @example
+   * const content = await resource.content('user-123');
+   * if (content.buffer) {
+   *   console.log('Content type:', content.contentType);
+   *   console.log('Content size:', content.buffer.length);
+   *   // Save to file
+   *   fs.writeFileSync('output.jpg', content.buffer);
+   * } else {
+   *   console.log('No content found');
+   * }
    */
   async content(id) {
     const key = this.getResourceKey(id);
@@ -9656,7 +9954,7 @@ class Resource extends EventEmitter {
       return;
     }
     for (const [partitionName, partition] of Object.entries(partitions)) {
-      const partitionKey = this.getPartitionKey(partitionName, data.id, data);
+      const partitionKey = this.getPartitionKey({ partitionName, id: data.id, data });
       if (partitionKey) {
         const mappedData = await this.schema.mapper(data);
         const behaviorImpl = getBehavior(this.behavior);
@@ -9688,7 +9986,7 @@ class Resource extends EventEmitter {
     }
     const keysToDelete = [];
     for (const [partitionName, partition] of Object.entries(partitions)) {
-      const partitionKey = this.getPartitionKey(partitionName, data.id, data);
+      const partitionKey = this.getPartitionKey({ partitionName, id: data.id, data });
       if (partitionKey) {
         keysToDelete.push(partitionKey);
       }
@@ -9702,20 +10000,72 @@ class Resource extends EventEmitter {
     }
   }
   /**
-   * Query documents with simple filtering
-   * @param {Object} filter - Filter criteria
-   * @returns {Array} Filtered documents
+   * Query resources with simple filtering and pagination
+   * @param {Object} [filter={}] - Filter criteria (exact field matches)
+   * @param {Object} [options] - Query options
+   * @param {number} [options.limit=100] - Maximum number of results
+   * @param {number} [options.offset=0] - Offset for pagination
+   * @param {string} [options.partition] - Partition name to query from
+   * @param {Object} [options.partitionValues] - Partition field values to filter by
+   * @returns {Promise<Object[]>} Array of filtered resource objects
+   * @example
+   * // Query all resources (no filter)
+   * const allUsers = await resource.query();
+   * 
+   * // Query with simple filter
+   * const activeUsers = await resource.query({ status: 'active' });
+   * 
+   * // Query with multiple filters
+   * const usElectronics = await resource.query({
+   *   category: 'electronics',
+   *   region: 'US'
+   * });
+   * 
+   * // Query with pagination
+   * const firstPage = await resource.query(
+   *   { status: 'active' },
+   *   { limit: 10, offset: 0 }
+   * );
+   * 
+   * // Query within partition
+   * const googleUsers = await resource.query(
+   *   { status: 'active' },
+   *   {
+   *     partition: 'byUtmSource',
+   *     partitionValues: { 'utm.source': 'google' },
+   *     limit: 5
+   *   }
+   * );
    */
-  async query(filter = {}) {
-    const allDocuments = await this.getAll();
+  async query(filter = {}, { limit = 100, offset = 0, partition = null, partitionValues = {} } = {}) {
     if (Object.keys(filter).length === 0) {
-      return allDocuments;
-    }
-    return allDocuments.filter((doc) => {
-      return Object.entries(filter).every(([key, value]) => {
-        return doc[key] === value;
+      return await this.list({ partition, partitionValues, limit, offset });
+    }
+    const results = [];
+    let currentOffset = offset;
+    const batchSize = Math.min(limit, 50);
+    while (results.length < limit) {
+      const batch = await this.list({
+        partition,
+        partitionValues,
+        limit: batchSize,
+        offset: currentOffset
       });
-    });
+      if (batch.length === 0) {
+        break;
+      }
+      const filteredBatch = batch.filter((doc) => {
+        return Object.entries(filter).every(([key, value]) => {
+          return doc[key] === value;
+        });
+      });
+      results.push(...filteredBatch);
+      currentOffset += batchSize;
+      if (batch.length < batchSize) {
+        break;
+      }
+    }
+    return results.slice(0, limit);
   }
   /**
    * Update partition objects to keep them in sync
@@ -9727,7 +10077,7 @@ class Resource extends EventEmitter {
       return;
     }
     for (const [partitionName, partition] of Object.entries(partitions)) {
-      const partitionKey = this.getPartitionKey(partitionName, data.id, data);
+      const partitionKey = this.getPartitionKey({ partitionName, id: data.id, data });
       if (partitionKey) {
         const mappedData = await this.schema.mapper(data);
         const behaviorImpl = getBehavior(this.behavior);
@@ -9754,13 +10104,30 @@ class Resource extends EventEmitter {
     }
   }
   /**
-   * Get object directly from a specific partition
-   * @param {string} id - Resource ID
-   * @param {string} partitionName - Name of the partition
-   * @param {Object} partitionValues - Values for partition fields
-   * @returns {Object} The resource data
+   * Get a resource object directly from a specific partition
+   * @param {Object} params - Partition parameters
+   * @param {string} params.id - Resource ID
+   * @param {string} params.partitionName - Name of the partition
+   * @param {Object} params.partitionValues - Values for partition fields
+   * @returns {Promise<Object>} The resource object with partition metadata
+   * @example
+   * // Get user from UTM source partition
+   * const user = await resource.getFromPartition({
+   *   id: 'user-123',
+   *   partitionName: 'byUtmSource',
+   *   partitionValues: { 'utm.source': 'google' }
+   * });
+   * console.log(user._partition); // 'byUtmSource'
+   * console.log(user._partitionValues); // { 'utm.source': 'google' }
+   * 
+   * // Get product from multi-field partition
+   * const product = await resource.getFromPartition({
+   *   id: 'product-456',
+   *   partitionName: 'byCategoryRegion',
+   *   partitionValues: { category: 'electronics', region: 'US' }
+   * });
    */
-  async getFromPartition(id, partitionName, partitionValues = {}) {
+  async getFromPartition({ id, partitionName, partitionValues = {} }) {
     const partition = this.options.partitions[partitionName];
     if (!partition) {
       throw new Error(`Partition '${partitionName}' not found`);
@@ -9819,7 +10186,7 @@ class Database extends EventEmitter {
     this.version = "1";
     this.s3dbVersion = (() => {
       try {
-        return true ? "4.1.4" : "latest";
+        return true ? "4.1.7" : "latest";
       } catch (e) {
         return "latest";
       }