feat: add type definitions

dist/index.d.ts

@@ -0,0 +1,47 @@
+export type AttributeDescriptor = {
+  name: string;
+  collection?: boolean | undefined;
+  enumerable?: boolean | undefined;
+}
+
+export class Refs {
+
+  /**
+   * Creates a new references object defining two inversly related
+   * attribute descriptors a and b.
+   *
+   * @param a property descriptor
+   * @param b property descriptor
+   */
+  constructor(a: AttributeDescriptor, b: AttributeDescriptor);
+
+  /**
+   * Binds one side of a bi-directional reference to a target object.
+   *
+   * @param target
+   * @param property
+   */
+  bind(target: any, property: string | AttributeDescriptor): void;
+
+  ensureBound(target: any, property: string | AttributeDescriptor): void;
+
+  ensureRefsCollection(target: any, property: AttributeDescriptor): any;
+
+  set(target: any, property: string | AttributeDescriptor, value: any): void;
+
+  unset(target: any, property: string | AttributeDescriptor, value: any): void;
+}
+
+export namespace Collection {
+
+  /**
+   * Extends a collection with Refs aware methods
+   */
+  function extend(collection: any[], refs: Refs, property: string | AttributeDescriptor, target: any): any;
+
+  /**
+   * Checks if a given collection is extended
+   */
+  function isExtended(collection: any[]): boolean;
+
+}

package.json

@@ -3,16 +3,18 @@
   "version": "0.3.0",
   "description": "Minimal bi-directional object references for JavaScript",
   "scripts": {
-    "all": "run-s lint bundle test",
+    "all": "run-s lint lint:types bundle test",
     "dev": "npm test -- --watch",
-    "bundle": "microbundle --target node --format esm,cjs",
+    "bundle": "microbundle --target node --generateTypes false --sourcemap false --format esm,cjs",
     "lint": "eslint .",
+    "lint:types": "tsc --noEmit",
     "test": "mocha test/spec/*.{cjs,js}"
   },
   "type": "module",
   "source": "./src/index.js",
   "module": "./dist/index.js",
   "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/bpmn-io/object-refs"
@@ -32,12 +34,15 @@
   },
   "license": "MIT",
   "devDependencies": {
+    "@types/chai": "^4.3.11",
+    "@types/mocha": "^10.0.6",
     "chai": "^4.3.10",
     "eslint": "^8.55.0",
     "eslint-plugin-bpmn-io": "^1.0.0",
     "microbundle": "^0.15.1",
     "mocha": "^10.2.0",
-    "npm-run-all": "^4.1.2"
+    "npm-run-all": "^4.1.2",
+    "typescript": "^5.3.3"
   },
   "files": [
     "dist"

test/spec/refsSpec.ts

@@ -0,0 +1,45 @@
+import {
+  Refs,
+  Collection
+} from '../../dist/index';
+
+import { expect } from 'chai';
+
+
+describe('types', function() {
+
+  describe('should type Refs', function() {
+
+    var refs = new Refs({ name: 'foo' }, { name: 'bar' });
+
+
+    it('should keep already set property', function() {
+
+      // given
+      var b = { };
+      var a = { foo: b };
+
+      // when
+      refs.bind(a, 'foo');
+
+      // then
+      expect(a.foo).to.equal(b);
+    });
+
+  });
+
+
+  describe('should type Collection', function() {
+
+    it('should keep already set property', function() {
+
+      // when
+      const collection = [];
+
+      // then
+      expect(Collection.isExtended(collection)).to.be.false;
+    });
+
+  });
+
+});

tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "lib": [
+      "ES2018"
+    ],
+    "strict": true,
+    "noImplicitAny": false
+  },
+  "include": [
+    "./dist/*.d.ts",
+    "./test/spec/**/*.ts"
+  ]
+}