etro 0.9.0 → 0.10.0

package/src/effect/stack.ts

@@ -1,6 +1,40 @@
 import { Movie } from '../movie'
 import { Visual } from './visual'
 import { Visual as VisualLayer } from '../layer'
+import { CustomArray, CustomArrayListener } from '../custom-array'
+
+class StackEffectsListener extends CustomArrayListener<Visual> {
+  // eslint-disable-next-line no-use-before-define
+  private _stack: Stack
+
+  constructor (stack: Stack) {
+    super()
+    this._stack = stack
+  }
+
+  onAdd (effect: Visual) {
+    if (!this._stack.parent) {
+      return
+    }
+
+    effect.tryAttach(this._stack.parent)
+  }
+
+  onRemove (effect: Visual) {
+    if (!this._stack.parent) {
+      return
+    }
+
+    effect.tryDetach()
+  }
+}
+
+class StackEffects extends CustomArray<Visual> {
+  // eslint-disable-next-line no-use-before-define
+  constructor (target: Visual[], stack: Stack) {
+    super(target, new StackEffectsListener(stack))
+  }
+}
 
 export interface StackOptions {
   effects: Visual[]
@@ -11,58 +45,37 @@ export interface StackOptions {
  * for defining reused effect sequences as one effect.
  */
 export class Stack extends Visual {
-  readonly effects: Visual[]
-
-  private _effectsBack: Visual[]
+  readonly effects: StackEffects
 
   constructor (options: StackOptions) {
     super()
 
-    this._effectsBack = []
-    // TODO: Throw 'change' events in handlers
-    this.effects = new Proxy(this._effectsBack, {
-      deleteProperty: function (target: Visual[], property: number | string): boolean {
-        const value = target[property]
-        value.detach() // Detach effect from movie
-        delete target[property]
-        return true
-      },
-      set: function (target: Visual[], property: number | string, value: Visual): boolean {
-        // TODO: make sure type check works
-        if (!isNaN(Number(property))) { // if property is a number (index)
-          if (target[property])
-            target[property].detach() // Detach old effect from movie
-
-          value.attach(this._target) // Attach effect to movie
-        }
-        target[property] = value
-        return true
-      }
-    })
+    this.effects = new StackEffects(options.effects, this)
     options.effects.forEach(effect => this.effects.push(effect))
-
-    // TODO: Propogate 'change' events from children up
   }
 
   attach (movie: Movie): void {
     super.attach(movie)
+
     this.effects.filter(effect => !!effect).forEach(effect => {
-      effect.detach()
-      effect.attach(movie)
+      effect.tryAttach(movie)
     })
   }
 
   detach (): void {
     super.detach()
+
     this.effects.filter(effect => !!effect).forEach(effect => {
-      effect.detach()
+      effect.tryDetach()
     })
   }
 
   apply (target: Movie | VisualLayer, reltime: number): void {
     for (let i = 0; i < this.effects.length; i++) {
       const effect = this.effects[i]
-      if (!effect) continue
+      if (!effect) {
+        continue
+      }
       effect.apply(target, reltime)
     }
   }

package/src/effect/transform.ts

@@ -15,9 +15,9 @@ export interface TransformOptions {
  */
 class Transform extends Visual {
   /** Matrix that determines how to transform the target */
-  matrix: Dynamic<Transform.Matrix>
+  matrix: Dynamic<Transform.Matrix> // eslint-disable-line no-use-before-define
 
-  private _tmpMatrix: Transform.Matrix
+  private _tmpMatrix: Transform.Matrix // eslint-disable-line no-use-before-define
   private _tmpCanvas: HTMLCanvasElement
   private _tmpCtx: CanvasRenderingContext2D
 
@@ -36,11 +36,13 @@ class Transform extends Visual {
   }
 
   apply (target: Movie | VisualLayer, reltime: number): void {
-    if (target.canvas.width !== this._tmpCanvas.width)
+    if (target.canvas.width !== this._tmpCanvas.width) {
       this._tmpCanvas.width = target.canvas.width
+    }
 
-    if (target.canvas.height !== this._tmpCanvas.height)
+    if (target.canvas.height !== this._tmpCanvas.height) {
       this._tmpCanvas.height = target.canvas.height
+    }
 
     // Use data, since that's the underlying storage
     this._tmpMatrix.data = val(this, 'matrix.data', reltime)
@@ -81,8 +83,9 @@ namespace Transform { // eslint-disable-line @typescript-eslint/no-namespace
     }
 
     identity (): Matrix {
-      for (let i = 0; i < this.data.length; i++)
+      for (let i = 0; i < this.data.length; i++) {
         this.data[i] = Matrix.IDENTITY.data[i]
+      }
 
       return this
     }
@@ -93,8 +96,9 @@ namespace Transform { // eslint-disable-line @typescript-eslint/no-namespace
      * @param [val]
      */
     cell (x: number, y: number, val?: number): number {
-      if (val !== undefined)
+      if (val !== undefined) {
         this.data[3 * y + x] = val
+      }
 
       return this.data[3 * y + x]
     }
@@ -130,18 +134,21 @@ namespace Transform { // eslint-disable-line @typescript-eslint/no-namespace
      */
     multiply (other: Matrix): Matrix {
       // copy to temporary matrix to avoid modifying `this` while reading from it
-      for (let x = 0; x < 3; x++)
+      for (let x = 0; x < 3; x++) {
         for (let y = 0; y < 3; y++) {
           let sum = 0
-          for (let i = 0; i < 3; i++)
+          for (let i = 0; i < 3; i++) {
             sum += this.cell(x, i) * other.cell(i, y)
+          }
 
           Matrix._TMP_MATRIX.cell(x, y, sum)
         }
+      }
 
       // copy data from TMP_MATRIX to this
-      for (let i = 0; i < Matrix._TMP_MATRIX.data.length; i++)
+      for (let i = 0; i < Matrix._TMP_MATRIX.data.length; i++) {
         this.data[i] = Matrix._TMP_MATRIX.data[i]
+      }
 
       return this
     }

package/src/event.ts

@@ -4,6 +4,32 @@
 
 import EtroObject from './object'
 
+class DeprecatedEvent {
+  replacement: string
+  message: string
+
+  constructor (replacement: string, message: string = undefined) {
+    this.replacement = replacement
+    this.message = message
+  }
+
+  toString () {
+    let str = ''
+
+    if (this.replacement) {
+      str += `Use ${this.replacement} instead.`
+    }
+
+    if (this.message) {
+      str += ` ${this.message}`
+    }
+
+    return str
+  }
+}
+
+const deprecatedEvents: Record<string, DeprecatedEvent> = {}
+
 export interface Event {
   target: EtroObject
   type: string
@@ -21,12 +47,15 @@ class TypeId {
   }
 
   contains (other) {
-    if (other._parts.length > this._parts.length)
+    if (other._parts.length > this._parts.length) {
       return false
+    }
 
-    for (let i = 0; i < other._parts.length; i++)
-      if (other._parts[i] !== this._parts[i])
+    for (let i = 0; i < other._parts.length; i++) {
+      if (other._parts[i] !== this._parts[i]) {
         return false
+      }
+    }
 
     return true
   }
@@ -36,27 +65,60 @@ class TypeId {
   }
 }
 
+export function deprecate (type: string, newType: string, message: string = undefined): void {
+  deprecatedEvents[type] = new DeprecatedEvent(newType, message)
+}
+
+function subscribeOnce (target: EtroObject, type: string, listener: <T extends Event>(T) => void): void {
+  const wrapped = event => {
+    unsubscribe(target, wrapped)
+    listener(event)
+  }
+  subscribe(target, type, wrapped)
+}
+
+function subscribeMany (target: EtroObject, type: string, listener: <T extends Event>(T) => void): void {
+  if (!listeners.has(target)) {
+    listeners.set(target, [])
+  }
+
+  listeners.get(target).push(
+    { type: new TypeId(type), listener }
+  )
+}
+
 /**
- * Listen for an event or category of events
+ * Listen for an event or category of events.
  *
- * @param target - a etro object
+ * @param target - an etro object
  * @param type - the id of the type (can contain subtypes, such as
  * "type.subtype")
  * @param listener
+ * @param options - options
+ * @param options.once - if true, the listener will only be called once
  */
-export function subscribe (target: EtroObject, type: string, listener: <T extends Event>(T) => void): void {
-  if (!listeners.has(target))
-    listeners.set(target, [])
+export function subscribe (
+  target: EtroObject,
+  type: string,
+  listener: <T extends Event>(T) => void,
+  options: { once?: boolean } = {}
+): void {
+  // Check if this event is deprecated.
+  if (Object.keys(deprecatedEvents).includes(type)) {
+    console.warn(`Event ${type} is deprecated. ${deprecatedEvents[type]}`)
+  }
 
-  listeners.get(target).push(
-    { type: new TypeId(type), listener }
-  )
+  if (options.once) {
+    subscribeOnce(target, type, listener)
+  } else {
+    subscribeMany(target, type, listener)
+  }
 }
 
 /**
  * Remove an event listener
  *
- * @param target - a etro object
+ * @param target - an etro object
  * @param type - the id of the type (can contain subtypes, such as
  * "type.subtype")
  * @param listener
@@ -64,8 +126,9 @@ export function subscribe (target: EtroObject, type: string, listener: <T extend
 export function unsubscribe (target: EtroObject, listener: <T extends Event>(T) => void): void {
   // Make sure `listener` has been added with `subscribe`.
   if (!listeners.has(target) ||
-  !listeners.get(target).map(pair => pair.listener).includes(listener))
+  !listeners.get(target).map(pair => pair.listener).includes(listener)) {
     throw new Error('No matching event listener to remove')
+  }
 
   const removed = listeners.get(target)
     .filter(pair => pair.listener !== listener)
@@ -73,29 +136,31 @@ export function unsubscribe (target: EtroObject, listener: <T extends Event>(T)
 }
 
 /**
- * Emits an event to all listeners
+ * Publish an event to all listeners without checking if it is deprecated.
  *
- * @param target - a etro object
- * @param type - the id of the type (can contain subtypes, such as
- * "type.subtype")
- * @param event - any additional event data
+ * @param target
+ * @param type
+ * @param event
+ * @returns
  */
-export function publish (target: EtroObject, type: string, event: Record<string, unknown>): Event {
+function _publish (target: EtroObject, type: string, event: Record<string, unknown>): Event {
   (event as unknown as Event).target = target; // could be a proxy
   (event as unknown as Event).type = type
 
   const t = new TypeId(type)
 
-  if (!listeners.has(target))
+  if (!listeners.has(target)) {
     // No event fired
     return null
+  }
 
   // Call event listeners for this event.
   const listenersForType = []
   for (let i = 0; i < listeners.get(target).length; i++) {
     const item = listeners.get(target)[i]
-    if (t.contains(item.type))
+    if (t.contains(item.type)) {
       listenersForType.push(item.listener)
+    }
   }
 
   for (let i = 0; i < listenersForType.length; i++) {
@@ -106,6 +171,31 @@ export function publish (target: EtroObject, type: string, event: Record<string,
   return event as unknown as Event
 }
 
+/**
+ * Emits an event to all listeners
+ *
+ * @param target - an etro object
+ * @param type - the id of the type (can contain subtypes, such as
+ * "type.subtype")
+ * @param event - any additional event data
+ */
+export function publish (target: EtroObject, type: string, event: Record<string, unknown>): Event {
+  // Check if this event is deprecated only if it can be replaced.
+  if (Object.keys(deprecatedEvents).includes(type) && deprecatedEvents[type].replacement) {
+    throw new Error(`Event ${type} is deprecated. ${deprecatedEvents[type]}`)
+  }
+
+  // Check for deprecated events that this event replaces.
+  for (const deprecated in deprecatedEvents) {
+    const deprecatedEvent = deprecatedEvents[deprecated]
+    if (type === deprecatedEvent.replacement) {
+      _publish(target, deprecated, { ...event })
+    }
+  }
+
+  return _publish(target, type, event)
+}
+
 const listeners: WeakMap<EtroObject, {
   type: TypeId,
   listener: (Event) => void

package/src/layer/audio-source.ts

@@ -6,19 +6,24 @@ import { Base, BaseOptions } from './base'
 type Constructor<T> = new (...args: unknown[]) => T
 
 interface AudioSource extends Base {
-  readonly source: HTMLMediaElement
+  /** HTML media element (an audio or video element) */
+  readonly source: HTMLAudioElement
+  /** Audio source node for the media */
   readonly audioNode: AudioNode
   playbackRate: number
-  /** The audio source node for the media */
+  /** Seconds to skip ahead by */
   sourceStartTime: number
 }
 
-interface AudioSourceOptions extends BaseOptions {
+interface AudioSourceOptions extends Omit<BaseOptions, 'duration'> {
+  duration?: number
+  /** HTML media element (an audio or video element) */
   source: HTMLMediaElement
+  /** Seconds to skip ahead by */
   sourceStartTime?: number
   muted?: boolean
   volume?: number
-  playbackRate: number
+  playbackRate?: number
   onload?: (source: HTMLMediaElement, options: AudioSourceOptions) => void
 }
 
@@ -59,18 +64,31 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
      * @param [options.playbackRate=1]
      */
     constructor (options: MixedAudioSourceOptions) {
+      if (!options.source) {
+        throw new Error('Property "source" is required in options')
+      }
+
       const onload = options.onload
       // Don't set as instance property
       delete options.onload
-      super(options)
+
+      super({
+        ...options,
+
+        // Set a default duration so that the super constructor doesn't throw an
+        // error
+        duration: options.duration ?? 0
+      })
+
       this._initialized = false
       this._sourceStartTime = options.sourceStartTime || 0
       applyOptions(options, this)
 
       const load = () => {
         // TODO:              && ?
-        if ((options.duration || (this.source.duration - this.sourceStartTime)) < 0)
+        if ((options.duration || (this.source.duration - this.sourceStartTime)) < 0) {
           throw new Error('Invalid options.duration or options.sourceStartTime')
+        }
 
         this._unstretchedDuration = options.duration || (this.source.duration - this.sourceStartTime)
         this.duration = this._unstretchedDuration / (this.playbackRate)
@@ -78,31 +96,34 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
         // super()
         onload && onload.bind(this)(this.source, options)
       }
-      if (this.source.readyState >= 2)
+      if (this.source.readyState >= 2) {
         // this frame's data is available now
         load()
-      else
+      } else {
         // when this frame's data is available
         this.source.addEventListener('loadedmetadata', load)
+      }
 
       this.source.addEventListener('durationchange', () => {
         this.duration = options.duration || (this.source.duration - this.sourceStartTime)
       })
     }
 
+    async whenReady (): Promise<void> {
+      await super.whenReady()
+      if (this.source.readyState < 4) {
+        await new Promise(resolve => {
+          this.source.addEventListener('canplaythrough', resolve)
+        })
+      }
+    }
+
     attach (movie: Movie) {
       super.attach(movie)
 
-      subscribe(movie, 'movie.seek', () => {
-        if (this.currentTime < 0 || this.currentTime >= this.duration)
-          return
-
-        this.source.currentTime = this.currentTime + this.sourceStartTime
-      })
-
       // TODO: on unattach?
-      subscribe(movie, 'movie.audiodestinationupdate', event => {
-        // Connect to new destination if immeidately connected to the existing
+      subscribe(movie, 'audiodestinationupdate', event => {
+        // Connect to new destination if immediately connected to the existing
         // destination.
         if (this._connectedToDestination) {
           this.audioNode.disconnect(movie.actx.destination)
@@ -123,8 +144,9 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
       const oldDisconnect = this._audioNode.disconnect.bind(this.audioNode)
       this._audioNode.disconnect = <T extends AudioDestinationNode>(destination?: T | number, output?: number, input?: number): AudioNode => {
         if (this._connectedToDestination &&
-        destination === movie.actx.destination)
+        destination === movie.actx.destination) {
           this._connectedToDestination = false
+        }
 
         return oldDisconnect(destination, output, input)
       }
@@ -145,6 +167,12 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
       this.source.play()
     }
 
+    seek (time: number): void {
+      super.seek(time)
+
+      this.source.currentTime = this.currentTime + this.sourceStartTime
+    }
+
     render () {
       super.render()
       // TODO: implement Issue: Create built-in audio node to support built-in
@@ -155,6 +183,8 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
     }
 
     stop () {
+      super.stop()
+
       this.source.pause()
     }
 
@@ -171,8 +201,9 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
 
     set playbackRate (value) {
       this._playbackRate = value
-      if (this._unstretchedDuration !== undefined)
+      if (this._unstretchedDuration !== undefined) {
         this.duration = this._unstretchedDuration / value
+      }
     }
 
     get startTime () {
@@ -202,7 +233,16 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
       return this._sourceStartTime
     }
 
-    getDefaultOptions (): MixedAudioSourceOptions {
+    get ready (): boolean {
+      // Typescript doesn't support `super.ready` when targeting es5
+      const superReady = Object.getOwnPropertyDescriptor(superclass.prototype, 'ready').get.call(this)
+      return superReady && this.source.readyState === 4
+    }
+
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
+    getDefaultOptions () {
       return {
         ...superclass.prototype.getDefaultOptions(),
         source: undefined, // required

package/src/layer/audio.ts

@@ -3,22 +3,44 @@
 import { Base, BaseOptions } from './base'
 import { AudioSourceMixin, AudioSourceOptions } from './audio-source'
 
-type AudioOptions = AudioSourceOptions
+interface AudioOptions extends Omit<AudioSourceOptions, 'source'> {
+  /**
+   * The raw html `<audio>` element
+   */
+  source: string | HTMLAudioElement
+}
 
 /**
+ * Layer for an HTML audio element
  * @extends AudioSource
  */
 class Audio extends AudioSourceMixin<BaseOptions>(Base) {
+  /**
+   * The raw html `<audio>` element
+   */
+  source: HTMLAudioElement
+
   /**
    * Creates an audio layer
    */
   constructor (options: AudioOptions) {
+    if (typeof options.source === 'string') {
+      const audio = document.createElement('audio')
+      audio.src = options.source
+      options.source = audio
+    }
+
     super(options)
-    if (this.duration === undefined)
+
+    if (this.duration === undefined) {
       this.duration = (this).source.duration - this.sourceStartTime
+    }
   }
 
-  getDefaultOptions (): AudioOptions {
+  /**
+   * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+   */
+  getDefaultOptions () {
     return {
       ...Object.getPrototypeOf(this).getDefaultOptions(),
       /**