Introduction

Sqimitive.js – A Universal Primitive

Sqimitive.js is a minimalistic paradigm-agnostic building block for applications written in JavaScript (not necessary in-browser or DOM-related). It provides core infrastructure without much domain-specific logic that you can quickly develop thanks to its flexible API.

• Declaration-time and run-time mix-ins and traditional OOP inheritance using events. evt events mixIn _mergeProps
• Collections with Underscore (or other) integration and assisted management of children. util _childEvents autoOff
• Transparently ordered collections. Ordered _repos
• Attributes with normalization, on-change notifications and batching. opt change_OPT batch
• Unserialization of data in arbitrary format. assignChildren assignResp
• DOM integration for “views”. jQuery Base.elEvents
• Fractal Promise on steroids. Async Fetch

Sqimitive.js is under 20K (minified), sports documentation that is over 200 pages long (printed A4), needs no transpilers (plain pre-ES6 JavaScript, IE 11+) and depends only on a compatible utility library (NoDash no@ +16K, Underscore.js >=1.9.0 un: or LoDash) and, optionally, on jQuery jq: or Zepto (for Sqimitive\jQuery).

And it’s in public domain (http://unlicense.org).

from jqex

var Task = Sqimitive.jQuery.extend({
  el: {tag: 'li'},

  _opt: {
    // Keep el appended to the parent's el.
    attachPath: '.',
    // Define the default attributes of Task:
    caption: '',
    done: false,
  },

  events: {
    // Update the visual presentation whenever any _opt changes:
    change: 'render',

    render: function () {
      this.el.text(this.get('caption'))
        .toggleClass('done', this.get('done'))
    },
  },

  elEvents: {
    // Listen for double clicks on this.el to change the done state:
    dblclick: function () {
      this.set('done', !this.get('done'))
    },
  },
})

// Create a parent container for our to-do items (Task's) which
// is placed into the DOM at $('#tasks'):
var list = new Sqimitive.jQuery({el: '#tasks'})

// Create a new item, add it to list's _children:
list.nest( new Task({caption: 'Ready steady go!'}) )
// ...append to list's el and render for the first time:
  .attach().render()

// Double click on Task's element in the window to change its
// className.

Resources

npm install sqimitive

• New to Sqimitive? Start with the overview: ov
• Download for development: https://github.com/ProgerXP/Sqimitive/archive/master.zip
• Download for production (minified): https://raw.githubusercontent.com/ProgerXP/Sqimitive/master/sqimitive.min.js
• Check out the sample To-Do application: https://squizzle.me/js/sqimitive/demo/to-do.html
• Report issues: https://github.com/ProgerXP/Sqimitive/issues
• Get the code on GitHub: https://github.com/ProgerXP/Sqimitive

If you spot a typo – select the fragment and press Ctrl+Enter. Help us keep this memo free of vexatious mistakes! Powered by https://github.com/ProgerXP/Orphus.

Basic code conventions

• Protected fields begin with underscore (_) – such fields (data properties and methods) are meant to be read or written only by the class they are defined in, or by one of its subclasses. It’s bad practice to try to access them from an ancestor (not the descendant they’re defined in) or, mind you, from an unrelated class – this is only justified, if ever, by really severe optimizations (such as tons of Base._opt calls bypassing get()).
• Naming style: underscores separating camelCase – when an identifier (oneId) needs to be combined with another (twoId) it becomes simply oneId_twoId instead of oneIdTwoId, one_id_two_id or something else dictated by “pretty printing” identifiers. For example, Base fires events of form “change_OPT” so the event name used when attrName option (Base._opt) was changed is change_attrName.
• Semicolon-free zone – JavaScript is one of those languages where operation separators are optional, much like in Lua. You just need to remember to put ; before any operation beginning with ( (which most of the time has to do with IIFE):

  foo = 123
  ;(function () { ... })()
    // without ; above is equivalent to 123(function () { {... })()

• null is undefined – unless mentioned, these two values are used interchangeably: when testing, use value == null instead of ===; when supplying, give any of the two. One case when undefined is different are event handler results (see ::fire()).

Customizing dependenciesdeps

Sqimitive can be included using several methods as implemented by umh.js. Each method has its own way of overriding dependencies (which default to NoDash no@ and jQuery jq:). Alternatively, you can change the deps variable in the source code but you’ll have to redo it on upgrade.

CommonJS/Node.js

In npm 8.3+, put this into your project’s package.json before doing npm install sqimitive (https://github.com/npm/cli/issues/4909):

"overrides": {
  "sqimitive": {
    "nodash": "npm:underscore",
    "jquery": "npm:zepto"
  }
}

AMD/Require.js

Use map and/or path options (https://requirejs.org/docs/api.html#config):

requirejs.config({
  map: {
    'sqimitive/main': {
      'nodash/main': 'lodash'
    },
    'sqimitive/jquery': {
      jquery: 'zepto'
    }
  },
  paths: {
    nodash: 'https://cdn.jsdelivr.net/npm/underscore@latest/underscore-umd-min.js'
  }
})

Plain <script>

Dependencies land in global window so simply fetch the needed script before including Sqimitive:

<script src="https://cdn.jsdelivr.net/npm/underscore@latest/underscore-umd-min.js"></script>
<script src="https://raw.githubusercontent.com/ProgerXP/Sqimitive/master/sqimitive.min.js"></script>