s3db.js 4.1.2 → 4.1.4

package/README.md

@@ -830,6 +830,48 @@ const resource = await s3db.createResource({
 });
 ```
 
+#### Check Resource Existence
+
+```javascript
+// Check if a resource exists by name
+const exists = s3db.resourceExists("users");
+console.log(exists); // true or false
+```
+
+#### Create Resource If Not Exists
+
+```javascript
+// Create a resource only if it doesn't exist with the same definition hash
+const result = await s3db.createResourceIfNotExists({
+  name: "users",
+  attributes: {
+    name: "string|required",
+    email: "email|required"
+  },
+  options: { timestamps: true },
+  behavior: "user-management"
+});
+
+console.log(result);
+// {
+//   resource: Resource,
+//   created: true, // or false if already existed
+//   reason: "New resource created" // or "Resource already exists with same definition hash"
+// }
+
+// If the resource already exists with the same hash, it returns the existing resource
+const result2 = await s3db.createResourceIfNotExists({
+  name: "users",
+  attributes: {
+    name: "string|required",
+    email: "email|required"
+  }
+});
+
+console.log(result2.created); // false
+console.log(result2.reason); // "Resource already exists with same definition hash"
+```
+
 #### Get Resource Reference
 
 ```javascript

package/dist/s3db.cjs.js

@@ -3482,6 +3482,7 @@ class Schema {
     this.attributes = attributes || {};
     this.passphrase = passphrase ?? "secret";
     this.options = lodashEs.merge({}, this.defaultOptions(), options);
+    this.allNestedObjectsOptional = this.options.allNestedObjectsOptional ?? false;
     const processedAttributes = this.preprocessAttributesForValidation(this.attributes);
     this.validator = new ValidatorManager({ autoEncrypt: false }).compile(lodashEs.merge(
       { $$async: true },
@@ -3679,11 +3680,17 @@ class Schema {
     const processed = {};
     for (const [key, value] of Object.entries(attributes)) {
       if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-        processed[key] = {
+        const isExplicitRequired = value.$$type && value.$$type.includes("required");
+        const isExplicitOptional = value.$$type && value.$$type.includes("optional");
+        const objectConfig = {
           type: "object",
           properties: this.preprocessAttributesForValidation(value),
           strict: false
         };
+        if (isExplicitRequired) ; else if (isExplicitOptional || this.allNestedObjectsOptional) {
+          objectConfig.optional = true;
+        }
+        processed[key] = objectConfig;
       } else {
         processed[key] = value;
       }
@@ -8845,6 +8852,7 @@ class Resource extends EventEmitter {
       partitions: {},
       paranoid: true,
       // Security flag for dangerous operations
+      allNestedObjectsOptional: options.allNestedObjectsOptional ?? false,
       ...options
     };
     this.hooks = {
@@ -8879,7 +8887,10 @@ class Resource extends EventEmitter {
       attributes: this.attributes,
       passphrase,
       version: this.version,
-      options: this.options
+      options: {
+        ...this.options,
+        allNestedObjectsOptional: this.options.allNestedObjectsOptional ?? false
+      }
     });
     this.validatePartitions();
     this.setupPartitionHooks();
@@ -9806,7 +9817,7 @@ class Database extends EventEmitter {
     this.version = "1";
     this.s3dbVersion = (() => {
       try {
-        return true ? "4.1.1" : "latest";
+        return true ? "4.1.3" : "latest";
       } catch (e) {
         return "latest";
       }
@@ -9918,16 +9929,21 @@ class Database extends EventEmitter {
   /**
    * Generate a consistent hash for a resource definition
    * @param {Object} definition - Resource definition to hash
+   * @param {string} behavior - Resource behavior
    * @returns {string} SHA256 hash
    */
-  generateDefinitionHash(definition) {
+  generateDefinitionHash(definition, behavior = void 0) {
     const attributes = definition.attributes;
     const stableAttributes = { ...attributes };
     if (definition.options?.timestamps) {
       delete stableAttributes.createdAt;
       delete stableAttributes.updatedAt;
     }
-    const stableString = jsonStableStringify(stableAttributes);
+    const hashObj = {
+      attributes: stableAttributes,
+      behavior: behavior || definition.behavior || "user-management"
+    };
+    const stableString = jsonStableStringify(hashObj);
     return `sha256:${crypto.createHash("sha256").update(stableString).digest("hex")}`;
   }
   /**
@@ -10014,6 +10030,73 @@ class Database extends EventEmitter {
       resources: {}
     };
   }
+  /**
+   * Check if a resource exists by name
+   * @param {string} name - Resource name
+   * @returns {boolean} True if resource exists, false otherwise
+   */
+  resourceExists(name) {
+    return !!this.resources[name];
+  }
+  /**
+   * Check if a resource exists with the same definition hash
+   * @param {string} name - Resource name
+   * @param {Object} attributes - Resource attributes
+   * @param {Object} options - Resource options
+   * @param {string} behavior - Resource behavior
+   * @returns {Object} Object with exists flag and hash information
+   */
+  resourceExistsWithSameHash({ name, attributes, options = {}, behavior = "user-management" }) {
+    if (!this.resources[name]) {
+      return { exists: false, sameHash: false, hash: null };
+    }
+    const tempResource = new Resource({
+      name,
+      attributes,
+      behavior,
+      observers: [],
+      client: this.client,
+      version: "temp",
+      options: {
+        cache: this.cache,
+        ...options
+      }
+    });
+    const newHash = this.generateDefinitionHash(tempResource.export(), behavior);
+    const existingHash = this.generateDefinitionHash(this.resources[name].export(), this.resources[name].behavior);
+    return {
+      exists: true,
+      sameHash: newHash === existingHash,
+      hash: newHash,
+      existingHash
+    };
+  }
+  /**
+   * Create a resource only if it doesn't exist with the same definition hash
+   * @param {Object} params - Resource parameters
+   * @param {string} params.name - Resource name
+   * @param {Object} params.attributes - Resource attributes
+   * @param {Object} params.options - Resource options
+   * @param {string} params.behavior - Resource behavior
+   * @returns {Object} Object with resource and created flag
+   */
+  async createResourceIfNotExists({ name, attributes, options = {}, behavior = "user-management" }) {
+    const alreadyExists = !!this.resources[name];
+    const hashCheck = this.resourceExistsWithSameHash({ name, attributes, options, behavior });
+    if (hashCheck.exists && hashCheck.sameHash) {
+      return {
+        resource: this.resources[name],
+        created: false,
+        reason: "Resource already exists with same definition hash"
+      };
+    }
+    const resource = await this.createResource({ name, attributes, options, behavior });
+    return {
+      resource,
+      created: !alreadyExists,
+      reason: alreadyExists ? "Resource updated with new definition" : "New resource created"
+    };
+  }
   async createResource({ name, attributes, options = {}, behavior = "user-management" }) {
     if (this.resources[name]) {
       const existingResource = this.resources[name];
@@ -10025,7 +10108,13 @@ class Database extends EventEmitter {
         existingResource.behavior = behavior;
       }
       existingResource.updateAttributes(attributes);
-      await this.uploadMetadataFile();
+      const newHash = this.generateDefinitionHash(existingResource.export(), existingResource.behavior);
+      const existingMetadata2 = this.savedMetadata?.resources?.[name];
+      const currentVersion = existingMetadata2?.currentVersion || "v0";
+      const existingVersionData = existingMetadata2?.versions?.[currentVersion];
+      if (!existingVersionData || existingVersionData.hash !== newHash) {
+        await this.uploadMetadataFile();
+      }
       this.emit("s3db.resourceUpdated", name);
       return existingResource;
     }