npm package: @jrc03c/data-class
Description: a struct-like class for storing data
Latest version: 0.0.3

# intro

a struct-like class for storing data

# installation

```bash
npm install @jrc03c/data-class
```

# usage

```js
import { Data } from "@jrc03c/data-class"

class PersonData extends Data {
  age = 0
  name = "Nobody"
}

console.log(PersonData.new())
// PersonData { age: 0, name: 'Nobody' }

console.log(PersonData.new({ age: 21 }))
// PersonData { age: 21, name: 'Nobody' }

console.log(PersonData.new({ name: "Alice" }))
// PersonData { age: 0, name: 'Alice' }

console.log(PersonData.new({ age: 21, name: "Alice" }))
// PersonData { age: 21, name: 'Alice' }
```

# why?

i made this little library for three main reasons:

first, i was tired of writing constructors in which i just copied properties from an options object onto an instance, like this:

```js
class SomeClass {
  prop1 = "..."
  prop2 = "..."
  prop3 = "..."
  // etc.

  constructor(data) {
    data = data ?? {}
    this.prop1 = data.prop1 ?? this.prop1
    this.prop2 = data.prop2 ?? this.prop2
    this.prop3 = data.prop3 ?? this.prop3
    // etc.
  }
}
```

in other words, i wanted to be able to just do `new SomeClass(data)` and not have to write a constructor for it.

second, i wanted to be able to extend a constructor-less class to add various features like getters / setters, methods, and even constructors if necessary.

third, i wanted to be able to verify that an object has a particular interface without relying on typescript. it's much easier to do `x instanceof SomeClass` than to check individual properties. (to be clear, the `Data` class exported by this library doesn't expect or enforce any kind of structure on the data it receives. but such expectations or enforcements could easily be implemented in a subclass of `Data`.)

# api

## `Data`

### `Data.new(options, shouldIncludeAllProperties)` (static method)

creates and returns a new instance of `Data`.

if an options object (`options`) is passed as the first argument, then that object's properties will be used to overwrite any existing instance property values.

if a `true` value (`shouldIncludeAllProperties`) is passed as the second argument, then _all_ properties on the `options` object will be assigned to the instance. for example:

```js
console.log(Data.new({ hello: "world" }))
// Data {}

console.log(Data.new({ hello: "world" }, true))
// Data { hello: 'world' }
```

be aware that the options object passed into this method is copied before use. in probably 99.99% of cases, this shouldn't cause any problems. but there may be edge cases in which the copying process fails or the data is modified by the copying process in unexpected ways (e.g., to break circular references).

# creating subclasses

creating a subclass of `Data` is generally pretty straightforward:

```js
class PersonData extends Data {
  age = 0
  name = "Nobody"
}

console.log(PersonData.new())
// PersonData { age: 0, name: 'Nobody' }

console.log(PersonData.new({ age: 21, name: "Alice" }))
// PersonData { age: 21, name: 'Alice' }
```

however, a complication arises when overriding the static `new` method while still expecting to use the superclass's `new` functionality. fortunately, it's a pretty easy complication to handle. all you have to do is re-bind the superclass's `new` method, like this:

```js
class PersonData extends Data {
  static new() {
    const newTemp = Data.new.bind(this)
    const out = newTemp(...arguments)

    // do whatever you want here. for example:
    if (typeof out.age !== "number" || out.age < 0) {
      throw new Error("Ages must be non-negative numbers!")
    }

    if (typeof out.name !== "string" || out.name.length === 0) {
      throw new Error("Names must be non-empty strings!")
    }

    // then return the instance:
    return out
  }

  age = 0
  name = "Nobody"
}
```

keep in mind, too, that getters and setters can usually handle sanity checking and may be a bit more elegant (if not less verbose) than overriding the static `new` method.

# notes

**be aware that you can use neither the `Data` constructor nor any `Data` subclass constructors!** if you try to use them, you'll receive an error!

i designed things this way because there were subtle issues related to instance construction that greatly increased the complexity of creating subclasses of `Data` (at least as it was originally conceived). so, the best solution seemed to be to avoid the constructor altogether and to rely on a static method for instance creation. although it's perhaps a bit unorthodox, i'm happy with the result so far — though i'm also willing to revisit the issue if anyone knows any good solutions.