ts-prorm-orm 1.1.0 → 1.2.0

package/dist/external-fields/adapters.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Adapters normalizing the shipped object/key-value stores to one interface.
+ *
+ * The stores under `src/nosql/` deliberately expose each engine's own API, so
+ * their method names and shapes differ:
+ *
+ *   S3 / R2      putObject(bucket, key, body)   getObject -> { body }   deleteObject   objectExists
+ *   MinIO        putObject(bucket, key, data)   getObject -> { body }   removeObject   statObject
+ *   GCS          uploadObject(bucket, key, d)   downloadObject -> Buffer deleteObject  objectExists
+ *   Azure Blob   uploadBlob(container, key, d)  downloadBlob -> Buffer  deleteBlob     blobExists
+ *   Redis        set(key, value)                get -> string | null    del            exists -> number
+ *
+ * An external field shouldn't have to care which of those it is talking to.
+ * `toExternalStoreAdapter()` duck-types a store and wraps it, so registering one
+ * is a single call with no adapter to write.
+ */
+/** A value an external field can hold. */
+export type ExternalValue = Buffer | string | Uint8Array;
+/** Options accepted when writing a value. */
+export interface ExternalPutOptions {
+    contentType?: string;
+}
+/**
+ * The uniform surface external fields are written against.
+ *
+ * `container` is a bucket (S3/R2/MinIO/GCS) or container (Azure). Stores with no
+ * container concept - Redis - ignore it.
+ */
+export interface ExternalStoreAdapter {
+    /** Identifies the underlying engine, for error messages. */
+    readonly engine: string;
+    /** Whether this engine has a bucket/container concept. */
+    readonly usesContainer: boolean;
+    put(container: string | undefined, key: string, value: ExternalValue, options?: ExternalPutOptions): Promise<void>;
+    get(container: string | undefined, key: string): Promise<Buffer | null>;
+    delete(container: string | undefined, key: string): Promise<void>;
+    exists(container: string | undefined, key: string): Promise<boolean>;
+}
+/** Raised when a store can't be adapted or a required container is missing. */
+export declare class ExternalStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Wrap one of the shipped stores - or anything with a compatible shape - in the
+ * uniform adapter interface.
+ *
+ * Detection prefers the store's own `name`, falling back to method duck-typing
+ * so a custom or future store still works without a code change here.
+ */
+export declare function toExternalStoreAdapter(store: unknown): ExternalStoreAdapter;

