@stream44.studio/encapsulate 0.2.0-rc.2 → 0.2.0-rc.4

package/src/encapsulate.ts

@@ -43,7 +43,8 @@ type TCapsuleSnapshot = {
 type TCapsuleMakeInstanceOptions = {
     overrides?: Record<string, any>,
     options?: Record<string, any>,
-    runtimeSpineContracts?: Record<string, any>
+    runtimeSpineContracts?: Record<string, any>,
+    sharedSelf?: Record<string, any>
 }
 
 type TCapsule = {
@@ -69,6 +70,7 @@ type TCapsuleOptions = {
     moduleFilepath?: string,
     capsuleName?: string,
     ambientReferences?: Record<string, any>,
+    extendsCapsule?: TCapsule | string,
     cst?: any,
     crt?: any
 }
@@ -78,6 +80,7 @@ type TEncapsulateOptions = {
     importStackLine: number,
     capsuleName?: string,
     ambientReferences?: Record<string, any>,
+    extendsCapsule?: TCapsule | string,
     capsuleSourceLineRef: string
 }
 
@@ -165,11 +168,15 @@ export async function SpineRuntime(options: TSpineRuntimeOptions): Promise<TSpin
 
                             let value = target[prop]
 
-                            // If the value is a Proxy (from Membrane), get the actual value through it
-                            // The Proxy will return the correct value from its get trap
-                            if (value && typeof value === 'object') {
-                                // Check if this value has .api - if so, unwrap it
-                                if (value.api && typeof value.api === 'object') {
+                            // If the value is a raw capsule instance (has spineContractCapsuleInstances
+                            // but is NOT a Proxy that handles API access), unwrap it
+                            // Static.v0 sets apiTarget[property.name] = mappedInstance (raw)
+                            // Membrane.v0 sets apiTarget[property.name] = new Proxy(...) which handles API access
+                            if (value && typeof value === 'object' && value.spineContractCapsuleInstances) {
+                                // Check if this is a raw capsule instance by seeing if it has .api
+                                // and the .api doesn't have the same spineContractCapsuleInstances
+                                // (Membrane Proxy would return .api properties, not the raw structure)
+                                if (value.api && typeof value.api === 'object' && !value.api.spineContractCapsuleInstances) {
                                     return createUnwrappingProxy(value)
                                 }
                             }
@@ -348,6 +355,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
         importStackLine,
         capsuleName: options.capsuleName,
         ambientReferences: options.ambientReferences,
+        extendsCapsule: options.extendsCapsule,
         capsuleSourceLineRef: `${moduleFilepath}:${importStackLine}`
     }
 
@@ -378,30 +386,29 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
         encapsulateOptions,
         cst: csts?.[encapsulateOptions.capsuleSourceLineRef],
         crt: crts?.[encapsulateOptions.capsuleSourceLineRef],
-        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts }: TCapsuleMakeInstanceOptions = {}) => {
+        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts, sharedSelf }: TCapsuleMakeInstanceOptions = {}) => {
 
             // Create cache key based on parameters
-            const cacheKey = JSON.stringify({
+            // When sharedSelf is provided, we must NOT cache because each extending capsule
+            // needs its own instance with its own 'this' context (sharedSelf).
+            // This is critical for the pattern where multiple structs extend the same parent.
+            const cacheKey = sharedSelf ? null : JSON.stringify({
                 overrides,
                 options,
                 hasRuntimeContracts: !!runtimeSpineContracts
             })
 
             // Check if we already have a pending or completed instance creation
-            if (instanceCache.has(cacheKey)) {
+            // Skip cache when sharedSelf is provided (cacheKey is null)
+            if (cacheKey && instanceCache.has(cacheKey)) {
                 return instanceCache.get(cacheKey)!
             }
 
-            // Create the instance promise and cache it immediately
+            // Create the instance promise and cache it immediately (only if cacheKey is set)
             const instancePromise = (async () => {
                 const encapsulatedApi: Record<string, any> = {}
                 const spineContractCapsuleInstances: Record<string, any> = {}
 
-                const capsuleInstance = {
-                    api: encapsulatedApi,
-                    spineContractCapsuleInstances
-                }
-
                 // Property contracts are keys starting with '#' that contain nested properties
                 // Structure: spineContractUri -> propertyContractUri -> propertyName -> propertyDef
                 const propertyContractDefinitions: Record<string, Record<string, Record<string, any>>> = {}
@@ -431,7 +438,11 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                             if (propContractUri !== '#') {
                                 // We have a property contract URI we need to resolve and load
                                 // Add a dynamic property mapping for this contract to the '#' group
-                                const contractKey = '#' + propContractUri.substring(1)
+                                // Check if 'as' is defined to use as the property name alias
+                                const propDefTyped = propDef as Record<string, any>
+                                const aliasName = propDefTyped.as
+                                const delegateOptions = propDefTyped.options
+                                const contractKey = aliasName || ('#' + propContractUri.substring(1))
 
                                 if (!propertyContractDefinitions[spineContractUri]['#']) {
                                     propertyContractDefinitions[spineContractUri]['#'] = {}
@@ -440,7 +451,10 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                                 propertyContractDefinitions[spineContractUri]['#'][contractKey] = {
                                     type: CapsulePropertyTypes.Mapping,
                                     value: propContractUri.substring(1),
-                                    propertyContractDelegate: propContractUri
+                                    propertyContractDelegate: propContractUri,
+                                    as: aliasName,
+                                    // Pass options from the property contract delegate to the mapped capsule
+                                    delegateOptions
                                 }
                             }
 
@@ -482,12 +496,120 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 }
                 mergeByContract(options, 'Options')
 
+                // Extract default values from property definitions (Literal/String types)
+                // This ensures child capsule's default values are available before parent is instantiated
+                const defaultPropertyValues: Record<string, any> = {}
+                for (const [spineContractUri, propertyContracts] of Object.entries(propertyContractDefinitions)) {
+                    for (const [propertyContractUri, properties] of Object.entries(propertyContracts)) {
+                        if (propertyContractUri !== '#') continue
+                        for (const [propertyName, propertyDef] of Object.entries(properties as Record<string, any>)) {
+                            if (propertyDef.type === CapsulePropertyTypes.Literal ||
+                                propertyDef.type === CapsulePropertyTypes.String) {
+                                if (propertyDef.value !== undefined) {
+                                    defaultPropertyValues[propertyName] = propertyDef.value
+                                }
+                            }
+                        }
+                    }
+                }
+
                 // Create a single shared self for all spine contracts by flattening merged values
-                const self = merge(
-                    {},
-                    defaultInstance,
-                    ...Object.values(mergedValuesByContract)
-                )
+                // ownValues contains this capsule's defaults and overrides
+                const ownValues = merge({}, defaultInstance, defaultPropertyValues, ...Object.values(mergedValuesByContract))
+
+                // If sharedSelf is provided (from extending capsule), we need to:
+                // 1. Add parent's properties that child doesn't have
+                // 2. Keep child's values for properties that exist in both
+                // We do this by assigning parent's values first, then child's values on top
+                let self: any
+                if (sharedSelf) {
+                    // Save child's current values (only non-undefined values)
+                    const childValues: Record<string, any> = {}
+                    for (const [key, value] of Object.entries(sharedSelf)) {
+                        if (value !== undefined) {
+                            childValues[key] = value
+                        }
+                    }
+                    // Assign parent's defaults to sharedSelf (for properties child doesn't have)
+                    for (const [key, value] of Object.entries(ownValues)) {
+                        if (!(key in childValues)) {
+                            sharedSelf[key] = value
+                        }
+                    }
+                    self = sharedSelf
+                } else {
+                    self = ownValues
+                }
+
+                // Create ownSelf containing only this capsule's own properties (not from extends chain)
+                // This allows functions to access this.self for their own capsule's properties
+                // The selfProxy in spine contracts will expose this as 'self' property
+                const ownSelf = merge({}, defaultInstance, defaultPropertyValues, ...Object.values(mergedValuesByContract))
+
+                // Initialize extended capsule instance if this capsule extends another
+                // Pass our self so extended capsule's functions bind to the same context
+                let extendedCapsuleInstance: any = undefined
+
+                // Check CST first, then fall back to encapsulateOptions for direct capsule references
+                let extendsCapsuleValue = capsule.cst?.source?.extendsCapsule || encapsulateOptions.extendsCapsule
+
+                // If extendsCapsule is a string identifier, check if it's in ambientReferences first
+                if (typeof extendsCapsuleValue === 'string') {
+                    const ambientRefs = capsule.cst?.source?.ambientReferences || encapsulateOptions.ambientReferences || {}
+                    for (const [refName, ref] of Object.entries(ambientRefs)) {
+                        const refTyped = ref as any
+                        if (refName === extendsCapsuleValue && refTyped.type === 'capsule' && refTyped.value) {
+                            extendsCapsuleValue = refTyped.value
+                            break
+                        }
+                    }
+                }
+
+                if (extendsCapsuleValue) {
+                    let extendsCapsule = extendsCapsuleValue
+
+                    // If it's a string, resolve it using the same mechanism as mappings
+                    if (typeof extendsCapsule === 'string') {
+                        // Use the first available spine contract to resolve the URI
+                        const activeSpineContracts = runtimeSpineContracts || spine.spineContracts
+                        const firstSpineContractKey = Object.keys(activeSpineContracts)[0]
+                        const firstSpineContract = activeSpineContracts[firstSpineContractKey] as any
+
+                        if (!firstSpineContract) throw new Error(`No spine contracts available to resolve extendsCapsule URI!`)
+
+                        // Create a contract instance to use resolveMappedCapsule
+                        const contractInstance = firstSpineContract.makeContractCapsuleInstance({
+                            spineContractUri: firstSpineContractKey,
+                            encapsulateOptions,
+                            capsuleInstance: { api: {}, spineContractCapsuleInstances: {} },
+                            self: {},
+                            capsule,
+                            encapsulatedApi: {},
+                            runtimeSpineContracts
+                        })
+
+                        // Resolve using the same mechanism as mappings
+                        extendsCapsule = await contractInstance.resolveMappedCapsule({
+                            property: {
+                                name: '__extends__',
+                                definition: { value: extendsCapsule }
+                            }
+                        })
+                    }
+
+                    extendedCapsuleInstance = await extendsCapsule.makeInstance({
+                        overrides,
+                        options,
+                        runtimeSpineContracts,
+                        sharedSelf: self
+                    })
+                }
+
+                const capsuleInstance = {
+                    api: encapsulatedApi,
+                    spineContractCapsuleInstances,
+                    extendedCapsuleInstance
+                }
 
                 // Use runtime spine contracts if provided, otherwise fall back to encapsulation spine contracts
                 const activeSpineContracts = runtimeSpineContracts || spine.spineContracts
@@ -503,9 +625,11 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                         encapsulateOptions,
                         capsuleInstance,
                         self,
+                        ownSelf,
                         capsule,
                         encapsulatedApi,
-                        runtimeSpineContracts
+                        runtimeSpineContracts,
+                        extendedCapsuleInstance
                     })
 
                     spineContractCapsuleInstances[spineContractUri] = spineContractCapsuleInstance
@@ -533,11 +657,37 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     }
                 }
 
+                // Wrap encapsulatedApi in a proxy that delegates to extended capsule's API for missing properties
+                if (extendedCapsuleInstance) {
+                    capsuleInstance.api = new Proxy(encapsulatedApi, {
+                        get: (target: any, prop: string | symbol) => {
+                            if (typeof prop === 'symbol') return target[prop]
+
+                            // First check if the property exists in local API
+                            if (prop in target) {
+                                return target[prop]
+                            }
+
+                            // Fall back to extended capsule's API
+                            if (prop in extendedCapsuleInstance.api) {
+                                return extendedCapsuleInstance.api[prop]
+                            }
+
+                            return undefined
+                        },
+                        has: (target: any, prop: string | symbol) => {
+                            return prop in target || prop in extendedCapsuleInstance.api
+                        }
+                    })
+                }
+
                 return capsuleInstance
             })()
 
-            // Cache the promise
-            instanceCache.set(cacheKey, instancePromise)
+            // Cache the promise only if cacheKey is set (not when sharedSelf is provided)
+            if (cacheKey) {
+                instanceCache.set(cacheKey, instancePromise)
+            }
 
             return instancePromise
         }