flow: almost feature parity with typescript

typings/dataclass.js.flow

@@ -1,6 +1,83 @@
 /* @flow */
+
+declare type OptKeys<T> = $Values<{ [P in $Keys<T> ]: T[P] extends void ? P : empty }>;
+declare type Optional<T> = Pick<{ [P in $Keys<T>]: T[P] }, OptKeys<T>>;
+declare type Explicit<T> = Omit<{ [P in $Keys<T>]: T[P] }, OptKeys<T>>;
+declare type Req<T> = { [P in $Keys<Optional<T>>]: $NonMaybeType<T[P]> };
+declare type Opt<T> = { [P in $Keys<Explicit<T>>]: T[P]};
+declare type Values<T> = { ...Req<T>, ...Partial<Opt<T>> };
+declare type Required<T> = { ...Req<T>, ...Opt<T> };
+declare type Init<T> = Optional<T> extends Record<any, empty> ? Values<T> | void : Values<T>;
+declare type Shape<T> = Partial<{ [P in $Keys<T>]: T[P] }>;
+
+/**
+ * Abstract class that allows defining custom data classes. Should be extended
+ * with a set of class fields that define the shape of desired model.
+ *
+ * ```js
+ * // @flow
+ * import { Data } from "dataclass";
+ *
+ * class Project extends Data {
+ *   // this property is required when creating an instance
+ *   id: ?string;
+ *   // these properties have defaults but can be overwritten
+ *   name: string = "Untitled";
+ *   createdBy: string = "Anon";
+ *   // this property may contain null and won't be required
+ *   createdAt: Date | null = null;
+ * }
+ *
+ * let project = Project.create({
+ *   id: 'abc123',
+ *   createdBy: 'Oleksii',
+ * });
+ * // > Project { id: 'abc123', name: 'Untitled', createdBy: 'Oleksii', createdAt: null }
+ * ```
+ *
+ * @link https://dataclass.js.org
+ */
 declare export class Data {
-  static create(values?: $Shape<this>): this;
-  copy(values?: $Shape<this>): this;
+  /**
+   * Instantiate the data class. Provide custom values that should override
+   * defaults. If the class has optional properties, create() method will
+   * require to explicitly define them.
+   *
+   * ```js
+   * // @flow
+   * 
+   * class User extends Data {
+   *   name: string = "Anon";
+   *   age: number | null = null;
+   * }
+   * ```
+   *
+   * @link https://dataclass.js.org/guide/getting-started.html
+   */
+  static create(values: Init<this>): this;
+  /**
+   * Create new immutable instance based on existing one, with some properties changed.
+   *
+   * ```js
+   * // @flow
+   * 
+   * class User extends Data {
+   *   name: string = "Anon";
+   *   age: number | null = null;
+   * }
+   *
+   * let initial = User.create({ name: "Liza" });
+   *
+   * // creates an immutable copy with previously defined
+   * // `name: "Liza"` and additionaly defined `age: 28`
+   * let updated = initial.copy({ age: 28 });
+   * ```
+   */
+  copy(values?: Shape<this>): this;
+  /**
+   * Compare the instance to another instance of the same data class.
+   *
+   * @link https://dataclass.js.org/guide/objects-equality.html
+   */
   equals(other: this): boolean;
 }