s3db.js 4.1.6 → 4.1.8

package/dist/s3db.iife.js

@@ -8560,6 +8560,14 @@ ${JSON.stringify(validation, null, 2)}`
     }
     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 "";
@@ -8594,49 +8602,31 @@ ${JSON.stringify(validation, null, 2)}`
     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: "" };
   }
@@ -8644,33 +8634,53 @@ ${JSON.stringify(validation, null, 2)}`
     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: "" };
   }
@@ -8678,7 +8688,7 @@ ${JSON.stringify(validation, null, 2)}`
     return { metadata, body };
   }
 
-  var enforceLimits = /*#__PURE__*/Object.freeze({
+  var userManagement = /*#__PURE__*/Object.freeze({
     __proto__: null,
     handleGet: handleGet$2,
     handleInsert: handleInsert$2,
@@ -8686,7 +8696,6 @@ ${JSON.stringify(validation, null, 2)}`
     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 }) {
@@ -8707,7 +8716,7 @@ ${JSON.stringify(validation, null, 2)}`
     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;
@@ -8727,7 +8736,7 @@ ${JSON.stringify(validation, null, 2)}`
           }
         }
         result[key] = truncatedValue + TRUNCATE_SUFFIX;
-        currentSize = S3_METADATA_LIMIT_BYTES$1;
+        currentSize = S3_METADATA_LIMIT_BYTES;
         break;
       } else {
         break;
@@ -8744,7 +8753,6 @@ ${JSON.stringify(validation, null, 2)}`
     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);
@@ -9087,13 +9095,29 @@ ${JSON.stringify(validation, null, 2)}`
       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`);
@@ -9124,15 +9148,36 @@ ${JSON.stringify(validation, null, 2)}`
         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();
@@ -9171,39 +9216,68 @@ ${JSON.stringify(validation, null, 2)}`
       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);
@@ -9213,6 +9287,24 @@ ${JSON.stringify(validation, null, 2)}`
         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) {
@@ -9269,6 +9361,14 @@ ${JSON.stringify(validation, null, 2)}`
       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 {
@@ -9283,6 +9383,20 @@ ${JSON.stringify(validation, null, 2)}`
       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) {
@@ -9290,6 +9404,28 @@ ${JSON.stringify(validation, null, 2)}`
       }
       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) {
@@ -9320,6 +9456,19 @@ ${JSON.stringify(validation, null, 2)}`
       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.PromisePool.for(objects).withConcurrency(this.parallelism).handleError(async (error, content) => {
         this.emit("error", error, content);
@@ -9331,6 +9480,15 @@ ${JSON.stringify(validation, null, 2)}`
       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 = lodashEs.chunk(
         ids.map((id) => this.getResourceKey(id)),
@@ -9389,7 +9547,35 @@ ${JSON.stringify(validation, null, 2)}`
       });
       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];
@@ -9413,8 +9599,11 @@ ${JSON.stringify(validation, null, 2)}`
       } 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("/");
@@ -9425,13 +9614,36 @@ ${JSON.stringify(validation, null, 2)}`
       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);
@@ -9441,7 +9653,7 @@ ${JSON.stringify(validation, null, 2)}`
         const { results: results2 } = await promisePool.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];
@@ -9474,11 +9686,19 @@ ${JSON.stringify(validation, null, 2)}`
         filteredIds = filteredIds.slice(0, limit);
       }
       const { results } = await promisePool.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.PromisePool.for(ids).withConcurrency(this.client.parallelism).process(async (id) => {
         this.emit("id", id);
@@ -9489,6 +9709,13 @@ ${JSON.stringify(validation, null, 2)}`
       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 [];
@@ -9499,20 +9726,65 @@ ${JSON.stringify(validation, null, 2)}`
       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;
@@ -9526,36 +9798,62 @@ ${JSON.stringify(validation, null, 2)}`
       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);
@@ -9650,7 +9948,7 @@ ${JSON.stringify(validation, null, 2)}`
         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);
@@ -9682,7 +9980,7 @@ ${JSON.stringify(validation, null, 2)}`
       }
       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);
         }
@@ -9696,20 +9994,72 @@ ${JSON.stringify(validation, null, 2)}`
       }
     }
     /**
-     * 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
@@ -9721,7 +10071,7 @@ ${JSON.stringify(validation, null, 2)}`
         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);
@@ -9748,13 +10098,30 @@ ${JSON.stringify(validation, null, 2)}`
       }
     }
     /**
-     * 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`);
@@ -9813,7 +10180,7 @@ ${JSON.stringify(validation, null, 2)}`
       this.version = "1";
       this.s3dbVersion = (() => {
         try {
-          return true ? "4.1.4" : "latest";
+          return true ? "4.1.7" : "latest";
         } catch (e) {
           return "latest";
         }