@rudderjs/orm 0.0.6

package/dist/index.js

@@ -0,0 +1,450 @@
+import { castGet, castSet } from './cast.js';
+export { Attribute } from './attribute.js';
+export { JsonResource, ResourceCollection } from './resource.js';
+export { ModelCollection } from './collection.js';
+export { ModelFactory, sequence } from './factory.js';
+// ─── Global ORM Registry ───────────────────────────────────
+export class ModelRegistry {
+    static adapter = null;
+    static set(adapter) {
+        this.adapter = adapter;
+    }
+    static get() {
+        return this.adapter;
+    }
+    static getAdapter() {
+        if (!this.adapter) {
+            throw new Error('[RudderJS ORM] No ORM adapter registered. Did you add a database provider to your providers list?');
+        }
+        return this.adapter;
+    }
+    static reset() {
+        this.adapter = null;
+    }
+}
+// ─── Decorators ────────────────────────────────────────────
+/**
+ * Mark an instance property as hidden from JSON output.
+ * Equivalent to adding the field name to `static hidden`.
+ *
+ * @example
+ * class User extends Model {
+ *   @Hidden password = ''
+ * }
+ */
+export function Hidden(target, key) {
+    const ctor = target.constructor;
+    if (!Object.prototype.hasOwnProperty.call(ctor, 'hidden')) {
+        ctor.hidden = [...ctor.hidden];
+    }
+    ctor.hidden.push(String(key));
+}
+/**
+ * Restrict JSON output to only visible properties.
+ * Equivalent to setting `static visible`.
+ * Applied per-field — all `@Visible` fields form the allowlist.
+ *
+ * @example
+ * class User extends Model {
+ *   @Visible id = 0
+ *   @Visible name = ''
+ *   password = ''   // hidden because visible list is set
+ * }
+ */
+export function Visible(target, key) {
+    const ctor = target.constructor;
+    if (!Object.prototype.hasOwnProperty.call(ctor, 'visible')) {
+        ctor.visible = [];
+    }
+    ctor.visible.push(String(key));
+}
+/**
+ * Always include the named accessor in JSON output.
+ * The property must also be defined in `static attributes` with a getter.
+ *
+ * @example
+ * class User extends Model {
+ *   @Appends fullName = ''
+ *   static attributes = {
+ *     fullName: Attribute.make({ get: (_, a) => `${a['firstName']} ${a['lastName']}` }),
+ *   }
+ * }
+ */
+export function Appends(target, key) {
+    const ctor = target.constructor;
+    if (!Object.prototype.hasOwnProperty.call(ctor, 'appends')) {
+        ctor.appends = [...(ctor.appends ?? [])];
+    }
+    ctor.appends.push(String(key));
+}
+/**
+ * Apply a cast to an instance property.
+ * Equivalent to adding the field to `static casts`.
+ *
+ * @example
+ * class User extends Model {
+ *   @Cast('boolean') isAdmin = false
+ *   @Cast('date')    createdAt = new Date()
+ *   @Cast(MoneyCast) balance = 0
+ * }
+ */
+export function Cast(type) {
+    return (target, key) => {
+        const ctor = target.constructor;
+        if (!Object.prototype.hasOwnProperty.call(ctor, 'casts')) {
+            ctor.casts = { ...(ctor.casts ?? {}) };
+        }
+        ctor.casts[String(key)] = type;
+    };
+}
+// ─── Model Base Class ──────────────────────────────────────
+export class Model {
+    /** The table name — defaults to lowercase class name + 's' */
+    static table;
+    /** Primary key column */
+    static primaryKey = 'id';
+    /** Columns to hide from JSON output */
+    static hidden = [];
+    /**
+     * Columns to exclusively include in JSON output.
+     * When set, only these columns (plus appends) appear in toJSON().
+     * Takes precedence over `hidden`.
+     */
+    static visible = [];
+    /**
+     * Accessor names (defined in `attributes`) to always append to JSON output.
+     * The accessor must have a `get` function.
+     */
+    static appends = [];
+    /**
+     * Attribute casts — map column names to their cast types.
+     * Applied both when reading (toJSON) and writing (create/update).
+     *
+     * @example
+     * static casts = {
+     *   isAdmin:   'boolean',
+     *   createdAt: 'date',
+     *   settings:  'json',
+     *   balance:   MoneyCast,  // custom cast class
+     * } as const satisfies Record<string, CastDefinition>
+     */
+    static casts = {};
+    /**
+     * Accessors and mutators using `Attribute.make({ get, set })`.
+     *
+     * @example
+     * static attributes = {
+     *   firstName: Attribute.make({ get: v => String(v).charAt(0).toUpperCase() + String(v).slice(1) }),
+     *   fullName:  Attribute.make({ get: (_, attrs) => `${attrs['firstName']} ${attrs['lastName']}` }),
+     *   password:  Attribute.make({ set: async v => await bcrypt.hash(String(v), 10) }),
+     * }
+     */
+    static attributes = {};
+    /** Columns that are mass-assignable */
+    static fillable = [];
+    /**
+     * Enable soft deletes for this model. When true:
+     * - `delete()` sets `deletedAt` instead of removing the record
+     * - Queries automatically exclude records where `deletedAt` is not null
+     * - Use `withTrashed()` to include soft-deleted records
+     * - Use `onlyTrashed()` to return only soft-deleted records
+     * - Use `restore()` to un-delete a record
+     * - Use `forceDelete()` to permanently remove a record
+     */
+    static softDeletes = false;
+    // ── Instance-level serialization overrides ─────────────
+    /** @internal */
+    _instanceHidden;
+    /** @internal */
+    _instanceVisible;
+    // ── Scopes ─────────────────────────────────────────────
+    static globalScopes = {};
+    static scopes = {};
+    // ── Observers ──────────────────────────────────────────
+    /** @internal */
+    static _observers = [];
+    /** @internal */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static _listeners = new Map();
+    static observe(ObserverClass) {
+        if (!Object.prototype.hasOwnProperty.call(this, '_observers')) {
+            this._observers = [];
+        }
+        this._observers.push(new ObserverClass());
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static on(event, handler) {
+        if (!Object.prototype.hasOwnProperty.call(this, '_listeners')) {
+            this._listeners = new Map();
+        }
+        const list = this._listeners.get(event) ?? [];
+        list.push(handler);
+        this._listeners.set(event, list);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static async _fireEvent(event, ...args) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        let result = args[0];
+        const observers = Object.prototype.hasOwnProperty.call(this, '_observers') ? this._observers : [];
+        for (const obs of observers) {
+            const method = obs[event];
+            if (method) {
+                const ret = await method.call(obs, ...args);
+                if (ret === false)
+                    return false;
+                if (ret !== undefined && ret !== null && typeof ret === 'object')
+                    result = ret;
+            }
+        }
+        const listeners = Object.prototype.hasOwnProperty.call(this, '_listeners')
+            ? (this._listeners.get(event) ?? [])
+            : [];
+        for (const fn of listeners) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            const ret = await fn(...args);
+            if (ret === false)
+                return false;
+            if (ret !== undefined && ret !== null && typeof ret === 'object')
+                result = ret;
+        }
+        return result;
+    }
+    static clearObservers() {
+        this._observers = [];
+        this._listeners = new Map();
+    }
+    // ── Query Methods ──────────────────────────────────────
+    static getTable() {
+        return this.table ?? `${this.name.toLowerCase()}s`;
+    }
+    static query() {
+        let q = ModelRegistry.getAdapter().query(this.getTable());
+        if (this.softDeletes) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            q._enableSoftDeletes?.();
+        }
+        const globalScopes = this.globalScopes;
+        const excludedScopes = new Set();
+        for (const [, scopeFn] of Object.entries(globalScopes)) {
+            q = scopeFn(q);
+        }
+        const modelClass = this;
+        const localScopes = modelClass.scopes;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const enhanced = q;
+        enhanced.scope = (name, ...args) => {
+            const scopeFn = localScopes[name];
+            if (!scopeFn)
+                throw new Error(`[RudderJS ORM] Scope "${name}" is not defined on ${modelClass.name}.`);
+            return scopeFn(enhanced, ...args);
+        };
+        enhanced.withoutGlobalScope = (name) => {
+            excludedScopes.add(name);
+            let rebuilt = ModelRegistry.getAdapter().query(modelClass.getTable());
+            if (modelClass.softDeletes) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                rebuilt._enableSoftDeletes?.();
+            }
+            for (const [scopeName, scopeFn] of Object.entries(globalScopes)) {
+                if (!excludedScopes.has(scopeName)) {
+                    rebuilt = scopeFn(rebuilt);
+                }
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ;
+            rebuilt.scope = enhanced.scope;
+            rebuilt.withoutGlobalScope = enhanced.withoutGlobalScope;
+            return rebuilt;
+        };
+        return enhanced;
+    }
+    static _q(self) {
+        const q = ModelRegistry.getAdapter().query(self.getTable());
+        if (self.softDeletes) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            q._enableSoftDeletes?.();
+        }
+        let result = q;
+        for (const [, scopeFn] of Object.entries(self.globalScopes)) {
+            result = scopeFn(result);
+        }
+        return result;
+    }
+    static find(id) {
+        return Model._q(this).find(id);
+    }
+    static all() {
+        return Model._q(this).all();
+    }
+    static where(column, value) {
+        return Model._q(this).where(column, value);
+    }
+    static async create(data) {
+        const self = this;
+        let payload = self._applyMutators(data);
+        const result = await self._fireEvent('creating', payload);
+        if (result === false)
+            throw new Error(`[RudderJS ORM] Create cancelled by observer on ${self.name}.`);
+        if (result && typeof result === 'object')
+            payload = result;
+        const record = await Model._q(this).create(payload);
+        await self._fireEvent('created', record);
+        return record;
+    }
+    static with(...relations) {
+        return Model._q(this).with(...relations);
+    }
+    static async update(id, data) {
+        const self = this;
+        let payload = self._applyMutators(data);
+        const result = await self._fireEvent('updating', id, payload);
+        if (result === false)
+            throw new Error(`[RudderJS ORM] Update cancelled by observer on ${self.name}.`);
+        if (result && typeof result === 'object')
+            payload = result;
+        const record = await Model._q(this).update(id, payload);
+        await self._fireEvent('updated', record);
+        return record;
+    }
+    static async delete(id) {
+        const self = this;
+        const result = await self._fireEvent('deleting', id);
+        if (result === false)
+            throw new Error(`[RudderJS ORM] Delete cancelled by observer on ${self.name}.`);
+        await Model._q(this).delete(id);
+        await self._fireEvent('deleted', id);
+    }
+    static async restore(id) {
+        const self = this;
+        const result = await self._fireEvent('restoring', id);
+        if (result === false)
+            throw new Error(`[RudderJS ORM] Restore cancelled by observer on ${self.name}.`);
+        const record = await Model._q(this).restore(id);
+        await self._fireEvent('restored', record);
+        return record;
+    }
+    static async forceDelete(id) {
+        const self = this;
+        const result = await self._fireEvent('deleting', id);
+        if (result === false)
+            throw new Error(`[RudderJS ORM] Delete cancelled by observer on ${self.name}.`);
+        await Model._q(this).forceDelete(id);
+        await self._fireEvent('deleted', id);
+    }
+    // ── Cast / Mutator helpers ─────────────────────────────
+    /** @internal — apply cast setters and attribute mutators to an incoming data payload */
+    static _applyMutators(data) {
+        const result = {};
+        for (const [key, value] of Object.entries(data)) {
+            let val = value;
+            // Attribute mutator (set side) takes priority
+            const attrDef = this.attributes[key];
+            if (attrDef?.setter) {
+                val = attrDef.setter(val, data);
+            }
+            else if (this.casts[key] !== undefined) {
+                val = castSet(this.casts[key], key, val, data);
+            }
+            result[key] = val;
+        }
+        return result;
+    }
+    // ── Instance serialization controls ───────────────────
+    /**
+     * Make the given keys visible for this instance's JSON output.
+     * Removes them from the instance's hidden list and adds to the visible override.
+     * Returns `this` for chaining.
+     */
+    makeVisible(keys) {
+        const k = Array.isArray(keys) ? keys : [keys];
+        this._instanceHidden = (this._instanceHidden ?? this.constructor.hidden)
+            .filter(h => !k.includes(h));
+        return this;
+    }
+    /**
+     * Hide the given keys from this instance's JSON output.
+     * Returns `this` for chaining.
+     */
+    makeHidden(keys) {
+        const k = Array.isArray(keys) ? keys : [keys];
+        this._instanceHidden = [...(this._instanceHidden ?? this.constructor.hidden), ...k];
+        return this;
+    }
+    /**
+     * Override the visible list for this instance only.
+     * Returns `this` for chaining.
+     */
+    setVisible(keys) {
+        this._instanceVisible = keys;
+        return this;
+    }
+    /**
+     * Override the hidden list for this instance only.
+     * Returns `this` for chaining.
+     */
+    setHidden(keys) {
+        this._instanceHidden = keys;
+        return this;
+    }
+    /**
+     * Add keys to the visible list for this instance.
+     * Returns `this` for chaining.
+     */
+    mergeVisible(keys) {
+        const base = this._instanceVisible ?? this.constructor.visible;
+        this._instanceVisible = [...base, ...keys];
+        return this;
+    }
+    /**
+     * Add keys to the hidden list for this instance.
+     * Returns `this` for chaining.
+     */
+    mergeHidden(keys) {
+        const base = this._instanceHidden ?? this.constructor.hidden;
+        this._instanceHidden = [...base, ...keys];
+        return this;
+    }
+    // ── toJSON ─────────────────────────────────────────────
+    toJSON() {
+        const ctor = this.constructor;
+        const rawEntries = Object.entries(this).filter(([k]) => !k.startsWith('_instance'));
+        const raw = {};
+        for (const [k, v] of rawEntries) {
+            raw[k] = v;
+        }
+        const result = {};
+        // Apply casts (get side) and accessor getters
+        for (const [k, v] of Object.entries(raw)) {
+            const attrDef = ctor.attributes[k];
+            if (attrDef?.getter) {
+                result[k] = attrDef.getter(v, raw);
+            }
+            else if (ctor.casts[k] !== undefined) {
+                result[k] = castGet(ctor.casts[k], k, v, raw);
+            }
+            else {
+                result[k] = v;
+            }
+        }
+        // Appends — add computed accessor values that aren't raw properties
+        for (const appendKey of ctor.appends) {
+            if (!(appendKey in result)) {
+                const attrDef = ctor.attributes[appendKey];
+                if (attrDef?.getter) {
+                    result[appendKey] = attrDef.getter(undefined, raw);
+                }
+            }
+        }
+        // Determine effective visible / hidden lists
+        const effectiveVisible = this._instanceVisible ?? ctor.visible;
+        const effectiveHidden = this._instanceHidden ?? ctor.hidden;
+        // Apply visible (allowlist) — takes precedence
+        if (effectiveVisible.length > 0) {
+            const appendKeys = new Set(ctor.appends);
+            return Object.fromEntries(Object.entries(result).filter(([k]) => effectiveVisible.includes(k) || appendKeys.has(k)));
+        }
+        // Apply hidden (denylist)
+        return Object.fromEntries(Object.entries(result).filter(([k]) => !effectiveHidden.includes(k)));
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/resource.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Base class for API resource transformations.
+ *
+ * @example
+ * class UserResource extends JsonResource<User> {
+ *   toArray() {
+ *     return {
+ *       id:    this.resource.id,
+ *       name:  this.resource.name,
+ *       email: this.resource.email,
+ *       // conditional
+ *       admin: this.when(this.resource.role === 'admin', true),
+ *       posts: this.whenLoaded('posts', PostResource.collection(this.resource.posts as Post[])),
+ *     }
+ *   }
+ * }
+ *
+ * // In a route handler:
+ * res.json(new UserResource(user).toArray())
+ * res.json(UserResource.collection(users).toResponse())
+ */
+export declare abstract class JsonResource<T extends Record<string, unknown> = Record<string, unknown>> {
+    protected readonly resource: T;
+    constructor(resource: T);
+    /** Transform the resource into an array/object. Override in subclasses. */
+    abstract toArray(req?: unknown): Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Include `value` only when `condition` is true.
+     * Returns `fallback` (default `undefined`) when false.
+     *
+     * Undefined values are stripped from the output object — use `mergeWhen()` for
+     * conditional blocks of multiple keys.
+     */
+    protected when<V>(condition: boolean, value: V): V | undefined;
+    protected when<V>(condition: boolean, value: V, fallback: V): V;
+    /**
+     * Include `then` only when `value` is not null/undefined.
+     * If `then` is a function it receives the non-null value.
+     */
+    protected whenNotNull<V, R>(value: V | null | undefined, then: R | ((v: NonNullable<V>) => R), fallback?: R): R | undefined;
+    /**
+     * Include `value` only when the named relation is loaded on the resource.
+     * Falls back to `fallback` (default `undefined`) when not loaded.
+     */
+    protected whenLoaded<R>(relation: string): unknown;
+    protected whenLoaded<R>(relation: string, value: R): R | undefined;
+    protected whenLoaded<R>(relation: string, value: R, fallback: R): R;
+    /**
+     * Merge `attributes` into the output only when `condition` is true.
+     * Returns `{}` when false — spread the result at the call site.
+     *
+     * @example
+     * toArray() {
+     *   return {
+     *     id: this.resource.id,
+     *     ...this.mergeWhen(this.resource.isAdmin, {
+     *       permissions: this.resource.permissions,
+     *       lastLogin:   this.resource.lastLogin,
+     *     }),
+     *   }
+     * }
+     */
+    protected mergeWhen(condition: boolean, attributes: Record<string, unknown>): Record<string, unknown>;
+    /** Create a `ResourceCollection` from an array of raw items using this resource class. */
+    static collection<T extends Record<string, unknown>>(this: new (item: T) => JsonResource<T>, items: T[], meta?: Record<string, unknown>): ResourceCollection<T>;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Wraps multiple `JsonResource` instances for collection responses.
+ *
+ * @example
+ * class UserResource extends JsonResource<User> { ... }
+ *
+ * // From a route handler:
+ * const collection = UserResource.collection(users)
+ * res.json(await collection.toResponse())
+ * // → { data: [...] }
+ *
+ * // With pagination metadata:
+ * const collection = UserResource.collection(users, { total: 100, page: 1, perPage: 15 })
+ * res.json(await collection.toResponse())
+ * // → { data: [...], meta: { total: 100, page: 1, perPage: 15 } }
+ */
+export declare class ResourceCollection<T extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly items;
+    private readonly meta?;
+    constructor(items: JsonResource<T>[], meta?: Record<string, unknown> | undefined);
+    static of<T extends Record<string, unknown>>(items: JsonResource<T>[], meta?: Record<string, unknown>): ResourceCollection<T>;
+    toArray(req?: unknown): Promise<Record<string, unknown>[]>;
+    toResponse(req?: unknown): Promise<{
+        data: Record<string, unknown>[];
+        meta?: Record<string, unknown>;
+    }>;
+}
+//# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"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"}