package/dist/external-fields/adapters.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * Adapters normalizing the shipped object/key-value stores to one interface.
+ *
+ * The stores under `src/nosql/` deliberately expose each engine's own API, so
+ * their method names and shapes differ:
+ *
+ *   S3 / R2      putObject(bucket, key, body)   getObject -> { body }   deleteObject   objectExists
+ *   MinIO        putObject(bucket, key, data)   getObject -> { body }   removeObject   statObject
+ *   GCS          uploadObject(bucket, key, d)   downloadObject -> Buffer deleteObject  objectExists
+ *   Azure Blob   uploadBlob(container, key, d)  downloadBlob -> Buffer  deleteBlob     blobExists
+ *   Redis        set(key, value)                get -> string | null    del            exists -> number
+ *
+ * An external field shouldn't have to care which of those it is talking to.
+ * `toExternalStoreAdapter()` duck-types a store and wraps it, so registering one
+ * is a single call with no adapter to write.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalStoreError = void 0;
+exports.toExternalStoreAdapter = toExternalStoreAdapter;
+/** Raised when a store can't be adapted or a required container is missing. */
+class ExternalStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ExternalStoreError';
+    }
+}
+exports.ExternalStoreError = ExternalStoreError;
+/** Coerce whatever a store handed back into a Buffer. */
+async function toBuffer(body) {
+    if (body === null || body === undefined)
+        return null;
+    if (Buffer.isBuffer(body))
+        return body;
+    if (typeof body === 'string')
+        return Buffer.from(body);
+    if (body instanceof Uint8Array)
+        return Buffer.from(body);
+    // AWS SDK v3 bodies expose transformToByteArray(); node streams don't.
+    const maybe = body;
+    if (typeof maybe.transformToByteArray === 'function') {
+        return Buffer.from(await maybe.transformToByteArray());
+    }
+    // Async iterable (node Readable, or a web stream via Symbol.asyncIterator).
+    const iterable = body;
+    if (typeof iterable?.[Symbol.asyncIterator] === 'function') {
+        const chunks = [];
+        for await (const chunk of iterable) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+    }
+    throw new ExternalStoreError(`Could not read the object body: unsupported type ${Object.prototype.toString.call(body)}`);
+}
+function requireContainer(container, engine) {
+    if (!container) {
+        throw new ExternalStoreError(`${engine} needs a bucket/container. Pass \`bucket\` on the @ExternalField, ` +
+            `or \`defaultBucket\` when registering the store.`);
+    }
+    return container;
+}
+/** S3, R2 and any store with the putObject/getObject/deleteObject shape. */
+function s3StyleAdapter(store, engine) {
+    return {
+        engine,
+        usesContainer: true,
+        async put(container, key, value, options) {
+            await store.putObject(requireContainer(container, engine), key, value, {
+                ...(options?.contentType ? { contentType: options.contentType } : {}),
+            });
+        },
+        async get(container, key) {
+            const res = await store.getObject(requireContainer(container, engine), key);
+            return toBuffer(res?.body ?? res);
+        },
+        async delete(container, key) {
+            const c = requireContainer(container, engine);
+            if (typeof store.deleteObject === 'function')
+                await store.deleteObject(c, key);
+            else
+                await store.removeObject(c, key);
+        },
+        async exists(container, key) {
+            const c = requireContainer(container, engine);
+            if (typeof store.objectExists === 'function')
+                return store.objectExists(c, key);
+            // MinIO has no objectExists; statObject throws when absent.
+            try {
+                await store.statObject(c, key);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+/** Google Cloud Storage: upload/downloadObject, download returns a Buffer. */
+function gcsAdapter(store) {
+    return {
+        engine: 'gcs',
+        usesContainer: true,
+        async put(container, key, value, options) {
+            await store.uploadObject(requireContainer(container, 'gcs'), key, value, {
+                ...(options?.contentType ? { contentType: options.contentType } : {}),
+            });
+        },
+        async get(container, key) {
+            return toBuffer(await store.downloadObject(requireContainer(container, 'gcs'), key));
+        },
+        async delete(container, key) {
+            await store.deleteObject(requireContainer(container, 'gcs'), key);
+        },
+        async exists(container, key) {
+            return store.objectExists(requireContainer(container, 'gcs'), key);
+        },
+    };
+}
+/** Azure Blob Storage: upload/download/deleteBlob against a container. */
+function azureBlobAdapter(store) {
+    return {
+        engine: 'azure-blob',
+        usesContainer: true,
+        async put(container, key, value) {
+            await store.uploadBlob(requireContainer(container, 'azure-blob'), key, value);
+        },
+        async get(container, key) {
+            return toBuffer(await store.downloadBlob(requireContainer(container, 'azure-blob'), key));
+        },
+        async delete(container, key) {
+            await store.deleteBlob(requireContainer(container, 'azure-blob'), key);
+        },
+        async exists(container, key) {
+            return store.blobExists(requireContainer(container, 'azure-blob'), key);
+        },
+    };
+}
+/**
+ * Redis and Redis-compatible key-value stores.
+ *
+ * No container concept: any configured bucket is folded into the key as a
+ * prefix, so `bucket: 'avatars'` stores under `avatars:<key>`.
+ */
+function redisAdapter(store, engine) {
+    const compose = (container, key) => container ? `${container}:${key}` : key;
+    return {
+        engine,
+        usesContainer: false,
+        async put(container, key, value) {
+            // Redis values are strings; binary payloads round-trip via base64 so a
+            // Buffer written is a Buffer read back.
+            const encoded = Buffer.isBuffer(value) || value instanceof Uint8Array
+                ? Buffer.from(value).toString('base64')
+                : String(value);
+            await store.set(compose(container, key), encoded);
+        },
+        async get(container, key) {
+            const raw = await store.get(compose(container, key));
+            if (raw === null || raw === undefined)
+                return null;
+            return Buffer.from(String(raw), 'base64');
+        },
+        async delete(container, key) {
+            await store.del(compose(container, key));
+        },
+        async exists(container, key) {
+            return (await store.exists(compose(container, key))) > 0;
+        },
+    };
+}
+/** True when the object already satisfies the adapter interface. */
+function isAdapter(x) {
+    return (x &&
+        typeof x.put === 'function' &&
+        typeof x.get === 'function' &&
+        typeof x.delete === 'function' &&
+        typeof x.exists === 'function' &&
+        typeof x.engine === 'string');
+}
+/**
+ * Wrap one of the shipped stores - or anything with a compatible shape - in the
+ * uniform adapter interface.
+ *
+ * Detection prefers the store's own `name`, falling back to method duck-typing
+ * so a custom or future store still works without a code change here.
+ */
+function toExternalStoreAdapter(store) {
+    if (isAdapter(store))
+        return store;
+    const s = store;
+    if (!s || typeof s !== 'object') {
+        throw new ExternalStoreError('registerStore() expects a store instance or an adapter object.');
+    }
+    const name = typeof s.name === 'string' ? s.name : '';
+    switch (name) {
+        case 's3':
+        case 'r2':
+        case 'minio':
+            return s3StyleAdapter(s, name);
+        case 'gcs':
+            return gcsAdapter(s);
+        case 'azure-blob':
+            return azureBlobAdapter(s);
+        case 'redis':
+        case 'upstash':
+        case 'vercel-kv':
+        case 'memcached':
+            return redisAdapter(s, name || 'redis');
+    }
+    // Unknown store: infer from the methods it actually has.
+    if (typeof s.putObject === 'function' && typeof s.getObject === 'function') {
+        return s3StyleAdapter(s, name || 'object-store');
+    }
+    if (typeof s.uploadObject === 'function' && typeof s.downloadObject === 'function') {
+        return gcsAdapter(s);
+    }
+    if (typeof s.uploadBlob === 'function' && typeof s.downloadBlob === 'function') {
+        return azureBlobAdapter(s);
+    }
+    if (typeof s.get === 'function' && typeof s.set === 'function' && typeof s.del === 'function') {
+        return redisAdapter(s, name || 'key-value');
+    }
+    throw new ExternalStoreError(`Don't know how to use ${name ? `store '${name}'` : 'this store'} for external fields. ` +
+        `Expected an object store (putObject/getObject), a blob store ` +
+        `(uploadObject/downloadObject or uploadBlob/downloadBlob), a key-value store ` +
+        `(get/set/del), or an object implementing ExternalStoreAdapter.`);
+}

package/dist/external-fields/decorator.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `@ExternalField` — a model field whose *contents* live in an object or
+ * key-value store while the row lives in the database.
+ *
+ * The table column holds only a reference (the object key). Reading and writing
+ * the payload goes through a store registered with `prorm.registerStore()`, so
+ * the connection between the row and the object is maintained by the ORM
+ * instead of by hand.
+ *
+ *   prorm.registerStore('assets', s3Store, { defaultBucket: 'avatars' });
+ *
+ *   @Table()
+ *   class User extends Model {
+ *     @Column(DataTypes.STRING) declare name: string;
+ *
+ *     @ExternalField({ store: 'assets', contentType: 'image/png' })
+ *     declare avatar: Buffer;
+ *   }
+ *
+ *   const user = await User.findByPk(1);
+ *   await user.loadAvatar();        // GET, populates user.avatar
+ *   user.avatar = newBytes;
+ *   await user.save();              // PUT, then persists the key column
+ *
+ * The key column (`avatarKey` by default) is registered automatically, so it
+ * does not need its own `@Column`.
+ */
+/** How a stored payload is materialized when read back. */
+export type ExternalEncoding = 'buffer' | 'utf8' | 'json';
+export interface ExternalFieldOptions {
+    /** Name the store was registered under with `prorm.registerStore()`. */
+    store: string;
+    /**
+     * Bucket / container to store objects in. Falls back to the store's
+     * `defaultBucket`. Key-value stores fold this into the key as a prefix.
+     */
+    bucket?: string;
+    /**
+     * Column holding the object key. Defaults to `<field>Key` (e.g. `avatarKey`).
+     * Registered automatically as a nullable STRING.
+     */
+    keyColumn?: string;
+    /**
+     * Prefix for generated keys. Defaults to `<field>/`. Only used when a value
+     * is written to a field that has no key yet.
+     */
+    keyPrefix?: string;
+    /** Content type recorded on write, where the store supports it. */
+    contentType?: string;
+    /**
+     * How to materialize the payload on read:
+     *  - `buffer` (default) — a Buffer, for binary data
+     *  - `utf8` — a string
+     *  - `json` — parsed via JSON.parse, stringified on write
+     */
+    encoding?: ExternalEncoding;
+}
+/** Resolved per-field metadata. */
+export interface ExternalFieldMeta extends ExternalFieldOptions {
+    /** The model property (e.g. `avatar`). */
+    field: string;
+    keyColumn: string;
+    keyPrefix: string;
+    encoding: ExternalEncoding;
+}
+/**
+ * Mark a property as backed by an external store.
+ */
+export declare function ExternalField(options: ExternalFieldOptions): PropertyDecorator;
+/** All external fields declared on a model, including inherited ones. */
+export declare function getExternalFields(modelName: string): ExternalFieldMeta[];
+/** One external field's metadata, or undefined. */
+export declare function getExternalField(modelName: string, field: string): ExternalFieldMeta | undefined;
+/** True when the model declares at least one external field. */
+export declare function hasExternalFields(modelName: string): boolean;
+/** Clear registered metadata (used by tests). */
+export declare function clearExternalFieldMetadata(): void;

package/dist/external-fields/decorator.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * `@ExternalField` — a model field whose *contents* live in an object or
+ * key-value store while the row lives in the database.
+ *
+ * The table column holds only a reference (the object key). Reading and writing
+ * the payload goes through a store registered with `prorm.registerStore()`, so
+ * the connection between the row and the object is maintained by the ORM
+ * instead of by hand.
+ *
+ *   prorm.registerStore('assets', s3Store, { defaultBucket: 'avatars' });
+ *
+ *   @Table()
+ *   class User extends Model {
+ *     @Column(DataTypes.STRING) declare name: string;
+ *
+ *     @ExternalField({ store: 'assets', contentType: 'image/png' })
+ *     declare avatar: Buffer;
+ *   }
+ *
+ *   const user = await User.findByPk(1);
+ *   await user.loadAvatar();        // GET, populates user.avatar
+ *   user.avatar = newBytes;
+ *   await user.save();              // PUT, then persists the key column
+ *
+ * The key column (`avatarKey` by default) is registered automatically, so it
+ * does not need its own `@Column`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalField = ExternalField;
+exports.getExternalFields = getExternalFields;
+exports.getExternalField = getExternalField;
+exports.hasExternalFields = hasExternalFields;
+exports.clearExternalFieldMetadata = clearExternalFieldMetadata;
+const decorators_1 = require("../models/decorators");
+const data_types_1 = require("../models/data-types");
+/** modelName -> field -> metadata */
+const externalFieldMetadata = new Map();
+/**
+ * Mark a property as backed by an external store.
+ */
+function ExternalField(options) {
+    return function (target, propertyKey) {
+        const modelName = target?.constructor?.name;
+        if (!modelName)
+            return;
+        const field = String(propertyKey);
+        const keyColumn = options.keyColumn || `${field}Key`;
+        if (!externalFieldMetadata.has(modelName)) {
+            externalFieldMetadata.set(modelName, new Map());
+        }
+        externalFieldMetadata.get(modelName).set(field, {
+            ...options,
+            field,
+            keyColumn,
+            keyPrefix: options.keyPrefix ?? `${field}/`,
+            encoding: options.encoding ?? 'buffer',
+        });
+        // Register the key column so the user doesn't have to declare it. The
+        // payload itself is not a column - only the reference is persisted.
+        (0, decorators_1.Attribute)(data_types_1.DataTypes.STRING(512))(target, keyColumn);
+    };
+}
+/** All external fields declared on a model, including inherited ones. */
+function getExternalFields(modelName) {
+    const own = externalFieldMetadata.get(modelName);
+    return own ? Array.from(own.values()) : [];
+}
+/** One external field's metadata, or undefined. */
+function getExternalField(modelName, field) {
+    return externalFieldMetadata.get(modelName)?.get(field);
+}
+/** True when the model declares at least one external field. */
+function hasExternalFields(modelName) {
+    return (externalFieldMetadata.get(modelName)?.size ?? 0) > 0;
+}
+/** Clear registered metadata (used by tests). */
+function clearExternalFieldMetadata() {
+    externalFieldMetadata.clear();
+}

package/dist/external-fields/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * External fields — model fields whose contents live in an object or key-value
+ * store while the row lives in the database.
+ */
+export { ExternalField, getExternalFields, getExternalField, hasExternalFields, clearExternalFieldMetadata, } from './decorator';
+export type { ExternalFieldOptions, ExternalFieldMeta, ExternalEncoding } from './decorator';
+export { toExternalStoreAdapter, ExternalStoreError, } from './adapters';
+export type { ExternalStoreAdapter, ExternalPutOptions, ExternalValue, } from './adapters';
+export { ExternalStoreRegistry, attachExternalFields } from './runtime';
+export type { RegisterStoreOptions, RegisteredStore } from './runtime';

package/dist/external-fields/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * External fields — model fields whose contents live in an object or key-value
+ * store while the row lives in the database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachExternalFields = exports.ExternalStoreRegistry = exports.ExternalStoreError = exports.toExternalStoreAdapter = exports.clearExternalFieldMetadata = exports.hasExternalFields = exports.getExternalField = exports.getExternalFields = exports.ExternalField = void 0;
+var decorator_1 = require("./decorator");
+Object.defineProperty(exports, "ExternalField", { enumerable: true, get: function () { return decorator_1.ExternalField; } });
+Object.defineProperty(exports, "getExternalFields", { enumerable: true, get: function () { return decorator_1.getExternalFields; } });
+Object.defineProperty(exports, "getExternalField", { enumerable: true, get: function () { return decorator_1.getExternalField; } });
+Object.defineProperty(exports, "hasExternalFields", { enumerable: true, get: function () { return decorator_1.hasExternalFields; } });
+Object.defineProperty(exports, "clearExternalFieldMetadata", { enumerable: true, get: function () { return decorator_1.clearExternalFieldMetadata; } });
+var adapters_1 = require("./adapters");
+Object.defineProperty(exports, "toExternalStoreAdapter", { enumerable: true, get: function () { return adapters_1.toExternalStoreAdapter; } });
+Object.defineProperty(exports, "ExternalStoreError", { enumerable: true, get: function () { return adapters_1.ExternalStoreError; } });
+var runtime_1 = require("./runtime");
+Object.defineProperty(exports, "ExternalStoreRegistry", { enumerable: true, get: function () { return runtime_1.ExternalStoreRegistry; } });
+Object.defineProperty(exports, "attachExternalFields", { enumerable: true, get: function () { return runtime_1.attachExternalFields; } });

package/dist/external-fields/runtime.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Runtime for `@ExternalField`: the store registry, and the per-instance
+ * accessors that keep a row's key column and the stored payload in step.
+ */
+import { ExternalStoreAdapter } from './adapters';
+/** Options accepted when registering a store. */
+export interface RegisterStoreOptions {
+    /** Bucket/container used by fields that don't name one. */
+    defaultBucket?: string;
+}
+/** A store registered for use by external fields. */
+export interface RegisteredStore {
+    name: string;
+    adapter: ExternalStoreAdapter;
+    defaultBucket?: string;
+}
+/** Registry of stores, keyed by the name given to `registerStore()`. */
+export declare class ExternalStoreRegistry {
+    private stores;
+    register(name: string, store: unknown, options?: RegisterStoreOptions): void;
+    get(name: string): RegisteredStore;
+    has(name: string): boolean;
+    clear(): void;
+}
+/**
+ * Attach external-field accessors to a row instance.
+ *
+ * Each field `avatar` gets:
+ *   - `avatar`            a non-enumerable accessor holding the materialized value
+ *   - `loadAvatar()`      read from the store into `avatar`
+ *   - `saveAvatar(value)` write to the store and persist the key column
+ *   - `deleteAvatar()`    remove from the store and null the key column
+ *
+ * The accessor is deliberately **non-enumerable** so `save()`'s sweep over the
+ * instance's own keys doesn't try to persist a Buffer into a column that
+ * doesn't exist. Assigning to it records a pending write, which the wrapped
+ * `save()` flushes before the row is written.
+ */
+export declare function attachExternalFields(rowInstance: any, dataValues: Record<string, any>, modelName: string, tableName: string, registry: ExternalStoreRegistry): void;