@stonyx/orm 0.2.7-alpha.0 → 0.3.1

package/dist/postgres/schema-introspector.js

@@ -0,0 +1,296 @@
+import Orm from '@stonyx/orm';
+import { getPgType, getVectorType } from './type-map.js';
+import { camelCaseToKebabCase } from '@stonyx/utils/string';
+import { getPluralName } from '../plural-registry.js';
+import { dbKey } from '../db.js';
+import { AggregateProperty } from '../aggregates.js';
+import { getRelationshipInfo, sanitizeTableName } from '../schema-helpers.js';
+import ModelProperty from '../model-property.js';
+export function introspectModels() {
+    const { models } = Orm.instance;
+    const schemas = {};
+    for (const [modelKey, modelClass] of Object.entries(models)) {
+        const name = camelCaseToKebabCase(modelKey.slice(0, -5));
+        if (name === dbKey)
+            continue;
+        const model = new modelClass(modelKey);
+        const columns = {};
+        const foreignKeys = {};
+        const relationships = { belongsTo: {}, hasMany: {} };
+        const vectorColumns = {};
+        let idType = 'number';
+        const transforms = Orm.instance.transforms;
+        for (const [key, property] of Object.entries(model)) {
+            if (key.startsWith('__'))
+                continue;
+            const relInfo = getRelationshipInfo(property);
+            if (relInfo?.type === 'belongsTo') {
+                relationships.belongsTo[key] = relInfo.modelName;
+            }
+            else if (relInfo?.type === 'hasMany') {
+                relationships.hasMany[key] = relInfo.modelName;
+            }
+            else if (property instanceof ModelProperty) {
+                const prop = property;
+                if (key === 'id') {
+                    idType = prop.type;
+                }
+                else if (prop.type === 'vector') {
+                    const dimensions = prop.dimensions || 1536;
+                    columns[key] = getVectorType(dimensions);
+                    vectorColumns[key] = dimensions;
+                }
+                else {
+                    columns[key] = getPgType(prop.type, transforms[prop.type]);
+                }
+            }
+        }
+        // Build foreign keys from belongsTo relationships
+        for (const [relName, targetModelName] of Object.entries(relationships.belongsTo)) {
+            if (!targetModelName)
+                continue;
+            const fkColumn = `${relName}_id`;
+            foreignKeys[fkColumn] = {
+                references: sanitizeTableName(getPluralName(targetModelName)),
+                column: 'id',
+            };
+        }
+        const hypertable = modelClass.hypertable;
+        schemas[name] = {
+            table: sanitizeTableName(getPluralName(name)),
+            idType,
+            columns,
+            foreignKeys,
+            relationships,
+            vectorColumns,
+            hypertable: hypertable || undefined,
+            memory: modelClass.memory === true,
+        };
+    }
+    return schemas;
+}
+export function buildTableDDL(name, schema, allSchemas = {}) {
+    const { idType, columns, foreignKeys, hypertable } = schema;
+    const table = sanitizeTableName(schema.table);
+    const lines = [];
+    const useCompositePK = hypertable && idType !== 'string';
+    // Primary key
+    if (idType === 'string') {
+        lines.push('  "id" VARCHAR(255) PRIMARY KEY');
+    }
+    else if (useCompositePK) {
+        lines.push('  "id" INTEGER GENERATED ALWAYS AS IDENTITY');
+    }
+    else {
+        lines.push('  "id" INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY');
+    }
+    // Attribute columns
+    for (const [col, pgType] of Object.entries(columns)) {
+        lines.push(`  "${col}" ${pgType}`);
+    }
+    // Foreign key columns
+    for (const [fkCol, fkDef] of Object.entries(foreignKeys)) {
+        const refIdType = getReferencedIdType(fkDef.references, allSchemas);
+        lines.push(`  "${fkCol}" ${refIdType}`);
+    }
+    // Timestamps
+    if (useCompositePK) {
+        lines.push('  "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW()');
+    }
+    else {
+        lines.push('  "created_at" TIMESTAMPTZ DEFAULT NOW()');
+    }
+    lines.push('  "updated_at" TIMESTAMPTZ DEFAULT NOW()');
+    // Foreign key constraints
+    for (const [fkCol, fkDef] of Object.entries(foreignKeys)) {
+        const refTable = sanitizeTableName(fkDef.references);
+        lines.push(`  FOREIGN KEY ("${fkCol}") REFERENCES "${refTable}"("${fkDef.column}") ON DELETE SET NULL`);
+    }
+    // Composite primary key for hypertable models
+    if (useCompositePK) {
+        lines.push(`  PRIMARY KEY ("id", "${hypertable.timeColumn}")`);
+    }
+    return `CREATE TABLE IF NOT EXISTS "${table}" (\n${lines.join(',\n')}\n)`;
+}
+/**
+ * Build HNSW index DDL for vector columns on a model.
+ */
+export function buildVectorIndexDDL(name, schema) {
+    const table = sanitizeTableName(schema.table);
+    const statements = [];
+    for (const [col] of Object.entries(schema.vectorColumns || {})) {
+        statements.push(`CREATE INDEX IF NOT EXISTS "idx_${table}_${col}_hnsw" ON "${table}" USING hnsw ("${col}" vector_cosine_ops) WITH (m = 16, ef_construction = 200)`);
+    }
+    return statements;
+}
+function getReferencedIdType(tableName, allSchemas) {
+    for (const schema of Object.values(allSchemas)) {
+        if (schema.table === tableName) {
+            return schema.idType === 'string' ? 'VARCHAR(255)' : 'INTEGER';
+        }
+    }
+    return 'INTEGER';
+}
+export { getTopologicalOrder } from '../schema-helpers.js';
+export function introspectViews() {
+    const orm = Orm.instance;
+    if (!orm.views)
+        return {};
+    const schemas = {};
+    for (const [viewKey, viewClass] of Object.entries(orm.views)) {
+        const name = camelCaseToKebabCase(viewKey.slice(0, -4)); // Remove 'View' suffix
+        const source = viewClass.source;
+        if (!source)
+            continue;
+        const model = new viewClass(name);
+        const columns = {};
+        const foreignKeys = {};
+        const aggregates = {};
+        const relationships = { belongsTo: {}, hasMany: {} };
+        for (const [key, property] of Object.entries(model)) {
+            if (key.startsWith('__'))
+                continue;
+            if (key === 'id')
+                continue;
+            if (property instanceof AggregateProperty) {
+                aggregates[key] = property;
+                continue;
+            }
+            const relInfo = getRelationshipInfo(property);
+            if (relInfo?.type === 'belongsTo') {
+                relationships.belongsTo[key] = relInfo.modelName;
+                if (relInfo.modelName) {
+                    const fkColumn = `${key}_id`;
+                    foreignKeys[fkColumn] = {
+                        references: sanitizeTableName(getPluralName(relInfo.modelName)),
+                        column: 'id',
+                    };
+                }
+            }
+            else if (relInfo?.type === 'hasMany') {
+                relationships.hasMany[key] = relInfo.modelName;
+            }
+            else if (property instanceof ModelProperty) {
+                const transforms = Orm.instance.transforms;
+                const prop = property;
+                columns[key] = getPgType(prop.type, transforms[prop.type]);
+            }
+        }
+        schemas[name] = {
+            viewName: sanitizeTableName(getPluralName(name)),
+            source,
+            groupBy: viewClass.groupBy || undefined,
+            columns,
+            foreignKeys,
+            aggregates,
+            relationships,
+            isView: true,
+            memory: false, // Views default to memory:false
+        };
+    }
+    return schemas;
+}
+export function buildViewDDL(name, viewSchema, modelSchemas = {}) {
+    if (!viewSchema.source) {
+        throw new Error(`View '${name}' must define a source model`);
+    }
+    const sourceModelName = viewSchema.source;
+    const sourceSchema = modelSchemas[sourceModelName];
+    const sourceTable = sanitizeTableName(sourceSchema
+        ? sourceSchema.table
+        : getPluralName(sourceModelName));
+    const selectColumns = [];
+    const joins = [];
+    const hasAggregates = Object.keys(viewSchema.aggregates || {}).length > 0;
+    const groupByField = viewSchema.groupBy;
+    // ID column: groupBy field or source table PK
+    if (groupByField) {
+        selectColumns.push(`"${sourceTable}"."${groupByField}" AS "id"`);
+    }
+    else {
+        selectColumns.push(`"${sourceTable}"."id" AS "id"`);
+    }
+    // Aggregate columns
+    for (const [key, aggProp] of Object.entries(viewSchema.aggregates || {})) {
+        // Use pgFunction if available, fall back to mysqlFunction
+        const fn = aggProp.pgFunction || aggProp.mysqlFunction;
+        if (aggProp.relationship === undefined) {
+            // Field-level aggregate (groupBy views)
+            if (aggProp.aggregateType === 'count') {
+                selectColumns.push(`COUNT(*) AS "${key}"`);
+            }
+            else {
+                selectColumns.push(`${fn}("${sourceTable}"."${aggProp.field}") AS "${key}"`);
+            }
+        }
+        else {
+            // Relationship aggregate
+            const relName = aggProp.relationship;
+            const relTable = sanitizeTableName(getPluralName(relName));
+            if (aggProp.aggregateType === 'count') {
+                selectColumns.push(`${fn}("${relTable}"."id") AS "${key}"`);
+            }
+            else {
+                const field = aggProp.field;
+                selectColumns.push(`${fn}("${relTable}"."${field}") AS "${key}"`);
+            }
+            // Add LEFT JOIN for the relationship if not already added
+            const joinKey = `${relTable}`;
+            if (!joins.find(j => j.table === joinKey)) {
+                const fkColumn = `${sourceModelName}_id`;
+                joins.push({
+                    table: relTable,
+                    condition: `"${relTable}"."${fkColumn}" = "${sourceTable}"."id"`
+                });
+            }
+        }
+    }
+    // Regular columns
+    for (const [key] of Object.entries(viewSchema.columns || {})) {
+        selectColumns.push(`"${sourceTable}"."${key}" AS "${key}"`);
+    }
+    // Build JOIN clauses
+    const joinClauses = joins.map(j => `LEFT JOIN "${j.table}" ON ${j.condition}`).join('\n  ');
+    // Build GROUP BY
+    let groupBy = '';
+    if (groupByField) {
+        groupBy = `\nGROUP BY "${sourceTable}"."${groupByField}"`;
+    }
+    else if (hasAggregates) {
+        groupBy = `\nGROUP BY "${sourceTable}"."id"`;
+    }
+    const viewName = sanitizeTableName(viewSchema.viewName);
+    const sql = `CREATE OR REPLACE VIEW "${viewName}" AS\nSELECT\n  ${selectColumns.join(',\n  ')}\nFROM "${sourceTable}"${joinClauses ? '\n  ' + joinClauses : ''}${groupBy}`;
+    return sql;
+}
+export function viewSchemasToSnapshot(viewSchemas) {
+    const snapshot = {};
+    for (const [name, schema] of Object.entries(viewSchemas)) {
+        snapshot[name] = {
+            viewName: schema.viewName,
+            source: schema.source,
+            ...(schema.groupBy ? { groupBy: schema.groupBy } : {}),
+            columns: { ...schema.columns },
+            foreignKeys: { ...schema.foreignKeys },
+            isView: true,
+            viewQuery: buildViewDDL(name, schema),
+        };
+    }
+    return snapshot;
+}
+export function schemasToSnapshot(schemas) {
+    const snapshot = {};
+    for (const [name, schema] of Object.entries(schemas)) {
+        snapshot[name] = {
+            table: schema.table,
+            idType: schema.idType,
+            columns: { ...schema.columns },
+            foreignKeys: { ...schema.foreignKeys },
+            ...(schema.vectorColumns && Object.keys(schema.vectorColumns).length > 0
+                ? { vectorColumns: { ...schema.vectorColumns } }
+                : {}),
+            ...(schema.hypertable ? { hypertable: schema.hypertable } : {}),
+        };
+    }
+    return snapshot;
+}

