Merge pull request #31 from cuthbertLab/airbnb-base

Update deps and to 1.2

Author: mscuthbert

.eslintignore

@@ -1,14 +1,19 @@
-jsonpickleJS
-============
+# jsonpickleJS
 
 Javascript reinterpretation of Python jsonpickle to allow reading and (to a lesser extent) 
 writing JSON objects
 
-Copyright (c) 2014 Michael Scott Cuthbert and cuthbertLab.
+Copyright © 2014-25 Michael Scott Asato Cuthbert.
 Released under the BSD (3-clause) license. See LICENSE.
 
-Python to Javascript and Back
-==============================
+# Pre-class-based system (Closing down)
+
+Note for 2025+: This system depends on legacy style functions that behave like objects.
+To use with modern Javascript you will need to assign all classes to globalThis (window, global).
+For this reason, v1.2 will be the last version of jsonpickleJS.  Using custom decoders in JSON.parse
+is probably the best solution going forward in the modern world.
+
+# Python to Javascript and Back
 Python has a remarkable number of ways (for a language that believes there's only one way to do it)
 to transfer data between itself and Javascript, most obviously with the 
 ``json.dump()``/``json.dumps()`` calls, which work well on specifically created data, especially
@@ -31,22 +36,21 @@ namespace, such as ``window``, in the Javascript.  For instance, if you have a c
 ``window.myobject.Thing`` in Javascript. The object, and any subobjects, will be created as closely
 as possible in Javascript.
 
-The reverse is also possible, with some caveats. Since Javascript doesn't (until ECMAScript 6) have
-the concept of named classes, each object will need to have a marker somewhere on it saying what
+The reverse is also possible, with some caveats. Since Javascript didn't (until ECMAScript 6) have
+the concept of named classes, each object needed to have a marker somewhere on it saying what
 Python object it should convert back to. The marker is 
 ``o[jsonpickle.tags.PY_CLASS] = 'fully.qualified.ClassName'``. 
 It may be possible in the future to use ``instanceof``
 through the entire Global namespace to figure out what something is, but that seems rather dangerous
 and inefficient (A project for later). 
 
-Limitations
-===========
+# Limitations
 Remember that Javascript does not have tuples, so all tuple objects are changed to lists.
+
 Namedtuples behave the same way, I believe. Dicts and Objects are identical in Javascript (both
 a blessing and a curse).
 
-Security
-========
+# Security
 Pickle, jsonpickle, and jsonpickleJS all raise important security considerations you must be
 aware of. You will be loading data directly into Python or Javascript with no checks on what the
 data contains. Only load data you have personally produced if you want to be safe.  In Javascript,
@@ -60,15 +64,68 @@ data, but anyone with JS programming experience can inject other data into your
 Be safe: be cautious going from Python to Javascript and NEVER accept Javascript-produced
 jsonpickle data from the net into your Python program in any sort of open environment.
 
-Usage
-=====
-See the source code of: testUnpickle.html to see how to use it. JsonpickleJS follows the AMD
-moduleloader standard, so set the ``src=""`` attribute in the ``<script>`` to an AMD loader
-such as ``//cdnjs.cloudflare.com/ajax/libs/require.js/2.1.14/require.min.js`` 
-(or the included local version in ``jsonpickleJS/ext/require/require.js``) and 
-the ``data-main`` attribute to ``jsonpickleJS/main`` (no ``.js``).  Then call 
-``var o = jsonpickle.decode(jsonStr)`` to get the Python object back as a JS object named ``o``.
-
-See the cuthbertLab/music21 and cuthbertLab/music21j projects and especially the ``.show('vexflow')``
-component for an example of how jsonpickleJS can be extremely useful for projects that have
-parallel data structures between Python and Javascript.
+# Usage
+
+You can use `jsonpickleJS` in modern JavaScript environments with either 
+ES Modules or traditional `<script>` tags.
+
+---
+
+### ES Module (Modern usage)
+
+```js
+// be sure jsonpickle is in your package.json and installed.
+
+// # in python:
+// import jsonpickle
+// jsonStr = jsonpickle.encode(my_object)
+
+import jsonpickle from 'jsonpickle';
+
+const obj = jsonpickle.decode(jsonStr);
+// `obj` is now a JavaScript version of the original Python object
+// with proper classes.
+```
+
+---
+
+### `<script>` Tag (Legacy/global usage)
+
+```html
+<script src="build/jsonpickle.min.js"></script>
+<script>
+    const obj = jsonpickle.decode(jsonStr);
+    console.log(obj);
+</script>
+```
+
+This works without any build system. The `jsonpickle` global will be available automatically.
+
+
+### Example
+
+You can find a working example in [`testUnpickle.html`](./testUnpickle.html).
+
+
+### Background
+
+`jsonpickleJS` allows you to **decode Python-style JSON strings** into rich JavaScript objects. 
+It’s especially useful for projects that mirror data structures across Python and JavaScript.
+
+One real-world use case:  
+Older versions of [`music21`](https://github.com/cuthbertLab/music21) and 
+[`music21j`](https://github.com/cuthbertLab/music21j) use `jsonpickleJS` to render complex 
+musical objects in the browser — such as using `.show('vexflow')` in music21 to visualize 
+music sent from Python into JavaScript.
+
+# Building
+Run once:
+```
+% npm install
+```
+
+Then:
+
+```
+% npm run build
+```

.eslintrc.json

@@ -0,0 +1,8 @@
+/*!
+ * 
+ * jsonpickle.js 1.2.0 built on 2025-08-06
+ * Copyright (c) 2013–2025 Michael Scott Asato Cuthbert. BSD License
+ *
+ * http://github.com/cuthbertLab/jsonpickleJS
+ *
+ */

README.md

@@ -0,0 +1,83 @@
+import globals from 'globals';
+import { configs } from 'eslint-config-airbnb-extended/legacy';
+
+export default [
+    ...configs.base.recommended,
+    {
+        ignores: ['build/*', 'node_modules/*'],
+        languageOptions: {
+            ecmaVersion: 'latest',
+            sourceType: 'module',
+            globals: {
+                ...globals.browser,
+            },
+        },
+        rules: {
+            'array-bracket-spacing': ['off'],
+            'arrow-parens': ['off'],
+            'brace-style': ['off'],
+            'camelcase': ['off'],
+            'class-methods-use-this': ['off'],
+            'comma-dangle': ['error', {
+                'arrays': 'only-multiline',
+                'objects': 'always-multiline',
+                'imports': 'always-multiline',
+                'exports': 'always-multiline',
+                'functions': 'ignore',
+            }],
+            'curly': ['error', 'all'],
+            'dot-location': ['error', 'property'],
+            'dot-notation': ['error'],
+            'indent': ['error', 4],
+            'import/extensions': ['off'],
+            'import/prefer-default-export': ['off'],
+            'import/no-named-as-default': ['off'],
+            'import/no-named-as-default-member': ['off'],
+            'import/no-unresolved': ['off'],
+            'import/no-extraneous-dependencies': ['off'],
+            'max-len': ['off'],
+            'new-cap': ['off'],
+            'no-case-declarations': ['error'],
+            'no-console': ['off'],
+            'no-continue': ['off'],
+            'no-confusing-arrow': ['off'],
+            'no-else-return': ['off'],
+            'no-lonely-if': ['off'],
+            'no-mixed-operators': ['off'],
+            'no-multi-spaces': ['off'],
+            'no-multiple-empty-lines': ['error', { 'max': 3 }],
+            'no-param-reassign': ['off'],
+            'no-plusplus': ['error', { 'allowForLoopAfterthoughts': true }],
+            'no-restricted-syntax': [
+                2,
+                'DebuggerStatement',
+                'LabeledStatement',
+                'WithStatement'
+            ],
+            'no-shadow': ['off'],
+            'no-trailing-spaces': ['off'],
+            'no-use-before-define': ['off'],
+            'no-underscore-dangle': ['off'],
+            'no-unused-vars': [
+                'error',
+                {
+                    args: 'none',
+                    caughtErrors: 'none',
+                    varsIgnorePattern: '^i$|^j$|^unused|^junk|^counter|^_',
+                }
+            ],
+            'object-curly-spacing': ['off'],
+            'object-property-newline': ['off'],
+            'operator-linebreak': ['error', 'before'],
+            'padded-blocks': ['off'],
+            'prefer-destructuring': ['off'],
+            'prefer-template': ['off'],
+            'quote-props': ['off'],
+            'radix': ['off'],
+            'space-infix-ops': ['off'],
+            'spaced-comment': ['off'],
+            'strict': ['error', 'global'],
+            'yoda': ['error', 'never', { 'exceptRange': true }],
+        },
+    },
+];

build/jsonpickle.min.js

@@ -2,22 +2,26 @@
  * jsonpickleJS -- interpretation of python jsonpickle in Javascript
  * index.js -- main loader -- this should be the only file that most users care about.
  *
- * Copyright (c) 2014-19 Michael Scott Cuthbert and cuthbertLab
+ * Copyright (c) 2014-25 Michael Scott Cuthbert and cuthbertLab
  */
-import 'regenerator-runtime/runtime';
-
 import * as unpickler from './unpickler.js';
 import * as pickler from './pickler.js';
 import * as util from './util.js';
 import { tags } from './tags.js';
 import { handlers } from './handlers.js';
 
 // noinspection JSUnusedGlobalSymbols
-export { pickler, unpickler, util, tags, handlers };
+export {
+    pickler, unpickler, util, tags, handlers, 
+};
 
 export function encode(
-    value, unpicklable=true, make_refs=true,
-    keys=false, max_depth, backend
+    value, 
+    unpicklable=true, 
+    make_refs=true,
+    keys=false, 
+    max_depth=undefined,
+    backend=undefined,
 ) {
     const options = {
         unpicklable,

build/jsonpickle.min.js.LICENSE.txt

@@ -1,6 +1,6 @@
-import * as util from './util';
-import { handlers } from './handlers';
-import { tags } from './tags';
+import * as util from './util.js';
+import { handlers } from './handlers.js';
+import { tags } from './tags.js';
 
 export function encode(value, options) {
     const params = {
@@ -51,6 +51,7 @@ export class Pickler {
         this._objs = [];
         this._seen = [];
     }
+
     reset() {
         this._objs = [];
         this._depth = -1;
@@ -60,13 +61,15 @@ export class Pickler {
     _push() {
         this._depth += 1;
     }
+
     _pop(value) {
         this._depth -= 1;
         if (this._depth === -1) {
             this.reset();
         }
         return value;
     }
+
     _mkref(obj) {
         const found_id = this._get_id_in_objs(obj);
         // console.log(found_id);
@@ -81,6 +84,7 @@ export class Pickler {
         this._objs.push(obj);
         return true;
     }
+
     _get_id_in_objs(obj) {
         const objLength = this._objs.length;
         // console.log('sought obj', obj);