@seedprotocol/sdk 0.7.9 → 0.7.10-next.1353.g74aeeed

package/dist/{Schema-J_1f6p0c.js → Schema-BMXRF4j9.js}

@@ -1,10 +1,10 @@
 import { setup, assign, createActor } from 'xstate';
-import { T as applyContextUpdate, U as isInternalUpdate, V as evictionLog, W as holdChild, X as isEntityTornDown, Y as sameEntity, Z as DEFAULT_READY_TIMEOUT_MS, _ as waitForEntityReady, $ as createReactiveProxy, a0 as runEntityLoad, a1 as evictEntities, a2 as entityStatus, a3 as releaseEntity, a4 as destroyEntity, a5 as EntityCache } from './Item-Bf4kWKpH.js';
-import { SchemaValidationService } from './SchemaValidationService-CnmKyzR-.js';
-import { m as listLatestSchemaFiles, n as readSchemaFile, o as applySchemaFile, p as resolveSchemaRow, S as SCHEMA_FILE_FORMAT, q as loadAllSchemasFromDb, M as Model, u as getDraftSaveError, C as ConflictError, w as writeNextSchemaVersion, v as queueDraftSave, x as setupEntityLiveQuery, y as mergeSchemaFiles, z as trackDraftSave } from './errors-DLSoqSHG.js';
-import { B as BaseDb, t as schemas, d as models, j as modelSchemas, l as properties, w as BaseFileManager } from './BaseFileManager-BAlySv8w.js';
+import { T as applyContextUpdate, U as isInternalUpdate, V as evictionLog, W as holdChild, X as isEntityTornDown, Y as sameEntity, Z as DEFAULT_READY_TIMEOUT_MS, _ as createReactiveProxy, $ as runEntityLoad, a0 as waitForEntityReady, a1 as evictEntities, a2 as EntityUnloadedError, a3 as entityStatus, a4 as releaseEntity, a5 as destroyEntity, a6 as EntityCache } from './Item-oPnmIehk.js';
+import { SchemaValidationService } from './SchemaValidationService-CieGrj5c.js';
+import { m as listLatestSchemaFiles, n as readSchemaFile, o as applySchemaFile, p as resolveSchemaRow, S as SCHEMA_FILE_FORMAT, q as loadAllSchemasFromDb, M as Model, u as getDraftSaveError, C as ConflictError, w as writeNextSchemaVersion, v as queueDraftSave, x as setupEntityLiveQuery, y as mergeSchemaFiles, z as trackDraftSave } from './errors-CnT0fSMK.js';
+import { B as BaseDb, t as schemas, d as models, j as modelSchemas, l as properties, w as BaseFileManager } from './BaseFileManager-DLou1TZS.js';
 import { eq, desc, and, inArray } from 'drizzle-orm';
-import { S as SEED_PROTOCOL_SCHEMA_NAME, I as INTERNAL_SCHEMA_IDS, m as generateId, o as addSchemaToDb, p as isInternalSchema, q as inDefinitionsTransaction, s as isClientReady, u as upsertSchemaRow, t as broadcastSchemasInvalidate } from './tabEvents-CaVmngqr.js';
+import { S as SEED_PROTOCOL_SCHEMA_NAME, I as INTERNAL_SCHEMA_IDS, m as generateId, o as addSchemaToDb, p as isInternalSchema, q as inDefinitionsTransaction, s as isClientReady, u as upsertSchemaRow, t as broadcastSchemasInvalidate } from './tabEvents-DT5ez6io.js';
 import '@seedprotocol/arweave';
 import 'pluralize';
 import '@seedprotocol/eas';
@@ -196,7 +196,7 @@ const createModelInstances = async (modelIds, since, owner) => {
         return;
     }
     try {
-        const _mod_0 = await import('./errors-DLSoqSHG.js');
+        const _mod_0 = await import('./errors-CnT0fSMK.js');
         const _ns_0 = _mod_0.a4;
         const mod = _ns_0;
         const Model = mod?.Model ?? mod?.default;
@@ -207,7 +207,7 @@ const createModelInstances = async (modelIds, since, owner) => {
         const createPromises = modelIds.map(async (modelFileId) => {
             try {
                 // Not if the schema was evicted (Schema.destroy, test cleanup) since this check started
-                const model = await Model.createById(modelFileId, { since, hold: false });
+                const model = await Model.createById(modelFileId, { since });
                 if (model && owner)
                     holdChild(owner, model, Model.cache);
                 if (model) {
@@ -248,7 +248,7 @@ const findSchemaRow = async (db, schemaName) => {
  */
 const createSchema = async (schemaName) => {
     if (schemaName === SEED_PROTOCOL_SCHEMA_NAME) {
-        const _mod_1 = await import('./errors-DLSoqSHG.js');
+        const _mod_1 = await import('./errors-CnT0fSMK.js');
         const _ns_1 = _mod_1.a6;
         const internalSchema = _ns_1;
         const { schemaFile, schemaRecord } = await applySchemaFile(internalSchema.default, {
@@ -393,7 +393,7 @@ class Schema {
         }
         const waitForReady = options?.waitForReady !== false;
         const readyTimeout = options?.readyTimeout ?? DEFAULT_READY_TIMEOUT_MS;
-        const holds = options?.hold === false ? 0 : 1;
+        const holds = options?.hold === true;
         // Cached under this name (or file id)
         const cached = this.cache.peek(schemaName);
         if (cached) {
@@ -401,7 +401,7 @@ class Schema {
                 this.cache.holdInstance(cached);
             if (!waitForReady)
                 return cached;
-            return waitForEntityReady(cached, { timeout: readyTimeout }).then(() => cached);
+            return Schema.readyOrRelease(cached, readyTimeout, holds);
         }
         // Create new instance
         const newInstance = new this(schemaName);
@@ -446,6 +446,7 @@ class Schema {
                 };
             },
             sendUpdate: (instance, prop, value) => {
+                instance._assertLoaded(`set ${prop} on`);
                 // Handle special property updates
                 if (prop === 'name') {
                     // Update both metadata.name and schemaName
@@ -533,26 +534,43 @@ class Schema {
                 }
             },
         });
-        this.cache.add(proxiedInstance, [schemaName], { hold: holds === 1 });
+        this.cache.add(proxiedInstance, [schemaName], { hold: holds });
         void runEntityLoad(proxiedInstance, () => Schema.load(proxiedInstance));
         if (!waitForReady)
             return proxiedInstance;
-        return waitForEntityReady(proxiedInstance, { timeout: readyTimeout }).then(() => proxiedInstance);
+        return Schema.readyOrRelease(proxiedInstance, readyTimeout, holds);
+    }
+    /** The schema once ready; a call that took a hold gives it back when the schema isn't ready in time. */
+    static async readyOrRelease(schema, timeout, held) {
+        try {
+            await waitForEntityReady(schema, { timeout });
+        }
+        catch (error) {
+            if (held)
+                schema.unload();
+            throw error;
+        }
+        return schema;
     }
     /**
-     * Get schema instance by schemaFileId (preferred method)
-     * Returns null if not found in cache
+     * The cached schema with this file id, or null. Takes no hold unless `hold: true`.
      */
-    static getById(schemaFileId) {
-        return this.cache.hold(schemaFileId) ?? null;
+    static getById(schemaFileId, options) {
+        return (options?.hold ? this.cache.hold(schemaFileId) : this.cache.peek(schemaFileId)) ?? null;
     }
     /**
-     * The cached schema with this file id or name, without taking a hold. For SDK code that reads
-     * the schema and doesn't hand it to a caller; callers that keep it use `create` or `find`.
+     * The cached schema with this file id or name, without taking a hold.
      */
     static peek(schemaFileIdOrName) {
         return this.cache.peek(schemaFileIdOrName);
     }
+    /**
+     * Takes one more hold on a cached, running instance, released with `unload()`. False (and no
+     * hold) when the instance isn't cached or was stopped.
+     */
+    static retain(instance) {
+        return instance.getService().getSnapshot().status === 'active' && this.cache.holdInstance(instance);
+    }
     /** Stop and drop every cached Schema, whoever holds it (test cleanup). */
     static clearCache() {
         evictEntities(this.cache, () => true);
@@ -561,16 +579,14 @@ class Schema {
      * Create or get schema instance by schemaFileId
      * Queries the database to find the schema name if not cached
      * @param schemaFileId - The schema file ID
-     * @returns Schema instance, with a hold taken (unless `hold: false`)
+     * @returns Schema instance, with no hold unless `hold: true`
      */
-    static async createById(schemaFileId, 
-    /** @internal `hold: false` as for `create` */
-    options) {
+    static async createById(schemaFileId, options) {
         if (!schemaFileId) {
             throw new Error('Schema file ID is required');
         }
         // First, check if we have an instance cached by ID
-        const cachedInstance = options?.hold === false ? this.peek(schemaFileId) : this.getById(schemaFileId);
+        const cachedInstance = this.getById(schemaFileId, options);
         if (cachedInstance) {
             return cachedInstance;
         }
@@ -594,35 +610,38 @@ class Schema {
             throw new Error(`Schema with ID "${schemaFileId}" has no name in database`);
         }
         // Create schema using the name (this will load from database/file)
-        return this.create(schemaName, options?.hold === false ? { hold: false } : undefined);
+        return this.create(schemaName, options);
     }
     /**
      * Find a schema by schemaFileId or by name. Read-only: a name with no schema row gives undefined
      * and creates nothing (`Schema.create` creates a draft for an unknown name). By name, the cached
      * instance is used, else the stored schema is loaded. Waits for the schema to be fully loaded
-     * (idle state) by default. Takes a hold unless `hold: false`.
+     * (idle state) by default. Takes no hold unless `hold: true`.
      * @returns Schema instance if found, undefined otherwise
      */
-    static async find({ schemaFileId, schemaName, waitForReady = true, readyTimeout = DEFAULT_READY_TIMEOUT_MS, hold, }) {
+    static async find({ schemaFileId, schemaName, waitForReady = true, readyTimeout = DEFAULT_READY_TIMEOUT_MS, hold = false, }) {
         if (schemaName) {
             return this.findByName(schemaName, { waitForReady, readyTimeout, hold });
         }
         if (!schemaFileId) {
             return undefined;
         }
+        let schema;
         try {
-            const schema = (hold === false ? Schema.peek(schemaFileId) : (Schema.getById(schemaFileId) ?? undefined)) ??
-                (await Schema.createById(schemaFileId, hold === false ? { hold: false } : undefined));
+            schema = await Schema.createById(schemaFileId, { hold });
             if (waitForReady)
                 await waitForEntityReady(schema, { timeout: readyTimeout });
             return schema;
         }
         catch {
+            // Keeps no hold when it returns nothing
+            if (hold)
+                schema?.unload();
             return undefined;
         }
     }
     static async findByName(schemaName, options) {
-        const createOptions = { readyTimeout: options.readyTimeout, ...(options.hold === false && { hold: false }) };
+        const createOptions = { readyTimeout: options.readyTimeout, hold: options.hold };
         const loadOrCached = () => options.waitForReady
             ? this.create(schemaName, { ...createOptions, waitForReady: true })
             : this.create(schemaName, { ...createOptions, waitForReady: false });
@@ -644,7 +663,7 @@ class Schema {
      * Get instantiated Schema objects for all schemas (from database and files)
      * By default, returns only the latest version of each schema and excludes the internal Seed Protocol schema.
      * Uses loadAllSchemasFromDb() as the single source of truth, which intelligently merges database and file data.
-     * Takes no holds on the instances it returns: a caller that keeps one uses `Schema.create` or `Schema.find`.
+     * Takes no holds unless `hold: true`.
      *
      * @param options - Configuration options
      * @param options.includeAllVersions - If true, returns all versions of each schema. Default: false
@@ -652,7 +671,7 @@ class Schema {
      * @returns Array of Schema instances
      */
     static async all(options = {}) {
-        const { includeAllVersions = false, includeInternal = false, waitForReady = false, readyTimeout = DEFAULT_READY_TIMEOUT_MS, } = options;
+        const { includeAllVersions = false, includeInternal = false, waitForReady = false, readyTimeout = DEFAULT_READY_TIMEOUT_MS, hold = false, } = options;
         // Use loadAllSchemasFromDb as single source of truth
         // This intelligently merges database and file data, including drafts
         const allSchemasData = await loadAllSchemasFromDb();
@@ -702,8 +721,7 @@ class Schema {
             }
             processedSchemaNames.add(schemaName);
             // Try to use schemaFileId to ensure we load the correct version
-            // First check if we have a cached instance by schemaFileId. Schema.all takes no holds: it
-            // lists schemas (useSchemas caches the list and never unloads it).
+            // First check if we have a cached instance by schemaFileId
             if (schemaFileId) {
                 const cachedById = this.peek(schemaFileId);
                 if (cachedById) {
@@ -730,23 +748,35 @@ class Schema {
             // But to ensure we get the correct version, we'll use createById if we have the schemaFileId
             if (schemaFileId) {
                 try {
-                    const instance = await this.createById(schemaFileId, { hold: false });
+                    const instance = await this.createById(schemaFileId);
                     schemaInstances.push(instance);
                 }
                 catch {
                     // Fallback to creating by name if createById fails
-                    schemaInstances.push(this.create(schemaName, { waitForReady: false, hold: false }));
+                    schemaInstances.push(this.create(schemaName, { waitForReady: false }));
                 }
             }
             else {
-                schemaInstances.push(this.create(schemaName, { waitForReady: false, hold: false }));
+                schemaInstances.push(this.create(schemaName, { waitForReady: false }));
             }
         }
         if (waitForReady && schemaInstances.length > 0) {
             await Promise.all(schemaInstances.map((schema) => waitForEntityReady(schema, { timeout: readyTimeout })));
         }
+        // Once nothing can throw, so a failed call keeps no holds
+        if (hold)
+            for (const schema of schemaInstances)
+                this.cache.holdInstance(schema);
         return schemaInstances;
     }
+    /** Throws EntityUnloadedError, naming the schema, when this instance was destroyed or evicted. */
+    _assertLoaded(action) {
+        if (!isEntityTornDown(this))
+            return;
+        const { schemaName, metadata, id } = this._getSnapshotContext();
+        throw new EntityUnloadedError(`Cannot ${action} schema ${metadata?.name ?? schemaName ?? '?'} (${id ?? 'no id'}): this Schema instance was ` +
+            'destroyed or evicted. Look the schema up again (Schema.find).');
+    }
     getService() {
         return this._service;
     }
@@ -874,8 +904,8 @@ class Schema {
      */
     async _buildModelsFromInstances() {
         const context = this._getSnapshotContext();
-        const _mod_2 = await import('./index-DmTtj1nk.js');
-        const _ns_2 = _mod_2.j;
+        const _mod_2 = await import('./index-Gh42_47r.js');
+        const _ns_2 = _mod_2.k;
         const { convertPropertyToSchemaUpdate } = _ns_2;
         const models = {};
         for (const modelInstance of this.models) {
@@ -890,7 +920,7 @@ class Schema {
                 const modelDbId = modelInstance.getService().getSnapshot().context._dbId;
                 const db = BaseDb.getAppDb();
                 if (propertyContexts.length === 0 && modelDbId && db) {
-                    const { ModelProperty } = await import('./ModelProperty-BlaEgb_U.js');
+                    const { ModelProperty } = await import('./ModelProperty-D2vJozmW.js');
                     const rows = await db.select().from(properties).where(eq(properties.modelId, modelDbId));
                     propertyContexts = rows.map((row) => {
                         const cached = row.schemaFileId ? ModelProperty.getById(row.schemaFileId) : undefined;
@@ -951,6 +981,7 @@ class Schema {
      * @returns The file path of the new schema version
      */
     async saveNewVersion() {
+        this._assertLoaded('save a new version of');
         // Check for conflicts before saving
         const conflictCheck = await this._checkForConflicts();
         if (conflictCheck.hasConflict) {
@@ -1019,7 +1050,7 @@ class Schema {
         });
         // Clear edited flags on the cached ModelProperty instances of the edited keys, then on the rows
         // (schema, those properties, the schema's models) in one transaction.
-        const { ModelProperty } = await import('./ModelProperty-BlaEgb_U.js');
+        const { ModelProperty } = await import('./ModelProperty-D2vJozmW.js');
         const thisSchemaName = this.schemaName;
         const clearedKeys = [];
         for (const propertyKey of context._editedProperties) {
@@ -1038,8 +1069,8 @@ class Schema {
             cachedInstance.getService().send({ type: 'clearEdited' });
             clearedKeys.push({ modelName, propertyName });
         }
-        const _mod_3 = await import('./tabEvents-CaVmngqr.js');
-        const _ns_3 = _mod_3.be;
+        const _mod_3 = await import('./tabEvents-DT5ez6io.js');
+        const _ns_3 = _mod_3.bh;
         const { resolveModelRecord } = _ns_3;
         await inDefinitionsTransaction(async (tx) => {
             await tx
@@ -1124,6 +1155,7 @@ class Schema {
      * This refreshes the actor context with the latest data from the database
      */
     async reload() {
+        this._assertLoaded('reload');
         logger(`Reloading schema ${this.schemaName} from database`);
         await runEntityLoad(this, () => Schema.load(this));
         if (this.status === 'error')
@@ -1283,8 +1315,8 @@ class Schema {
         evictEntities(this.cache, (schema) => schema._getSnapshotContext().schemaName === schemaName);
     }
     /**
-     * Release this caller's hold. With the last one the schema is stopped, leaves the cache, and
-     * releases its hold on each of its models.
+     * Release this caller's hold, if it took one. The schema stays cached (see `Schema.cache`); only
+     * `destroy`, eviction or client stop stop it.
      */
     unload() {
         releaseEntity(this, Schema.cache);
@@ -1315,10 +1347,10 @@ class Schema {
         // instances too, or a re-import would get them back with dangling _dbIds.
         if (schemaName) {
             const evictedModelNames = Model.evictForSchema(schemaName);
-            const { ModelProperty } = await import('./ModelProperty-BlaEgb_U.js');
+            const { ModelProperty } = await import('./ModelProperty-D2vJozmW.js');
             ModelProperty.evictForModels(evictedModelNames, schemaName);
             // Evicting stops new writes but not ones already running; let those land before deleting their rows
-            const _mod_4 = await import('./errors-DLSoqSHG.js');
+            const _mod_4 = await import('./errors-CnT0fSMK.js');
             const _ns_4 = _mod_4.a3;
             const { waitForInFlightWrites } = _ns_4;
             await waitForInFlightWrites();
@@ -1327,7 +1359,7 @@ class Schema {
             const db = BaseDb.getAppDb();
             if (!db || !schemaFileId)
                 return;
-            const { detachModelRows } = await import('./detachRowsBeforeDelete-sEaUwlOU.js');
+            const { detachModelRows } = await import('./detachRowsBeforeDelete-BZr_0iZU.js');
             // The schema's rows go together or not at all
             const deleted = await inDefinitionsTransaction(async (tx) => {
                 const schemaRecords = await tx
@@ -1368,7 +1400,7 @@ class Schema {
             // the destroyed schema back on the next Schema.all().
             // Match on name as well as id: versions imported from complete schema files can each
             // have their own id, and any version left behind would bring the schema back.
-            const _mod_5 = await import('./errors-DLSoqSHG.js');
+            const _mod_5 = await import('./errors-CnT0fSMK.js');
             const _ns_5 = _mod_5.a5;
             const { listCompleteSchemaFiles } = _ns_5;
             const files = await listCompleteSchemaFiles().catch(() => []);
@@ -1416,7 +1448,7 @@ class Schema {
                 // One at a time: an eviction of this schema part way through stops the rest
                 const since = evictionLog.now();
                 for (const id of ids) {
-                    await Model.createById(id, { since, hold: false });
+                    await Model.createById(id, { since });
                 }
             },
             queryInitialData: async (schemaId) => {
@@ -1444,8 +1476,12 @@ class Schema {
         });
     }
 }
-/** Cached under its file id and its name (ADR 0014). */
-Schema.cache = new EntityCache();
+/**
+ * Cached under its file id and its name (ADR 0014). A schema stays cached with no holds until it
+ * is destroyed or evicted, or the client stops (`unloadUnheld: false`): sync and name matching
+ * read the cached definitions synchronously.
+ */
+Schema.cache = new EntityCache({ unloadUnheld: false });
 
 var Schema$1 = /*#__PURE__*/Object.freeze({
     __proto__: null,
@@ -1453,4 +1489,4 @@ var Schema$1 = /*#__PURE__*/Object.freeze({
 });
 
 export { Schema as S, Schema$1 as a, schemaMachine as s };
-//# sourceMappingURL=Schema-J_1f6p0c.js.map
+//# sourceMappingURL=Schema-BMXRF4j9.js.map