@iamjulianacosta/mobx-data 1.0.1

package/src/store/index.ts

@@ -0,0 +1,11 @@
+export { Store } from './Store.js';
+export type {
+  AdapterLike,
+  AdapterFetchOptions,
+  SerializerLike,
+  FindOptions,
+  NormalizedDocument,
+  NormalizedResource,
+} from './Store.js';
+export { IdentityMap } from './IdentityMap.js';
+export { RecordArray, AdapterPopulatedRecordArray } from './RecordArray.js';

package/src/transforms/Transform.ts

@@ -0,0 +1,52 @@
+/**
+ * Interface and abstract base class for data transforms.
+ *
+ * A transform converts attribute values between the wire format used by the
+ * server (External) and the in-memory format used by the application
+ * (Internal).
+ *
+ * - `deserialize` — called when the store receives data from the server
+ *   (normalize direction, server → app).
+ * - `serialize` — called when the store sends data to the server
+ *   (serialize direction, app → server).
+ *
+ * Built-in transforms: `StringTransform`, `NumberTransform`,
+ * `BooleanTransform`, `DateTransform`.
+ *
+ * Custom transforms can be implemented by extending `BaseTransform`:
+ *
+ * ```ts
+ * @injectable()
+ * class UpperCaseTransform extends BaseTransform<string, string> {
+ *   deserialize(value: string) { return value.toUpperCase(); }
+ *   serialize(value: string)   { return value.toLowerCase(); }
+ * }
+ * ```
+ */
+
+/** Bidirectional value converter for a single attribute type. */
+export interface Transform<External = unknown, Internal = unknown> {
+  /**
+   * Converts a raw server value to the application-side type.
+   * @param serialized - Raw value as it arrived from the server.
+   * @param options    - Extra options forwarded from the `@attr` decorator.
+   */
+  deserialize(serialized: External, options?: Record<string, unknown>): Internal;
+
+  /**
+   * Converts an application-side value back to the wire format.
+   * @param deserialized - Current in-memory value.
+   * @param options      - Extra options forwarded from the `@attr` decorator.
+   */
+  serialize(deserialized: Internal, options?: Record<string, unknown>): External;
+}
+
+/**
+ * Convenience abstract class that implements `Transform` and can be extended
+ * to create custom transforms without repeating the interface declaration.
+ */
+export abstract class BaseTransform<External = unknown, Internal = unknown>
+implements Transform<External, Internal> {
+  abstract deserialize(serialized: External, options?: Record<string, unknown>): Internal;
+  abstract serialize(deserialized: Internal, options?: Record<string, unknown>): External;
+}

package/src/transforms/boolean.ts

@@ -0,0 +1,57 @@
+/**
+ * Transform that converts between arbitrary wire values and booleans.
+ *
+ * Deserialization coercions:
+ * - `null` / `undefined` → `false` (or `null` when `allowNull: true`)
+ * - `boolean` → passed through
+ * - `number` → `true` only when the value is exactly `1`
+ * - `string` → `true` for `'true'`, `'t'`, or `'1'` (case-insensitive)
+ * - anything else → `Boolean(value)`
+ *
+ * Serialization: `Boolean(value)` (preserves `null` when `allowNull: true`).
+ */
+
+import { injectable } from 'tsyringe';
+import { BaseTransform } from './Transform.js';
+
+/** Options accepted by `BooleanTransform`. */
+export interface BooleanTransformOptions {
+  /**
+   * When `true`, `null` / `undefined` input is preserved as `null` rather
+   * than coerced to `false`.
+   */
+  allowNull?: boolean;
+}
+
+@injectable()
+export class BooleanTransform extends BaseTransform<unknown, boolean | null> {
+  deserialize(
+    serialized: unknown,
+    options: BooleanTransformOptions = {},
+  ): boolean | null {
+    if (serialized === null || serialized === undefined) {
+      return options.allowNull ? null : false;
+    }
+    if (typeof serialized === 'boolean') {
+      return serialized;
+    }
+    if (typeof serialized === 'number') {
+      return serialized === 1;
+    }
+    if (typeof serialized === 'string') {
+      const normalized = serialized.toLowerCase();
+      return normalized === 'true' || normalized === 't' || normalized === '1';
+    }
+    return Boolean(serialized);
+  }
+
+  serialize(
+    deserialized: boolean | null,
+    options: BooleanTransformOptions = {},
+  ): unknown {
+    if (deserialized === null || deserialized === undefined) {
+      return options.allowNull ? null : false;
+    }
+    return Boolean(deserialized);
+  }
+}