package/dist/postgres/type-map.d.ts

@@ -0,0 +1,23 @@
+interface TransformFn {
+    pgType?: string;
+    mysqlType?: string;
+    (...args: unknown[]): unknown;
+}
+declare const typeMap: Record<string, string>;
+/**
+ * Resolves a Stonyx ORM attribute type to a PostgreSQL column type.
+ *
+ * For built-in types, returns the mapped PostgreSQL type directly.
+ *
+ * For custom transforms (e.g. an `animal` transform that maps strings to ints):
+ *   - If the transform function exports a `pgType` property, that value is used.
+ *   - Otherwise, if `mysqlType` is defined, it is mapped to a PG equivalent.
+ *   - Otherwise, defaults to JSONB. Values are JSON-stringified on write and
+ *     JSON-parsed on read by PostgreSQL natively.
+ */
+export declare function getPgType(attrType: string, transformFn?: TransformFn): string;
+/**
+ * Returns a vector column type for the given dimensions.
+ */
+export declare function getVectorType(dimensions: number): string;
+export default typeMap;

package/dist/postgres/type-map.js

@@ -0,0 +1,56 @@
+const typeMap = {
+    string: 'VARCHAR(255)',
+    number: 'INTEGER',
+    float: 'REAL',
+    boolean: 'BOOLEAN',
+    date: 'TIMESTAMPTZ',
+    timestamp: 'BIGINT',
+    passthrough: 'TEXT',
+    trim: 'VARCHAR(255)',
+    uppercase: 'VARCHAR(255)',
+    ceil: 'INTEGER',
+    floor: 'INTEGER',
+    round: 'INTEGER',
+};
+/**
+ * Resolves a Stonyx ORM attribute type to a PostgreSQL column type.
+ *
+ * For built-in types, returns the mapped PostgreSQL type directly.
+ *
+ * For custom transforms (e.g. an `animal` transform that maps strings to ints):
+ *   - If the transform function exports a `pgType` property, that value is used.
+ *   - Otherwise, if `mysqlType` is defined, it is mapped to a PG equivalent.
+ *   - Otherwise, defaults to JSONB. Values are JSON-stringified on write and
+ *     JSON-parsed on read by PostgreSQL natively.
+ */
+export function getPgType(attrType, transformFn) {
+    if (typeMap[attrType])
+        return typeMap[attrType];
+    if (transformFn?.pgType)
+        return transformFn.pgType;
+    if (transformFn?.mysqlType)
+        return mysqlTypeToPg(transformFn.mysqlType);
+    return 'JSONB';
+}
+/**
+ * Returns a vector column type for the given dimensions.
+ */
+export function getVectorType(dimensions) {
+    if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 16000) {
+        throw new Error(`Invalid vector dimensions: ${dimensions}. Must be an integer between 1 and 16000.`);
+    }
+    return `vector(${dimensions})`;
+}
+function mysqlTypeToPg(mysqlType) {
+    const upper = mysqlType.toUpperCase();
+    if (upper === 'TINYINT(1)')
+        return 'BOOLEAN';
+    if (upper === 'INT' || upper === 'INT AUTO_INCREMENT')
+        return 'INTEGER';
+    if (upper === 'DATETIME')
+        return 'TIMESTAMPTZ';
+    if (upper === 'JSON')
+        return 'JSONB';
+    return mysqlType;
+}
+export default typeMap;

package/dist/record.d.ts

@@ -0,0 +1,75 @@
+import type Serializer from './serializer.js';
+interface ToJSONOptions {
+    fields?: Set<string>;
+    baseUrl?: string;
+}
+interface SerializeOptions {
+    update?: boolean;
+    serialize?: boolean;
+    transform?: boolean;
+    [key: string]: unknown;
+}
+interface UnloadOptions {
+    [key: string]: unknown;
+}
+interface RelationshipLinks {
+    self: string;
+    related: string;
+}
+interface RelationshipEntry {
+    data: {
+        type: string;
+        id: unknown;
+    } | {
+        type: string;
+        id: unknown;
+    }[] | null;
+    links?: RelationshipLinks;
+}
+interface JSONAPIResult {
+    attributes: {
+        [key: string]: unknown;
+    };
+    relationships: {
+        [key: string]: RelationshipEntry;
+    };
+    id: unknown;
+    type: string;
+    links?: {
+        self: string;
+    };
+}
+export default class Record {
+    /** @private */
+    __data: {
+        [key: string]: unknown;
+    };
+    /** @private */
+    __relationships: {
+        [key: string]: unknown;
+    };
+    /** @private */
+    __serialized: boolean;
+    /** @private */
+    __model: {
+        __name: string;
+        [key: string]: unknown;
+    };
+    /** @private */
+    __serializer: Serializer;
+    [key: string]: unknown;
+    constructor(model: {
+        __name: string;
+        [key: string]: unknown;
+    }, serializer: Serializer);
+    serialize(rawData?: unknown, options?: SerializeOptions): {
+        [key: string]: unknown;
+    };
+    format(): {
+        [key: string]: unknown;
+    };
+    toJSON(options?: ToJSONOptions): JSONAPIResult;
+    unload(options?: UnloadOptions): void;
+    clean(): void;
+}
+export {};

package/dist/record.js

@@ -0,0 +1,129 @@
+import { store } from '@stonyx/orm';
+import { getComputedProperties } from "./serializer.js";
+import { camelCaseToKebabCase } from '@stonyx/utils/string';
+import { getPluralName } from './plural-registry.js';
+export default class Record {
+    /** @private */
+    __data = {};
+    /** @private */
+    __relationships = {};
+    /** @private */
+    __serialized = false;
+    /** @private */
+    __model;
+    /** @private */
+    __serializer;
+    constructor(model, serializer) {
+        this.__model = model;
+        this.__serializer = serializer;
+    }
+    serialize(rawData, options = {}) {
+        const { __data: data } = this;
+        if (this.__serialized && !options.update) {
+            const relatedIds = {};
+            for (const [key, childRecord] of Object.entries(this.__relationships)) {
+                relatedIds[key] = Array.isArray(childRecord)
+                    ? childRecord.map((r) => r.id)
+                    : childRecord?.id ?? null;
+            }
+            return { ...data, ...relatedIds };
+        }
+        const normalizedData = this.__serializer.normalize(rawData);
+        this.__serializer.setProperties(normalizedData, this, options);
+        return data;
+    }
+    // Similar to serialize, but preserves top level relationship records
+    format() {
+        if (!this.__serialized)
+            throw new Error('Record must be serialized before being converted to JSON');
+        const { __data: data } = this;
+        const records = {};
+        for (const [key, childRecord] of Object.entries(this.__relationships)) {
+            if (Array.isArray(childRecord)) {
+                // Deduplicate by record ID — keep last occurrence (latest data wins)
+                const seen = new Set();
+                const unique = [];
+                for (let i = childRecord.length - 1; i >= 0; i--) {
+                    const r = childRecord[i];
+                    if (!seen.has(r.id)) {
+                        seen.add(r.id);
+                        unique.push(r);
+                    }
+                }
+                unique.reverse();
+                records[key] = unique.map((r) => r.serialize());
+            }
+            else {
+                records[key] = childRecord?.serialize() ?? null;
+            }
+        }
+        return { ...data, ...records };
+    }
+    // Formats record for JSON API output
+    toJSON(options = {}) {
+        if (!this.__serialized)
+            throw new Error('Record must be serialized before being converted to JSON');
+        const { fields, baseUrl } = options;
+        const { __data: data } = this;
+        const modelName = this.__model.__name;
+        const pluralizedModelName = getPluralName(modelName);
+        const recordId = data.id;
+        const relationships = {};
+        const attributes = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (key === 'id')
+                continue;
+            if (fields && !fields.has(key))
+                continue;
+            attributes[key] = value;
+        }
+        for (const [key, getter] of getComputedProperties(this.__model)) {
+            if (fields && !fields.has(key))
+                continue;
+            attributes[key] = getter.call(this);
+        }
+        for (const [key, childRecord] of Object.entries(this.__relationships)) {
+            if (fields && !fields.has(key))
+                continue;
+            const relationshipData = Array.isArray(childRecord)
+                ? childRecord.map((r) => ({ type: r.__model.__name, id: r.id }))
+                : childRecord ? { type: childRecord.__model.__name, id: childRecord.id } : null;
+            // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
+            const dasherizedKey = camelCaseToKebabCase(key);
+            relationships[dasherizedKey] = { data: relationshipData };
+            // Add links to relationship if baseUrl provided
+            if (baseUrl) {
+                relationships[dasherizedKey].links = {
+                    self: `${baseUrl}/${pluralizedModelName}/${recordId}/relationships/${dasherizedKey}`,
+                    related: `${baseUrl}/${pluralizedModelName}/${recordId}/${dasherizedKey}`
+                };
+            }
+        }
+        const result = {
+            attributes,
+            relationships,
+            id: recordId,
+            type: modelName,
+        };
+        // Add resource links if baseUrl provided
+        if (baseUrl) {
+            result.links = {
+                self: `${baseUrl}/${pluralizedModelName}/${recordId}`
+            };
+        }
+        return result;
+    }
+    unload(options = {}) {
+        store.unloadRecord(this.__model.__name, this.id, options);
+    }
+    clean() {
+        try {
+            for (const key of Object.keys(this)) {
+                delete this[key];
+            }
+        }
+        catch {
+            // Ignore errors during cleanup, as some keys may not be deletable
+        }
+    }
+}

package/dist/relationships.d.ts

@@ -0,0 +1,10 @@
+import type { HasManyMap, BelongsToMap, GlobalMap, PendingMap, PendingBelongsToMap } from './types/orm-types.js';
+export declare function getRelationships(type: string, sourceModel: string, targetModel: string, relationshipId?: string): Map<unknown, unknown> | undefined;
+export declare function getHasManyRelationships(sourceModel: string, targetModel: string): Map<unknown, unknown> | undefined;
+/** Typed accessors for the relationship registry */
+export declare function getHasManyRegistry(): HasManyMap;
+export declare function getBelongsToRegistry(): BelongsToMap;
+export declare function getGlobalRegistry(): GlobalMap;
+export declare function getPendingRegistry(): PendingMap;
+export declare function getPendingBelongsToRegistry(): PendingBelongsToMap;
+export declare const TYPES: string[];

package/dist/relationships.js

@@ -0,0 +1,41 @@
+import { relationships } from '@stonyx/orm';
+// TODO: Refactor mapping to remove a level of iteration
+export function getRelationships(type, sourceModel, targetModel, relationshipId) {
+    let allRelationships = relationships.get(type);
+    if (!allRelationships) {
+        allRelationships = new Map();
+        relationships.set(type, allRelationships);
+    }
+    // create relationship map for this type of it doesn't already exist
+    if (!allRelationships.has(sourceModel))
+        allRelationships.set(sourceModel, new Map());
+    const modelRelationship = allRelationships.get(sourceModel);
+    if (!modelRelationship)
+        return undefined;
+    if (!modelRelationship.has(targetModel))
+        modelRelationship.set(targetModel, new Map());
+    const relationship = modelRelationship.get(targetModel);
+    // TODO: Determine whether already having id should be handled differently
+    //if (relationship.has(relationshipId)) return;
+    return relationship;
+}
+export function getHasManyRelationships(sourceModel, targetModel) {
+    return relationships.get('hasMany')?.get(sourceModel)?.get(targetModel);
+}
+/** Typed accessors for the relationship registry */
+export function getHasManyRegistry() {
+    return relationships.get('hasMany');
+}
+export function getBelongsToRegistry() {
+    return relationships.get('belongsTo');
+}
+export function getGlobalRegistry() {
+    return relationships.get('global');
+}
+export function getPendingRegistry() {
+    return relationships.get('pending');
+}
+export function getPendingBelongsToRegistry() {
+    return relationships.get('pendingBelongsTo');
+}
+export const TYPES = ['global', 'hasMany', 'belongsTo', 'pending'];

package/dist/schema-helpers.d.ts

@@ -0,0 +1,20 @@
+import type { ModelSchema } from './types/orm-types.js';
+export interface SchemaRelationshipInfo {
+    type: 'belongsTo' | 'hasMany';
+    modelName: string | null;
+}
+/**
+ * Detect relationship type and target model from a model property function.
+ * Returns null if the property is not a relationship.
+ */
+export declare function getRelationshipInfo(property: unknown): SchemaRelationshipInfo | null;
+/**
+ * Sanitize a model/table name for use in SQL identifiers.
+ * Replaces hyphens and slashes with underscores.
+ */
+export declare function sanitizeTableName(name: string): string;
+/**
+ * Sort model schemas in dependency order (belongsTo targets before dependents).
+ * Uses depth-first traversal to ensure referenced tables are created first.
+ */
+export declare function getTopologicalOrder(schemas: Record<string, ModelSchema>): string[];