@makefully/platypus 4.1.5 → 4.1.6

package/src/EntityLinker.js

@@ -0,0 +1,113 @@
+import {arrayCache, greenSplice} from './utils/array';
+import Data from './Data';
+import DataMap from './DataMap';
+import recycle from 'recycle';
+
+const
+    /**
+     * This class defines a linker for TiledLoader to connect entity pointer properties as soon as both entities are created.
+     *
+     * @memberof platypus
+     * @class EntityLinker
+     * @return {EntityLinker} Returns the new EntityLinker object.
+     */
+    EntityLinker = function () {
+        this.ids = this.ids || arrayCache.setUp();
+        this.entities = this.entities || DataMap.setUp();
+        this.currentId = 0;
+        this.count = 1;
+    },
+    proto = EntityLinker.prototype;
+
+proto.attemptRecycle = function () {
+    this.count -= 1;
+    if (this.count === 0) {
+        this.recycle();
+    }
+};
+
+proto.linkObject = function (id) {
+    this.currentId = id;
+    this.count += 1;
+};
+
+proto.linkEntity = function (entity) {
+    const
+        id = entity.tiledId,
+        list = this.ids;
+    let i = list.length;
+
+    while (i--) {
+        const
+            item = list[i];
+        let updated = false;
+
+        if (item.onEntity === entity.tiledId) {
+            item.onEntity = entity;
+            updated = true;
+        }
+        if (item.toEntity === entity.tiledId) {
+            item.toEntity = entity;
+            updated = true;
+        }
+        if (updated && typeof item.onEntity === 'object' && typeof item.toEntity === 'object') {
+            item.onEntity[item.property] = item.toEntity;
+            item.recycle();
+            greenSplice(list, i);
+        }
+    }
+
+    this.entities[id] = entity;
+    this.attemptRecycle();
+
+    return entity;
+};
+
+proto.getEntity = function (id, property) {
+    const entity = this.entities[id];
+
+    if (entity) {
+        return entity;
+    } else {
+        this.ids.push(Data.setUp(
+            'onEntity', this.currentId,
+            'toEntity', id,
+            'property', property
+        ));
+        return null;
+    }
+};
+
+/**
+ * Returns EntityLinker from cache or creates a new one if none are available.
+ *
+ * @method platypus.EntityLinker.setUp
+ * @return {platypus.EntityLinker} The instantiated EntityLinker.
+ */
+/**
+ * Returns EntityLinker back to the cache. Prefer the EntityLinker's recycle method since it recycles property objects as well.
+ *
+ * @method platypus.EntityLinker.recycle
+ * @param {platypus.EntityLinker} The EntityLinker to be recycled.
+ */
+/**
+ * Relinquishes EntityLinker properties and recycles it.
+ *
+ * @method platypus.EntityLinker#recycle
+ */
+recycle.add(EntityLinker, 'EntityLinker', EntityLinker, function () {
+    const
+        entities = this.entities,
+        keys = Object.keys(entities),
+        ids = this.ids;
+
+    for (let i = 0; i < keys.length; i++) {
+        delete entities[keys[i]];
+    }
+    for (let i = 0; i < ids.length; i++) {
+        ids[i].recycle();
+    }
+    ids.length = 0;
+}, true);
+
+export default EntityLinker;

package/src/EventHandler.js

@@ -0,0 +1,115 @@
+import recycle from 'recycle';
+
+/**
+ * Represents a single event subscription entry used by the event system.
+ *
+ * EventHandler instances are stored inside event emitter structures and
+ * sorted using `priority` and `order` to determine execution sequence.
+ *
+ * Higher priority values execute before lower ones. When priorities match,
+ * `order` acts as a stable tie-breaker preserving insertion sequence.
+ *
+ * Instances are pooled through `recycle` to reduce GC pressure in hot loops.
+ *
+ * @memberof platypus
+ * @class EventHandler
+ *
+ * @param {Function} callback Function invoked when the event fires.
+ * @param {Object} context Value used as `this` inside callback execution.
+ * @param {Number} priority Execution priority (higher runs first).
+ * @param {Number} order Stable ordering index used when priorities match.
+ *
+ * @property {Function} callback
+ * @property {Object} context
+ * @property {Number} priority
+ * @property {Number} order
+ */
+const EventHandler = function (callback, context = null, once = false, priority = 0, order = 0) {
+    this.callback = callback;
+    this.context = context;
+    this.once = once;
+    this.priority = priority;
+    this.order = order;
+};
+
+const { prototype } = EventHandler;
+
+/**
+ * Comparator used for sorting event handlers.
+ *
+ * Returns a negative number if this handler should run before the other.
+ * Returns a positive number if it should run after.
+ * Returns 0 when equivalent.
+ *
+ * Sorting rule:
+ * 1. higher priority runs first
+ * 2. if equal, lower order runs first
+ */
+prototype.sortPriority = function (eventHandler) {
+    return (this.priority - eventHandler.priority) || (this.order - eventHandler.order);
+};
+
+/**
+ * Returns EventHandler from cache or creates a new one.
+ *
+ * @method platypus.EventHandler.setUp
+ * @return {platypus.EventHandler}
+ */
+
+/**
+ * Returns EventHandler back to cache. If the instance has
+ * outstanding holds, the recycle is deferred until all holds
+ * are released.
+ *
+ * Prefer calling `eventHandler.recycle()`
+ * instead of direct pool access.
+ *
+ * @method platypus.EventHandler.recycle
+ * @param {platypus.EventHandler} eventHandler
+ */
+
+/**
+ * Increments the hold count on the instance, preventing recycling
+ * until all holds are released. Returns the instance for chaining.
+ *
+ * @method platypus.EventHandler.recycleHold
+ * @param {platypus.EventHandler} eventHandler
+ * @return {platypus.EventHandler}
+ */
+
+/**
+ * Decrements the hold count. When it reaches zero, any pending
+ * recycle is flushed. Returns the instance for chaining.
+ *
+ * @method platypus.EventHandler.recycleRelease
+ * @param {platypus.EventHandler} eventHandler
+ * @return {platypus.EventHandler}
+ */
+
+/**
+ * Clears internal references and recycles the instance. If the
+ * instance has outstanding holds, the recycle is deferred until
+ * all holds are released.
+ *
+ * @method platypus.EventHandler#recycle
+ */
+
+/**
+ * Increments the hold count on the instance, preventing recycling
+ * until all holds are released. Returns the instance for chaining.
+ *
+ * @method platypus.EventHandler#recycleHold
+ * @return {platypus.EventHandler}
+ */
+
+/**
+ * Decrements the hold count. When it reaches zero, any pending
+ * recycle is flushed. Returns the instance for chaining.
+ *
+ * @method platypus.EventHandler#recycleRelease
+ * @return {platypus.EventHandler}
+ */
+
+recycle.add(EventHandler, 'EventHandler', EventHandler, null, true);
+
+export default EventHandler;

package/src/EventHandlerList.js

@@ -0,0 +1,251 @@
+import recycle from 'recycle';
+import EventHandler from './EventHandler';
+import { arrayCache, greenSlice, greenSplice } from './utils/array';
+
+/**
+ * Maintains an ordered list of event handlers for a single event type.
+ *
+ * EventHandlerList supports:
+ * - listener priorities
+ * - deterministic insertion ordering
+ * - safe mutation during dispatch
+ * - one-time listeners
+ * - recyclable pooled handlers
+ *
+ * Handlers are lazily sorted on first dispatch after modification.
+ *
+ * @memberof platypus
+ * @class EventHandlerList
+ */
+const EventHandlerList = function () {
+    /**
+     * Whether the handler list requires resorting.
+     *
+     * @property dirty
+     * @type Boolean
+     * @default false
+     */
+    this.dirty = false;
+
+    /**
+     * The ordered list of EventHandler objects.
+     *
+     * @property handlers
+     * @type Array
+     */
+    this.handlers = arrayCache.setUp();
+
+    /**
+     * Incrementing insertion index used to preserve
+     * deterministic ordering between equal priorities.
+     *
+     * @property orderIndex
+     * @type Number
+     * @default 0
+     */
+    this.orderIndex = 0;
+};
+
+const { prototype } = EventHandlerList;
+
+/**
+ * Adds a new handler to the list.
+ *
+ * Handlers are not immediately sorted. Sorting occurs lazily
+ * during the next dispatch.
+ *
+ * @method add
+ * @param callback {Function}
+ * The listener callback function.
+ *
+ * @param [context=null] {Object}
+ * The callback execution context.
+ *
+ * @param [priority=0] {Number}
+ * Lower numbers execute first.
+ *
+ * @return {platypus.EventHandler}
+ * Returns the created EventHandler instance.
+ */
+prototype.add = function (callback, context, once, priority) {
+    for (let i = 0; i < this.handlers.length; i++) {
+        const existing = this.handlers[i];
+
+        if (
+            existing.callback === callback &&
+            existing.context === context
+        ) {
+            return null;
+        }
+    }
+    
+    const
+        eventHandler = EventHandler.setUp(
+            callback,
+            context,
+            once,
+            priority,
+            this.orderIndex++
+        );
+
+    this.handlers.push(eventHandler);
+    this.dirty = true;
+
+    return eventHandler;
+};
+
+/**
+ * Removes all handlers matching the supplied callback.
+ *
+ * @method remove
+ * @param callback {Function}
+ * @param context {Object}
+ * The callback function to remove.
+ */
+prototype.remove = function (callback, context) {
+    const
+        {handlers} = this;
+    let i = handlers.length;
+
+    while (i--) {
+        const
+            handler = handlers[i];
+
+        if (
+            handler.callback === callback &&
+            (
+                typeof context === 'undefined' ||
+                handler.context === context
+            )
+        ) {
+            handler.recycle();
+            greenSplice(handlers, i);
+        }
+    }
+};
+
+/**
+ * Dispatches the event to all registered handlers.
+ *
+ * The handler list is shallow-copied before iteration
+ * so listeners may safely remove themselves during dispatch.
+ *
+ * @method trigger
+ * @param [args] {Array}
+ * The arguments passed to listener callbacks.
+ *
+ * @return {Number}
+ * Returns the number of handlers triggered.
+ */
+prototype.trigger = function (args) {
+    if (this.dirty) {
+        this.handlers.sort((a, b) => a.sortPriority(b));
+        this.dirty = false;
+    }
+
+    const
+        handlers = greenSlice(this.handlers),
+        {length} = handlers;
+
+    // This prevents event handlers from getting recycled in the handlers copy.
+    for (let i = 0; i < length; i++) {
+        handlers[i].recycleHold();
+    }
+
+    for (let i = 0; i < length; i++) {
+        const
+            {callback, context, once} = handlers[i];
+
+        if (once) {
+            this.remove(callback);
+        }
+
+        callback.apply(context, args);
+    }
+
+    for (let i = 0; i < length; i++) {
+        handlers[i].recycleRelease();
+    }
+
+    arrayCache.recycle(handlers);
+
+    return length;
+};
+
+/**
+ * Returns EventHandlerList from cache or creates a new one.
+ *
+ * @method platypus.EventHandlerList.setUp
+ * @return {platypus.EventHandlerList}
+ */
+
+/**
+ * Returns EventHandlerList back to cache. If the instance has
+ * outstanding holds, the recycle is deferred until all holds
+ * are released.
+ *
+ * Prefer calling `eventHandlerList.recycle()`
+ * instead of direct pool access.
+ *
+ * @method platypus.EventHandlerList.recycle
+ * @param {platypus.EventHandlerList} eventHandlerList
+ */
+
+/**
+ * Increments the hold count on the instance, preventing recycling
+ * until all holds are released. Returns the instance for chaining.
+ *
+ * @method platypus.EventHandlerList.recycleHold
+ * @param {platypus.EventHandlerList} eventHandlerList
+ * @return {platypus.EventHandlerList}
+ */
+
+/**
+ * Decrements the hold count. When it reaches zero, any pending
+ * recycle is flushed. Returns the instance for chaining.
+ *
+ * @method platypus.EventHandlerList.recycleRelease
+ * @param {platypus.EventHandlerList} eventHandlerList
+ * @return {platypus.EventHandlerList}
+ */
+
+/**
+ * Clears internal references and recycles the instance. If the
+ * instance has outstanding holds, the recycle is deferred until
+ * all holds are released.
+ *
+ * @method platypus.EventHandlerList#recycle
+ */
+
+/**
+ * Increments the hold count on the instance, preventing recycling
+ * until all holds are released. Returns the instance for chaining.
+ *
+ * @method platypus.EventHandlerList#recycleHold
+ * @return {platypus.EventHandlerList}
+ */
+
+/**
+ * Decrements the hold count. When it reaches zero, any pending
+ * recycle is flushed. Returns the instance for chaining.
+ *
+ * @method platypus.EventHandlerList#recycleRelease
+ * @return {platypus.EventHandlerList}
+ */
+recycle.add(
+    EventHandlerList,
+    'EventHandlerList',
+    EventHandlerList,
+    function () {
+        this.handlers.forEach((handler) => handler.recycle());
+
+        arrayCache.recycle(this.handlers);
+
+        this.handlers = null;
+        this.dirty = false;
+        this.orderIndex = 0;
+    },
+    true
+);
+
+export default EventHandlerList;