package/src/transforms/date.ts

@@ -0,0 +1,48 @@
+/**
+ * Transform that converts between ISO 8601 strings (or numeric timestamps)
+ * and JavaScript `Date` objects.
+ *
+ * Deserialization:
+ * - `null` / `undefined` / `''` → `null`
+ * - `Date` instance → returned as-is (or `null` when invalid)
+ * - `number` (Unix ms) or `string` (ISO 8601) → parsed via `new Date(value)`,
+ *   returns `null` when parsing yields `NaN`
+ * - anything else → `null`
+ *
+ * Serialization:
+ * - `null` / `undefined` → `null`
+ * - `Date` instance → ISO 8601 string via `.toISOString()` (or `null` when invalid)
+ * - anything else → `null`
+ */
+
+import { injectable } from 'tsyringe';
+import { BaseTransform } from './Transform.js';
+
+@injectable()
+export class DateTransform extends BaseTransform<unknown, Date | null> {
+  deserialize(serialized: unknown): Date | null {
+    if (serialized === null || serialized === undefined || serialized === '') {
+      return null;
+    }
+    if (serialized instanceof Date) {
+      return Number.isNaN(serialized.getTime()) ? null : serialized;
+    }
+    if (typeof serialized === 'number' || typeof serialized === 'string') {
+      const parsed = new Date(serialized);
+      return Number.isNaN(parsed.getTime()) ? null : parsed;
+    }
+    return null;
+  }
+
+  serialize(deserialized: Date | null): unknown {
+    if (deserialized === null || deserialized === undefined) {
+      return null;
+    }
+    if (deserialized instanceof Date) {
+      return Number.isNaN(deserialized.getTime())
+        ? null
+        : deserialized.toISOString();
+    }
+    return null;
+  }
+}

package/src/transforms/index.ts

@@ -0,0 +1,5 @@
+export { BaseTransform, type Transform } from './Transform.js';
+export { StringTransform } from './string.js';
+export { NumberTransform } from './number.js';
+export { BooleanTransform } from './boolean.js';
+export { DateTransform } from './date.js';

package/src/transforms/number.ts

@@ -0,0 +1,42 @@
+/**
+ * Transform that converts between arbitrary wire values and numbers.
+ *
+ * Deserialization / serialization coercions (identical in both directions):
+ * - `null` / `undefined` / `''` → `null`
+ * - finite `number` → passed through
+ * - non-finite `number` (NaN, Infinity) → `null`
+ * - `string` → trimmed and parsed; `null` when the result is not finite
+ * - anything else → `null`
+ */
+
+import { injectable } from 'tsyringe';
+import { BaseTransform } from './Transform.js';
+
+@injectable()
+export class NumberTransform extends BaseTransform<unknown, number | null> {
+  static coerce(value: unknown): number | null {
+    if (value === null || value === undefined || value === '') {
+      return null;
+    }
+    if (typeof value === 'number') {
+      return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value === 'string') {
+      const trimmed = value.trim();
+      if (trimmed === '') {
+        return null;
+      }
+      const parsed = Number(trimmed);
+      return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+  }
+
+  deserialize(serialized: unknown): number | null {
+    return NumberTransform.coerce(serialized);
+  }
+
+  serialize(deserialized: number | null): unknown {
+    return NumberTransform.coerce(deserialized);
+  }
+}

package/src/transforms/string.ts

@@ -0,0 +1,35 @@
+/**
+ * Transform that converts between arbitrary wire values and strings.
+ *
+ * Deserialization:
+ * - `null` / `undefined` → `null`
+ * - `string` → passed through
+ * - anything else → `String(value)`
+ *
+ * Serialization:
+ * - `null` / `undefined` → `null`
+ * - anything else → `String(value)`
+ */
+
+import { injectable } from 'tsyringe';
+import { BaseTransform } from './Transform.js';
+
+@injectable()
+export class StringTransform extends BaseTransform<unknown, string | null> {
+  deserialize(serialized: unknown): string | null {
+    if (serialized === null || serialized === undefined) {
+      return null;
+    }
+    if (typeof serialized === 'string') {
+      return serialized;
+    }
+    return String(serialized);
+  }
+
+  serialize(deserialized: string | null): unknown {
+    if (deserialized === null || deserialized === undefined) {
+      return null;
+    }
+    return String(deserialized);
+  }
+}