Surreal JavaScript Library

Surreal uses two primary selection functions to solve the ambiguity of whether a selector returns a single element or an array.

• me(...): Guaranteed to return one element (the first found, or null).
  • Calling me() without arguments returns the parent element of the current <script> tag. This enables Locality of Behavior (LoB), allowing you to write scripts that act on their containing element without needing unique IDs or classes.
  • Supports CSS selectors (e.g., me('.button')), variables, and event objects.
  • Accepts an optional second parameter to define the starting DOM node (defaults to document).
• any(...): Guaranteed to return an array of elements (or an empty array).
  • Use this when you want to perform operations on all matching elements.
  • Works seamlessly with standard Array methods like .forEach(), .map(), and .filter().

You can convert between them using any(me()) or me(any(...)).

Surreal functions are designed to work identically on single elements or arrays of elements. You can use them via method chaining (recommended) or as global functions.

Chaining Style (Recommended):

me().classAdd('red')

Global Function Style:

classAdd(me(), 'red')

Note on Global Conveniences: By default, Surreal provides global conveniences (like classAdd()) that are attached to the window. If you prefer to avoid global namespace pollution, you can delete globalsAdd() from the source. To use the namespaced version, use surreal.me() or surreal.classAdd().

me().classAdd('red')
any("button").classAdd('red')
me().on("click", ev => me(ev).fadeOut())
any('button').on('click', ev => { me(ev).styles('color: red') })
any('button').run(_ => { alert(_) })
me().styles({ 'color':'red', 'background':'blue' })
me().attribute('active', true)

Surreal includes built-in animation helpers like fadeOut() and supports manual timelines using async/await and sleep() without external libraries.

Example: Fade out on click

<div>
  <script>me().on("click", ev => { me(ev).fadeOut() })</script>
</div>

Example: Manual Timeline

<div>
  <script>
    me().on("click", async ev => {
      let el = me(ev) // Capture element to avoid losing context in async
      me(el).styles({ "transition": "background 1s" })
      await sleep(1000)
      me(el).styles({ "background": "red" })
      // ... continue sequence
    })
  </script>
</div>

<div>
  <script>
    me().on("click", async ev => {
      let el = me(ev) // Save target because async will lose it.
      me(el).styles({ "transition": "background 1s" })
      await sleep(1000)
      me(el).styles({ "background": "red" })
      await sleep(1000)
      me(el).styles({ "background": "green" })
      await sleep(1000)
      me(el).styles({ "background": "blue" })
      await sleep(1000)
      me(el).styles({ "background": "none" })
      await sleep(1000)
      me(el).remove()
    })
  </script>
</div>

Surreal provides a suite of chainable and global functions for DOM manipulation.

Chainable functions (via me() or any()):

• run(fn): Executes a function on the element(s). Works on single elements or collections.
• remove(): Removes the element(s).
• classAdd(name): Adds a class (leading . is optional).
• classRemove(name): Removes a class.
• classToggle(name): Toggles a class.
• styles(cssStringOrObject): Sets styles. Use an object with null values to remove styles.
• attribute(name, value): Gets or sets attributes. Use an object to set/remove multiple.
• send(type, data): Wraps dispatchEvent to trigger events.
• on(type, fn): Wraps addEventListener.
• off(type, fn): Wraps removeEventListener.
• offAll(): Removes all event listeners.
• disable(): Disables click, key, and submit events.
• enable(): Re-enables events.

Global functions:

• createElement(tagName): Alias of document.createElement.
• sleep(ms, callback): Async version of setTimeout.
• halt(event): Stops propagation and prevents default actions.
• tick(): Async version of requestAnimationFrame (waits 1 frame).
• rAF(fn): Alias of requestAnimationFrame.
• rIC(fn): Alias of requestIdleCallback.
• onloadAdd(fn): Executes code after the DOM is ready (similar to jQuery ready()).

// Examples of chainable API
me().run(e => { alert(e) })
any('button').remove()
me().classAdd('active')
me().styles({ 'color':'red', 'background':'blue' })
me().attribute({ 'data-x':'yes', 'data-y':'no' })
me().on('click', ev => { me(ev).styles('background', 'red') })

// Examples of global API
await sleep(1000, ev => { alert(ev) })
await tick()