@ultimabase/files 0.0.0-stage → 0.1.1

package/dist/upload.js

@@ -0,0 +1,206 @@
+// An upload (D-152): its field, its size and its type checked, its pending
+// `FilesBlob` row inserted as its caller, then its object stored. When it
+// fails, its objects and its rows are deleted.
+import { randomUUID } from 'node:crypto';
+import { fileTypeFromBuffer } from 'file-type';
+import { isMaster, PublicError } from 'ultimabase';
+import { defaultMaxSize } from './field.js';
+import { bytesOf } from './memory.js';
+import { FilesBlob, hour, M } from './model.js';
+import { settled } from './storage.js';
+import { runningOf } from './values.js';
+/** How many first bytes the type is read from, as `file-type` reads them. */
+const sampleSize = 4100;
+/** An inline value's JSON, at most. */
+const inlineSize = 2048;
+const invalid = (path, message) => new PublicError('VALIDATION_FAILED', 'Invalid upload.', {
+    details: { issues: [{ path: [path], message }] },
+});
+function fieldOf(target) {
+    const [model = '', field = ''] = target.split('.');
+    const options = runningOf().fields.get(model)?.get(field);
+    if (options === undefined) {
+        const message = target === ''
+            ? 'Expected a file field: Model.field.'
+            : `${target} is not a file field.`;
+        throw invalid('for', message);
+    }
+    return options;
+}
+function concat(chunks, length) {
+    const bytes = new Uint8Array(length);
+    let at = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, at);
+        at += chunk.length;
+    }
+    return bytes;
+}
+/** The first bytes of a body, and the body to store, whole again. */
+async function sampled(body) {
+    if (body instanceof Uint8Array)
+        return { sample: body, body };
+    const reader = body.getReader();
+    const chunks = [];
+    let length = 0;
+    while (length < sampleSize) {
+        const { done, value } = await reader.read();
+        if (done) {
+            const whole = concat(chunks, length);
+            return { sample: whole, body: whole };
+        }
+        chunks.push(value);
+        length += value.length;
+    }
+    const sample = concat(chunks, length);
+    const rest = new ReadableStream({
+        start: (controller) => {
+            controller.enqueue(sample);
+        },
+        pull: async (controller) => {
+            const { done, value } = await reader.read();
+            if (done)
+                controller.close();
+            else
+                controller.enqueue(value);
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+    return { sample, body: rest };
+}
+const matches = (accept, type) => accept.some((pattern) => pattern.endsWith('/*')
+    ? type.startsWith(pattern.slice(0, -1))
+    : pattern === type);
+/** The type a file is stored with, and whether it is served as a download. */
+async function typeOf(sample, declared, accept) {
+    const detected = (await fileTypeFromBuffer(sample))?.mime;
+    if (detected !== undefined &&
+        (accept === undefined || matches(accept, detected))) {
+        return { type: detected, attachment: detected === 'image/svg+xml' };
+    }
+    const [media = ''] = (declared ?? '').split(';');
+    const type = media.trim().toLowerCase();
+    if (detected === undefined && accept === undefined) {
+        return {
+            type: type === '' ? 'application/octet-stream' : type,
+            attachment: true,
+        };
+    }
+    // An undetected type is taken as declared only when accept lists it.
+    if (detected === undefined && accept?.includes(type) === true) {
+        return { type, attachment: true };
+    }
+    throw new PublicError('UNSUPPORTED_MEDIA_TYPE', `${detected ?? (type === '' ? 'An undetected type' : type)} is not accepted.`);
+}
+/** A variant's own type, served as a download unless its bytes say it. */
+async function attachmentOf(body, type) {
+    const detected = (await fileTypeFromBuffer(body))?.mime;
+    return detected !== type || type === 'image/svg+xml';
+}
+async function inlineValue(key, given, file) {
+    const run = typeof given === 'function' ? given : given.run;
+    let value = await run(file);
+    if (typeof given !== 'function') {
+        const result = await given.schema['~standard'].validate(value);
+        if (result.issues !== undefined) {
+            throw new TypeError(`The inline ${key} does not match its schema.`);
+        }
+        value = result.value;
+    }
+    const json = JSON.stringify(value);
+    if (json === undefined ||
+        new TextEncoder().encode(json).length > inlineSize) {
+        throw new TypeError(`The inline ${key} is not JSON of 2 KB at most.`);
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- JSON.parse gives JSON.
+    return JSON.parse(json);
+}
+const uploaderOf = (caller) => isMaster(caller) ? 'master' : caller.kind === 'user' ? caller.user.id : null;
+/** What a buffered upload made: its inline values and its variants. */
+async function madeOf(options, file) {
+    const inline = Object.entries(options.inline ?? {}).map(async ([key, given]) => [key, await inlineValue(key, given, file)]);
+    const variants = Object.entries(options.variants ?? {}).map(async ([key, variant]) => {
+        const { body, type } = await variant(file);
+        return [key, body, type];
+    });
+    const [values, made] = await Promise.all([
+        Promise.all(inline),
+        Promise.all(variants),
+    ]);
+    return { inline: Object.fromEntries(values), variants: made };
+}
+/**
+ * Stores a file for `options.for`, as `POST /files` does, and gives its id,
+ * which a write of that field takes. `size` is the body's length in bytes.
+ */
+export async function upload(body, size, options) {
+    const { name, as: caller = { kind: 'anonymous' } } = options;
+    const field = fieldOf(options.for);
+    if (name === '')
+        throw invalid('name', 'Expected a file name.');
+    const maxSize = field.maxSize ?? defaultMaxSize;
+    if (size > maxSize) {
+        throw new PublicError('PAYLOAD_TOO_LARGE', `The file is over ${maxSize} bytes.`);
+    }
+    const buffered = field.inline !== undefined || field.variants !== undefined;
+    const read = buffered
+        ? { sample: await bytesOf(body), body: undefined }
+        : await sampled(body);
+    const { type, attachment } = await typeOf(read.sample, options.type, field.accept);
+    const { storage, logger } = runningOf();
+    const prefix = field.public === true ? 'public' : 'private';
+    const keyOf = () => `${prefix}/${randomUUID()}`;
+    const uploadedBy = uploaderOf(caller);
+    const deleteAfter = new Date(Date.now() + hour);
+    const blob = { field: options.for, uploadedBy, state: 'pending', deleteAfter };
+    const main = await FilesBlob.create({ data: { ...blob, key: keyOf(), name, type, size } }, { as: caller });
+    const keys = [main.key];
+    const ids = [main.id];
+    try {
+        if (read.body !== undefined) {
+            await storage.put(main.key, read.body, { type, size, attachment });
+            return { id: main.id };
+        }
+        const bytes = read.sample;
+        if (bytes.length !== size) {
+            throw invalid('size', `The file has ${bytes.length} bytes, not ${size}.`);
+        }
+        const made = await madeOf(field, { body: bytes, type, name });
+        const variants = await settled(made.variants.map(async ([key, variantBody, variantType]) => {
+            const row = await FilesBlob.create({
+                data: {
+                    ...blob,
+                    key: keyOf(),
+                    name: key,
+                    type: variantType,
+                    size: variantBody.length,
+                    variantOf: main.id,
+                },
+            }, M);
+            keys.push(row.key);
+            ids.push(row.id);
+            return { row, body: variantBody };
+        }));
+        await settled([
+            storage.put(main.key, bytes, { type, size, attachment }),
+            ...variants.map(async ({ row, body: variantBody }) => storage.put(row.key, variantBody, {
+                type: row.type,
+                size: row.size,
+                attachment: await attachmentOf(variantBody, row.type),
+            })),
+        ]);
+        await FilesBlob.update({ where: { id: main.id }, data: { inline: made.inline } }, M);
+        return { id: main.id };
+    }
+    catch (error) {
+        // The sweep deletes what this cannot: the rows expire within the hour.
+        try {
+            await Promise.all(keys.map((key) => storage.delete(key)));
+            await FilesBlob.deleteMany({ where: { id: { in: ids } } }, M);
+        }
+        catch (cleanup) {
+            logger.warn({ err: cleanup }, 'A failed upload was not cleaned up.');
+        }
+        throw error;
+    }
+}

package/dist/values.d.ts

@@ -0,0 +1,81 @@
+import type { CallerRule, JsonValue, Logger } from 'ultimabase';
+import type { FileOptions } from './field.ts';
+import type { FileStorage } from './storage.ts';
+/** A variant as a client reads it. */
+export interface FileVariant {
+    readonly type: string;
+    readonly size: number;
+    readonly url: string;
+}
+/** What a file field's value holds. */
+export interface FileValue<I extends object = {
+    readonly [key: string]: JsonValue | null;
+}, V extends object = {
+    readonly [key: string]: FileVariant | null;
+}> {
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    readonly size: number;
+    /** Stable for a public file, presigned for one hour for a private one. */
+    readonly url: string;
+    readonly inline: I;
+    readonly variants: V;
+}
+/** The copy of a variant's metadata the row stores. */
+export interface StoredVariant {
+    readonly key: string;
+    readonly type: string;
+    readonly size: number;
+}
+/** The copy of a file's metadata the row stores; `FilesBlob` is the truth. */
+export interface StoredFile {
+    readonly id: string;
+    readonly key: string;
+    readonly name: string;
+    readonly type: string;
+    readonly size: number;
+    readonly inline: {
+        readonly [key: string]: JsonValue;
+    };
+    readonly variants: {
+        readonly [key: string]: StoredVariant;
+    };
+}
+/** What a field's options say of its value's keys. */
+export interface Keys {
+    readonly inline: readonly string[];
+    readonly variants: readonly string[];
+}
+/** How a write changes a field's files, before the hooks resolve it. */
+export type Operation = 'set' | 'push' | 'pushUnique' | 'remove';
+/** The ids a write gives, which the plugin's hooks resolve to files. */
+export declare class Pending {
+    readonly operation: Operation;
+    readonly ids: readonly string[];
+    constructor(operation: Operation, ids: readonly string[]);
+}
+/** What the running application gives the plugin. */
+export interface Running {
+    readonly storage: FileStorage;
+    /** Who may upload; Master always may. */
+    readonly upload: CallerRule;
+    /** Each model's file fields, with their options. */
+    readonly fields: ReadonlyMap<string, ReadonlyMap<string, FileOptions>>;
+    readonly logger: Logger;
+}
+export declare function useRunning(given: Running | undefined): void;
+export declare function runningOf(): Running;
+/** The value code reads of a file, its URLs signed now. */
+export declare function fileValue(stored: StoredFile, keys: Keys): FileValue;
+/** Whether a value is a file the plugin resolved. */
+export declare const isFile: (value: unknown) => value is FileValue;
+/** The copy the row stores of a value code holds. */
+export declare function copyOf(value: unknown, where: string): StoredFile;
+/** A stored copy, read back from the row; any other value is a bug. */
+export declare function storedFile(value: unknown, where: string): StoredFile;
+/** A copy as the row's JSON column stores it. */
+export declare const storedJson: (copy: StoredFile) => JsonValue;
+/** A value as a client reads it. */
+export declare const fileJson: (value: FileValue) => JsonValue;
+//# sourceMappingURL=values.d.ts.map

package/dist/values.d.ts.map

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

package/dist/values.js

@@ -0,0 +1,125 @@
+/** The ids a write gives, which the plugin's hooks resolve to files. */
+export class Pending {
+    operation;
+    ids;
+    constructor(operation, ids) {
+        this.operation = operation;
+        this.ids = ids;
+    }
+}
+// The running application's: one runs at a time in a process.
+let running;
+export function useRunning(given) {
+    running = given;
+}
+export function runningOf() {
+    if (running === undefined)
+        throw new Error('filesPlugin has not started.');
+    return running;
+}
+/** Each value code holds, with the copy the row stores. */
+const copies = new WeakMap();
+/** The value code reads of a file, its URLs signed now. */
+export function fileValue(stored, keys) {
+    const { storage } = runningOf();
+    const variants = {};
+    for (const key of keys.variants) {
+        const variant = stored.variants[key];
+        variants[key] =
+            variant === undefined
+                ? null
+                : Object.freeze({
+                    type: variant.type,
+                    size: variant.size,
+                    url: storage.url(variant.key),
+                });
+    }
+    const inline = {};
+    for (const key of keys.inline)
+        inline[key] = stored.inline[key] ?? null;
+    const value = Object.freeze({
+        id: stored.id,
+        name: stored.name,
+        type: stored.type,
+        size: stored.size,
+        url: storage.url(stored.key),
+        inline: Object.freeze(inline),
+        variants: Object.freeze(variants),
+    });
+    copies.set(value, stored);
+    return value;
+}
+/** Whether a value is a file the plugin resolved. */
+export const isFile = (value) => typeof value === 'object' && value !== null && copies.has(value);
+/** The copy the row stores of a value code holds. */
+export function copyOf(value, where) {
+    const copy = typeof value === 'object' && value !== null ? copies.get(value) : undefined;
+    if (copy === undefined) {
+        throw new TypeError(`${where}: a file field stores the files filesPlugin resolved, written as ids.`);
+    }
+    return copy;
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isString = (value) => typeof value === 'string';
+const isSize = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0;
+function variantsOf(value) {
+    if (!isRecord(value))
+        return undefined;
+    const variants = {};
+    for (const [name, variant] of Object.entries(value)) {
+        if (!isRecord(variant))
+            return undefined;
+        const { key, type, size } = variant;
+        if (!isString(key) || !isString(type) || !isSize(size))
+            return undefined;
+        variants[name] = { key, type, size };
+    }
+    return variants;
+}
+/** A stored copy, read back from the row; any other value is a bug. */
+export function storedFile(value, where) {
+    if (isRecord(value)) {
+        const { id, key, name, type, size, inline } = value;
+        const variants = variantsOf(value['variants']);
+        if (isString(id) &&
+            isString(key) &&
+            isString(name) &&
+            isString(type) &&
+            isSize(size) &&
+            isRecord(inline) &&
+            variants !== undefined) {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the row's JSON column holds JSON.
+            const json = inline;
+            return { id, key, name, type, size, inline: json, variants };
+        }
+    }
+    throw new TypeError(`${where}: the row holds a file that is not one.`);
+}
+/** A copy as the row's JSON column stores it. */
+export const storedJson = (copy) => ({
+    id: copy.id,
+    key: copy.key,
+    name: copy.name,
+    type: copy.type,
+    size: copy.size,
+    inline: copy.inline,
+    variants: Object.fromEntries(Object.entries(copy.variants).map(([name, { key, type, size }]) => [
+        name,
+        { key, type, size },
+    ])),
+});
+/** A value as a client reads it. */
+export const fileJson = (value) => ({
+    id: value.id,
+    name: value.name,
+    type: value.type,
+    size: value.size,
+    url: value.url,
+    inline: { ...value.inline },
+    variants: Object.fromEntries(Object.entries(value.variants).map(([name, variant]) => [
+        name,
+        variant === null
+            ? null
+            : { type: variant.type, size: variant.size, url: variant.url },
+    ])),
+});

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@ultimabase/files",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Files for UltimaBase: uploads to S3-compatible storage, file fields, variants, and no orphan ever.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev/docs/files",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/files"
+  },
+  "engines": {
+    "node": ">=24.7.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "file-type": "22.2.0"
+  },
+  "peerDependencies": {
+    "@ultimabase/http": "^0.1.1",
+    "ultimabase": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/pg": "8.23.1",
+    "@ultimabase/http": "0.1.1",
+    "@ultimabase/postgres": "0.1.1",
+    "pg": "8.23.1",
+    "ultimabase": "0.1.1",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }