@stream44.studio/encapsulate 0.4.0-rc.13 → 0.4.0-rc.14

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stream44.studio/encapsulate",
-    "version": "0.4.0-rc.13",
+    "version": "0.4.0-rc.14",
     "license": "BSD-2-Clause-Patent",
     "repository": {
         "type": "git",

package/src/encapsulate.ts

@@ -103,11 +103,15 @@ type TSpineContext = {
 export const CapsulePropertyTypes = {
     Function: 'Function' as const,
     GetterFunction: 'GetterFunction' as const,
+    SetterFunction: 'SetterFunction' as const,
     String: 'String' as const,
     Mapping: 'Mapping' as const,
     Literal: 'Literal' as const,
     Constant: 'Constant' as const,
     StructInit: 'StructInit' as const,
+    StructDispose: 'StructDispose' as const,
+    Init: 'Init' as const,
+    Dispose: 'Dispose' as const,
 }
 
 // ##################################################
@@ -232,26 +236,57 @@ export async function SpineRuntime(options: TSpineRuntimeOptions): Promise<TSpin
                 }
             }
 
-            // Run StructInit functions for the entire capsule tree (top-down)
-            // Top-down means: child capsule's StructInit runs before extended parent's StructInit
+            // Run StructInit functions for struct capsules and Init functions for non-struct capsules
+            // StructInit: fires for struct-mapped capsules and any capsules they extend (top-down)
+            // Init: fires for non-struct capsules (those without StructInit)
             const structInitVisited = new Set<any>()
-            async function runStructInits(instance: any) {
+            const structInstances: any[] = []  // Track struct instances for StructDispose
+            const nonStructInstances: any[] = []  // Track non-struct instances for Dispose
+
+            async function runStructInits(instance: any, isStructContext: boolean = false) {
                 if (!instance || structInitVisited.has(instance)) return
                 structInitVisited.add(instance)
 
-                // Run this capsule's own StructInit functions first (top-down)
-                if (instance.structInitFunctions?.length) {
-                    for (const fn of instance.structInitFunctions) {
-                        await fn()
+                // Determine if this instance is a struct capsule (has StructInit functions)
+                const hasStructInit = instance.structInitFunctions?.length > 0
+                const isStruct = hasStructInit || isStructContext
+
+                if (isStruct) {
+                    // This is a struct capsule - run StructInit
+                    structInstances.push(instance)
+                    if (instance.structInitFunctions?.length) {
+                        for (const fn of instance.structInitFunctions) {
+                            await fn()
+                        }
+                        // Sync self values back to encapsulatedApi for spine contracts that use
+                        // direct assignment (e.g. Static contract) rather than getters
+                        if (instance.spineContractCapsuleInstances) {
+                            for (const sci of Object.values(instance.spineContractCapsuleInstances) as any[]) {
+                                if (sci.self && sci.encapsulatedApi) {
+                                    for (const key of Object.keys(sci.encapsulatedApi)) {
+                                        if (key in sci.self && sci.encapsulatedApi[key] !== sci.self[key]) {
+                                            sci.encapsulatedApi[key] = sci.self[key]
+                                        }
+                                    }
+                                }
+                            }
+                        }
                     }
-                    // Sync self values back to encapsulatedApi for spine contracts that use
-                    // direct assignment (e.g. Static contract) rather than getters
-                    if (instance.spineContractCapsuleInstances) {
-                        for (const sci of Object.values(instance.spineContractCapsuleInstances) as any[]) {
-                            if (sci.self && sci.encapsulatedApi) {
-                                for (const key of Object.keys(sci.encapsulatedApi)) {
-                                    if (key in sci.self && sci.encapsulatedApi[key] !== sci.self[key]) {
-                                        sci.encapsulatedApi[key] = sci.self[key]
+                } else {
+                    // This is a non-struct capsule - run Init
+                    nonStructInstances.push(instance)
+                    if (instance.initFunctions?.length) {
+                        for (const fn of instance.initFunctions) {
+                            await fn()
+                        }
+                        // Sync self values back to encapsulatedApi
+                        if (instance.spineContractCapsuleInstances) {
+                            for (const sci of Object.values(instance.spineContractCapsuleInstances) as any[]) {
+                                if (sci.self && sci.encapsulatedApi) {
+                                    for (const key of Object.keys(sci.encapsulatedApi)) {
+                                        if (key in sci.self && sci.encapsulatedApi[key] !== sci.self[key]) {
+                                            sci.encapsulatedApi[key] = sci.self[key]
+                                        }
                                     }
                                 }
                             }
@@ -259,15 +294,15 @@ export async function SpineRuntime(options: TSpineRuntimeOptions): Promise<TSpin
                     }
                 }
 
-                // Recurse into extended capsule instance
+                // Recurse into extended capsule instance (inherits struct context)
                 if (instance.extendedCapsuleInstance) {
-                    await runStructInits(instance.extendedCapsuleInstance)
+                    await runStructInits(instance.extendedCapsuleInstance, isStruct)
                 }
 
-                // Recurse into mapped capsule instances
+                // Recurse into mapped capsule instances (each determines its own struct status)
                 if (instance.mappedCapsuleInstances?.length) {
                     for (const mappedInstance of instance.mappedCapsuleInstances) {
-                        await runStructInits(mappedInstance)
+                        await runStructInits(mappedInstance, false)
                     }
                 }
             }
@@ -278,6 +313,38 @@ export async function SpineRuntime(options: TSpineRuntimeOptions): Promise<TSpin
 
             const result = await handler({ apis, capsules })
 
+            // Run StructDispose for struct capsules (reverse order - bottom-up)
+            for (let i = structInstances.length - 1; i >= 0; i--) {
+                const instance = structInstances[i]
+                if (instance.structDisposeFunctions?.length) {
+                    for (const fn of instance.structDisposeFunctions) {
+                        await fn()
+                    }
+                }
+            }
+
+            // Run Dispose for non-struct capsules (reverse order - bottom-up)
+            for (let i = nonStructInstances.length - 1; i >= 0; i--) {
+                const instance = nonStructInstances[i]
+                if (instance.disposeFunctions?.length) {
+                    for (const fn of instance.disposeFunctions) {
+                        await fn()
+                    }
+                }
+            }
+
+            // Clear all memoize timeouts to prevent memory leaks
+            for (const [, entry] of Object.entries(capsules)) {
+                const instance = (entry as any).instance
+                if (instance?.spineContractCapsuleInstances) {
+                    for (const sci of Object.values(instance.spineContractCapsuleInstances) as any[]) {
+                        if (typeof sci.clearMemoizeTimeouts === 'function') {
+                            sci.clearMemoizeTimeouts()
+                        }
+                    }
+                }
+            }
+
             return result
         },
 
@@ -750,6 +817,9 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     spineContractCapsuleInstances,
                     extendedCapsuleInstance,
                     structInitFunctions: [] as Array<() => any>,
+                    structDisposeFunctions: [] as Array<() => any>,
+                    initFunctions: [] as Array<() => any>,
+                    disposeFunctions: [] as Array<() => any>,
                     mappedCapsuleInstances: [] as Array<any>,
                     rootCapsule: resolvedRootCapsule
                 }
@@ -809,12 +879,21 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 }
                 ownSelf['#@stream44.studio/encapsulate/structs/Capsule'] = capsuleMetadataStruct
 
-                // Collect StructInit functions and mapped capsule instances from all spine contract capsule instances
+                // Collect lifecycle functions and mapped capsule instances from all spine contract capsule instances
                 for (const spineContractCapsuleInstance of Object.values(spineContractCapsuleInstances)) {
                     const sci = spineContractCapsuleInstance as any
                     if (sci.structInitFunctions?.length) {
                         capsuleInstance.structInitFunctions.push(...sci.structInitFunctions)
                     }
+                    if (sci.structDisposeFunctions?.length) {
+                        capsuleInstance.structDisposeFunctions.push(...sci.structDisposeFunctions)
+                    }
+                    if (sci.initFunctions?.length) {
+                        capsuleInstance.initFunctions.push(...sci.initFunctions)
+                    }
+                    if (sci.disposeFunctions?.length) {
+                        capsuleInstance.disposeFunctions.push(...sci.disposeFunctions)
+                    }
                     if (sci.mappedCapsuleInstances?.length) {
                         capsuleInstance.mappedCapsuleInstances.push(...sci.mappedCapsuleInstances)
                     }
@@ -953,7 +1032,10 @@ function relative(from: string, to: string): string {
 }
 
 function isObject(item: any): boolean {
-    return item && typeof item === 'object' && !Array.isArray(item)
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return false
+    // Only deep-merge plain objects — preserve instances like Map, Set, Date, etc.
+    const proto = Object.getPrototypeOf(item)
+    return proto === Object.prototype || proto === null
 }
 
 export function merge<T = any>(target: T, ...sources: any[]): T {

package/src/spine-contracts/CapsuleSpineContract.v0/Membrane.v0.ts

@@ -429,6 +429,25 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
     protected mapFunctionProperty({ property }: { property: any }) {
         const selfProxy = this.createSelfProxy()
         const boundFunction = property.definition.value.bind(selfProxy)
+        const memoizeOption = property.definition.memoize
+        const shouldMemoize = memoizeOption === true || typeof memoizeOption === 'number'
+        const memoizeTtl = typeof memoizeOption === 'number' ? memoizeOption : null
+        const cacheKey = `function:${property.name}`
+
+        // Helper to set up TTL expiration
+        const setupTtlExpiration = () => {
+            if (memoizeTtl !== null) {
+                // Clear any existing timeout for this key
+                if (this.memoizeTimeouts.has(cacheKey)) {
+                    clearTimeout(this.memoizeTimeouts.get(cacheKey))
+                }
+                const timeout = setTimeout(() => {
+                    this.memoizeCache.delete(cacheKey)
+                    this.memoizeTimeouts.delete(cacheKey)
+                }, memoizeTtl)
+                this.memoizeTimeouts.set(cacheKey, timeout)
+            }
+        }
 
         const valueKey = `__value_${property.name}`
         Object.defineProperty(this.encapsulatedApi, valueKey, {
@@ -441,6 +460,48 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         Object.defineProperty(this.encapsulatedApi, property.name, {
             get: () => {
                 return (...args: any[]) => {
+                    // Check memoize cache first (only for no-arg calls or first call)
+                    if (shouldMemoize && this.memoizeCache.has(cacheKey)) {
+                        const cachedResult = this.memoizeCache.get(cacheKey)
+
+                        const callEvent: any = {
+                            event: 'call',
+                            eventIndex: this.incrementEventIndex(),
+                            target: {
+                                capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
+                                spineContractCapsuleInstanceId: this.id,
+                                prop: property.name,
+                            },
+                            args,
+                            memoized: true
+                        }
+
+                        if (this.capsuleSourceNameRef) {
+                            callEvent.target.capsuleSourceNameRef = this.capsuleSourceNameRef
+                        }
+                        if (this.capsuleSourceNameRefHash) {
+                            callEvent.target.capsuleSourceNameRefHash = this.capsuleSourceNameRefHash
+                        }
+
+                        this.addCallerContextToEvent(callEvent)
+                        this.onMembraneEvent?.(callEvent)
+
+                        const resultEvent: any = {
+                            event: 'call-result',
+                            eventIndex: this.incrementEventIndex(),
+                            callEventIndex: callEvent.eventIndex,
+                            target: {
+                                spineContractCapsuleInstanceId: this.id,
+                            },
+                            result: cachedResult,
+                            memoized: true
+                        }
+
+                        this.onMembraneEvent?.(resultEvent)
+
+                        return cachedResult
+                    }
+
                     const callEvent: any = {
                         event: 'call',
                         eventIndex: this.incrementEventIndex(),
@@ -464,6 +525,12 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
 
                     const result = boundFunction(...args)
 
+                    // Store in memoize cache if memoize is enabled
+                    if (shouldMemoize) {
+                        this.memoizeCache.set(cacheKey, result)
+                        setupTtlExpiration()
+                    }
+
                     const resultEvent: any = {
                         event: 'call-result',
                         eventIndex: this.incrementEventIndex(),
@@ -487,12 +554,65 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
     protected mapGetterFunctionProperty({ property }: { property: any }) {
         const getterFn = property.definition.value
         const selfProxy = this.createSelfProxy()
+        const memoizeOption = property.definition.memoize
+        const shouldMemoize = memoizeOption === true || typeof memoizeOption === 'number'
+        const memoizeTtl = typeof memoizeOption === 'number' ? memoizeOption : null
+        const cacheKey = `getter:${property.name}`
+
+        // Helper to set up TTL expiration
+        const setupTtlExpiration = () => {
+            if (memoizeTtl !== null) {
+                // Clear any existing timeout for this key
+                if (this.memoizeTimeouts.has(cacheKey)) {
+                    clearTimeout(this.memoizeTimeouts.get(cacheKey))
+                }
+                const timeout = setTimeout(() => {
+                    this.memoizeCache.delete(cacheKey)
+                    this.memoizeTimeouts.delete(cacheKey)
+                }, memoizeTtl)
+                this.memoizeTimeouts.set(cacheKey, timeout)
+            }
+        }
 
         Object.defineProperty(this.encapsulatedApi, property.name, {
             get: () => {
+                // Check memoize cache first
+                if (shouldMemoize && this.memoizeCache.has(cacheKey)) {
+                    const cachedResult = this.memoizeCache.get(cacheKey)
+
+                    const event: any = {
+                        event: 'get',
+                        eventIndex: this.incrementEventIndex(),
+                        target: {
+                            capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
+                            spineContractCapsuleInstanceId: this.id,
+                            prop: property.name,
+                        },
+                        value: cachedResult,
+                        memoized: true
+                    }
+
+                    if (this.capsuleSourceNameRef) {
+                        event.target.capsuleSourceNameRef = this.capsuleSourceNameRef
+                    }
+                    if (this.capsuleSourceNameRefHash) {
+                        event.target.capsuleSourceNameRefHash = this.capsuleSourceNameRefHash
+                    }
+
+                    this.addCallerContextToEvent(event)
+                    this.onMembraneEvent?.(event)
+                    return cachedResult
+                }
+
                 // Call the getter function lazily when accessed with proper this context
                 const result = getterFn.call(selfProxy)
 
+                // Store in memoize cache if memoize is enabled
+                if (shouldMemoize) {
+                    this.memoizeCache.set(cacheKey, result)
+                    setupTtlExpiration()
+                }
+
                 const event: any = {
                     event: 'get',
                     eventIndex: this.incrementEventIndex(),
@@ -524,7 +644,16 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         if (this.ownSelf) {
             Object.defineProperty(this.ownSelf, property.name, {
                 get: () => {
-                    return getterFn.call(selfProxy)
+                    // For ownSelf, also respect memoization
+                    if (shouldMemoize && this.memoizeCache.has(cacheKey)) {
+                        return this.memoizeCache.get(cacheKey)
+                    }
+                    const result = getterFn.call(selfProxy)
+                    if (shouldMemoize) {
+                        this.memoizeCache.set(cacheKey, result)
+                        setupTtlExpiration()
+                    }
+                    return result
                 },
                 enumerable: true,
                 configurable: true

package/src/spine-contracts/CapsuleSpineContract.v0/Static.v0.ts

@@ -19,7 +19,12 @@ export class ContractCapsuleInstanceFactory {
     protected runtimeSpineContracts?: Record<string, any>
     protected capsuleInstance?: any
     public structInitFunctions: Array<() => any> = []
+    public structDisposeFunctions: Array<() => any> = []
+    public initFunctions: Array<() => any> = []
+    public disposeFunctions: Array<() => any> = []
     public mappedCapsuleInstances: Array<any> = []
+    protected memoizeCache: Map<string, any> = new Map()
+    protected memoizeTimeouts: Map<string, ReturnType<typeof setTimeout>> = new Map()
 
     constructor({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance, runtimeSpineContracts, capsuleInstance }: { spineContractUri: string, capsule: any, self: any, ownSelf?: any, encapsulatedApi: Record<string, any>, resolve?: (uri: string, parentFilepath: string) => Promise<string>, importCapsule?: (filepath: string) => Promise<any>, spineFilesystemRoot?: string, freezeCapsule?: (capsule: any) => Promise<any>, instanceRegistry?: CapsuleInstanceRegistry, extendedCapsuleInstance?: any, runtimeSpineContracts?: Record<string, any>, capsuleInstance?: any }) {
         this.spineContractUri = spineContractUri
@@ -50,8 +55,16 @@ export class ContractCapsuleInstanceFactory {
             this.mapFunctionProperty({ property })
         } else if (property.definition.type === CapsulePropertyTypes.GetterFunction) {
             this.mapGetterFunctionProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.SetterFunction) {
+            this.mapSetterFunctionProperty({ property })
         } else if (property.definition.type === CapsulePropertyTypes.StructInit) {
             this.mapStructInitProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.StructDispose) {
+            this.mapStructDisposeProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.Init) {
+            this.mapInitProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.Dispose) {
+            this.mapDisposeProperty({ property })
         }
     }
 
@@ -321,18 +334,82 @@ export class ContractCapsuleInstanceFactory {
     protected mapFunctionProperty({ property }: { property: any }) {
         const apiTarget = this.getApiTarget({ property })
         const selfProxy = this.createSelfProxy()
-        apiTarget[property.name] = property.definition.value.bind(selfProxy)
+        const boundFunction = property.definition.value.bind(selfProxy)
+        const memoizeOption = property.definition.memoize
+        const shouldMemoize = memoizeOption === true || typeof memoizeOption === 'number'
+        const memoizeTtl = typeof memoizeOption === 'number' ? memoizeOption : null
+        const cacheKey = `function:${property.name}`
+
+        if (shouldMemoize) {
+            // Wrap the function to support memoization
+            apiTarget[property.name] = (...args: any[]) => {
+                if (this.memoizeCache.has(cacheKey)) {
+                    return this.memoizeCache.get(cacheKey)
+                }
+                const result = boundFunction(...args)
+                this.memoizeCache.set(cacheKey, result)
+
+                // Set up TTL expiration if specified
+                if (memoizeTtl !== null) {
+                    // Clear any existing timeout for this key
+                    if (this.memoizeTimeouts.has(cacheKey)) {
+                        clearTimeout(this.memoizeTimeouts.get(cacheKey))
+                    }
+                    const timeout = setTimeout(() => {
+                        this.memoizeCache.delete(cacheKey)
+                        this.memoizeTimeouts.delete(cacheKey)
+                    }, memoizeTtl)
+                    this.memoizeTimeouts.set(cacheKey, timeout)
+                }
+
+                return result
+            }
+        } else {
+            apiTarget[property.name] = boundFunction
+        }
     }
 
     protected mapGetterFunctionProperty({ property }: { property: any }) {
         const apiTarget = this.getApiTarget({ property })
         const getterFn = property.definition.value
         const selfProxy = this.createSelfProxy()
+        const memoizeOption = property.definition.memoize
+        const shouldMemoize = memoizeOption === true || typeof memoizeOption === 'number'
+        const memoizeTtl = typeof memoizeOption === 'number' ? memoizeOption : null
+        const cacheKey = `getter:${property.name}`
+
+        // Helper to set up TTL expiration
+        const setupTtlExpiration = () => {
+            if (memoizeTtl !== null) {
+                // Clear any existing timeout for this key
+                if (this.memoizeTimeouts.has(cacheKey)) {
+                    clearTimeout(this.memoizeTimeouts.get(cacheKey))
+                }
+                const timeout = setTimeout(() => {
+                    this.memoizeCache.delete(cacheKey)
+                    this.memoizeTimeouts.delete(cacheKey)
+                }, memoizeTtl)
+                this.memoizeTimeouts.set(cacheKey, timeout)
+            }
+        }
 
         // Define a lazy getter that calls the function only when accessed with proper this context
         Object.defineProperty(apiTarget, property.name, {
             get: () => {
-                return getterFn.call(selfProxy)
+                // Check memoize cache first
+                if (shouldMemoize && this.memoizeCache.has(cacheKey)) {
+                    return this.memoizeCache.get(cacheKey)
+                }
+
+                const result = getterFn.call(selfProxy)
+
+                // Store in memoize cache if memoize is enabled
+                if (shouldMemoize) {
+                    this.memoizeCache.set(cacheKey, result)
+                    setupTtlExpiration()
+                }
+
+                return result
             },
             enumerable: true,
             configurable: true
@@ -343,7 +420,42 @@ export class ContractCapsuleInstanceFactory {
         if (this.ownSelf) {
             Object.defineProperty(this.ownSelf, property.name, {
                 get: () => {
-                    return getterFn.call(selfProxy)
+                    // For ownSelf, also respect memoization
+                    if (shouldMemoize && this.memoizeCache.has(cacheKey)) {
+                        return this.memoizeCache.get(cacheKey)
+                    }
+                    const result = getterFn.call(selfProxy)
+                    if (shouldMemoize) {
+                        this.memoizeCache.set(cacheKey, result)
+                        setupTtlExpiration()
+                    }
+                    return result
+                },
+                enumerable: true,
+                configurable: true
+            })
+        }
+    }
+
+    protected mapSetterFunctionProperty({ property }: { property: any }) {
+        const apiTarget = this.getApiTarget({ property })
+        const setterFn = property.definition.value
+        const selfProxy = this.createSelfProxy()
+
+        // Define a setter that calls the function when the property is assigned
+        Object.defineProperty(apiTarget, property.name, {
+            set: (value: any) => {
+                setterFn.call(selfProxy, value)
+            },
+            enumerable: true,
+            configurable: true
+        })
+
+        // Also define the setter on ownSelf so this.self.propertyName = value works
+        if (this.ownSelf) {
+            Object.defineProperty(this.ownSelf, property.name, {
+                set: (value: any) => {
+                    setterFn.call(selfProxy, value)
                 },
                 enumerable: true,
                 configurable: true
@@ -357,10 +469,35 @@ export class ContractCapsuleInstanceFactory {
         this.structInitFunctions.push(boundFunction)
     }
 
+    protected mapStructDisposeProperty({ property }: { property: any }) {
+        const selfProxy = this.createSelfProxy()
+        const boundFunction = property.definition.value.bind(selfProxy)
+        this.structDisposeFunctions.push(boundFunction)
+    }
+
+    protected mapInitProperty({ property }: { property: any }) {
+        const selfProxy = this.createSelfProxy()
+        const boundFunction = property.definition.value.bind(selfProxy)
+        this.initFunctions.push(boundFunction)
+    }
+
+    protected mapDisposeProperty({ property }: { property: any }) {
+        const selfProxy = this.createSelfProxy()
+        const boundFunction = property.definition.value.bind(selfProxy)
+        this.disposeFunctions.push(boundFunction)
+    }
+
     async freeze(options: any): Promise<any> {
         return this.freezeCapsule?.(options) || {}
     }
 
+    public clearMemoizeTimeouts() {
+        for (const timeout of this.memoizeTimeouts.values()) {
+            clearTimeout(timeout)
+        }
+        this.memoizeTimeouts.clear()
+    }
+
 }