@ultimabase/files 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @ultimabase/files
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - ultimabase@0.1.1
+  - @ultimabase/http@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- 0e885c4: The first release: the kernel, its adapters, transports and plugins, the testing helpers and the starter.
+
+### Patch Changes
+
+- Updated dependencies [0e885c4]
+  - @ultimabase/http@0.1.0
+  - ultimabase@0.1.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/files
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Files for UltimaBase, in S3 or any S3-compatible storage. A client uploads a file, then writes its id in a row as any other value; a replaced or deleted file leaves the storage after the commit, so no object is left without a row.
+
+Documentation: [Files](https://ultimabase.dev/docs/files).

package/dist/field.d.ts

@@ -0,0 +1,89 @@
+import type { Field, JsonValue } from 'ultimabase';
+import type { StandardSchema } from './standard.ts';
+import type { FileValue, FileVariant, Keys, Operation } from './values.ts';
+/** What `inline` and `variants` are made from, at upload. */
+export interface FileInput {
+    readonly body: Uint8Array;
+    readonly type: string;
+    readonly name: string;
+}
+/** Computes one inline value: JSON of 2 KB at most. */
+export type InlineRun = (file: FileInput) => JsonValue | Promise<JsonValue>;
+/** An inline value; with its `schema`, the transports type it. */
+export type Inline = InlineRun | {
+    readonly run: InlineRun;
+    readonly schema: StandardSchema;
+};
+/** Another file made from the upload: a thumbnail. */
+export type Variant = (file: FileInput) => MadeVariant | Promise<MadeVariant>;
+export interface MadeVariant {
+    readonly body: Uint8Array;
+    readonly type: string;
+}
+/** What `file()` takes (D-152). */
+export interface FileOptions {
+    readonly description?: string;
+    /** A single file that may be `null`. */
+    readonly optional?: boolean;
+    /** A list of files, `[]` when empty. */
+    readonly list?: boolean;
+    /** In bytes, 50 MB by default. */
+    readonly maxSize?: number;
+    /** MIME types or patterns: `['image/*', 'application/pdf']`; any by default. */
+    readonly accept?: readonly string[];
+    /** Served to everyone at a stable URL; presigned for one hour otherwise. */
+    readonly public?: boolean;
+    readonly inline?: {
+        readonly [key: string]: Inline;
+    };
+    readonly variants?: {
+        readonly [key: string]: Variant;
+    };
+}
+type InlineOf<T> = T extends {
+    readonly schema: StandardSchema<unknown, infer O>;
+} ? O : T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type Inlines<O> = O extends {
+    readonly inline: infer I;
+} ? {
+    readonly [K in keyof I]: InlineOf<I[K]> | null;
+} : {
+    readonly [K in never]: never;
+};
+type Variants<O> = O extends {
+    readonly variants: infer V;
+} ? {
+    readonly [K in keyof V]: FileVariant | null;
+} : {
+    readonly [K in never]: never;
+};
+/** The value of a field with options `O`. */
+export type FileOf<O> = FileValue<Inlines<O>, Variants<O>>;
+type ValueOf<O> = O extends {
+    readonly list: true;
+} ? readonly FileOf<O>[] : FileOf<O>;
+type Ids = string | readonly string[];
+/** A list's write: the new list, or one operation, as kernel lists (D-149). */
+type ListInput = readonly string[] | {
+    readonly [K in Operation]: {
+        readonly [P in K]: Ids;
+    } & {
+        readonly [P in Exclude<Operation, K>]?: never;
+    };
+}[Operation];
+type InputOf<O> = O extends {
+    readonly list: true;
+} ? ListInput : string;
+/** A file field: read as files, written as ids. */
+export type FileField<O> = Field<ValueOf<O>, O, 'files', never, InputOf<O>, true, Field<JsonValue, O, never, never, JsonValue, true>>;
+/** 50 MB. */
+export declare const defaultMaxSize: number;
+export declare const keysOf: (options: FileOptions) => Keys;
+/**
+ * A field of files (D-152): written as ids from `POST /files` or
+ * `files.upload`, read with each file's URL.
+ */
+export declare function file(): FileField<{}>;
+export declare function file<const O extends FileOptions>(options: O): FileField<NoInfer<O>>;
+export {};
+//# sourceMappingURL=field.d.ts.map

package/dist/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAGnD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAU1E,6DAA6D;AAC7D,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB;AAED,uDAAuD;AACvD,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;AAC3E,kEAAkE;AAClE,MAAM,MAAM,MAAM,GACjB,SAAS,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAA;AAEzE,sDAAsD;AACtD,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;AAC7E,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,kCAAkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;CACvD;AAED,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;CACjD,GACE,CAAC,GACD,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,MAAM,CAAC,GACtC,OAAO,CAAC,CAAC,CAAC,GACV,KAAK,CAAA;AACT,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACrD;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;CAAE,GAClD;IAAE,QAAQ,EAAE,CAAC,IAAI,KAAK,GAAG,KAAK;CAAE,CAAA;AACnC,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;CAAE,GACxD;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,GAAG,IAAI;CAAE,GAC/C;IAAE,QAAQ,EAAE,CAAC,IAAI,KAAK,GAAG,KAAK;CAAE,CAAA;AACnC,6CAA6C;AAC7C,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;AAC1D,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAChD,SAAS,MAAM,CAAC,CAAC,CAAC,EAAE,GACpB,MAAM,CAAC,CAAC,CAAC,CAAA;AACZ,KAAK,GAAG,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;AACrC,+EAA+E;AAC/E,KAAK,SAAS,GACX,SAAS,MAAM,EAAE,GACjB;IACA,QAAQ,EAAE,CAAC,IAAI,SAAS,GAAG;QAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,GAAG;KAAE,GAAG;QACvD,QAAQ,EAAE,CAAC,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK;KAC7C;CACA,CAAC,SAAS,CAAC,CAAA;AACf,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,GAAG,MAAM,CAAA;AAExE,mDAAmD;AACnD,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,KAAK,CAC/B,OAAO,CAAC,CAAC,CAAC,EACV,CAAC,EACD,OAAO,EACP,KAAK,EACL,OAAO,CAAC,CAAC,CAAC,EACV,IAAI,EACJ,KAAK,CAAC,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,CAClD,CAAA;AAED,aAAa;AACb,eAAO,MAAM,cAAc,EAAE,MAAyB,CAAA;AAGtD,eAAO,MAAM,MAAM,YAAa,WAAW,KAAG,IAG5C,CAAA;AAqHF;;;GAGG;AACH,wBAAgB,IAAI,IAAI,SAAS,CAAC,EAAE,CAAC,CAAA;AAGrC,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,WAAW,EAC/C,OAAO,EAAE,CAAC,GACR,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/field.js

@@ -0,0 +1,123 @@
+import { defineFieldType } from 'ultimabase';
+import { shapeOf } from './shape.js';
+import { copyOf, fileJson, fileValue, Pending, storedFile, storedJson, } from './values.js';
+/** 50 MB. */
+export const defaultMaxSize = 50 * 1024 * 1024;
+const operations = ['set', 'push', 'pushUnique', 'remove'];
+export const keysOf = (options) => ({
+    inline: Object.keys(options.inline ?? {}),
+    variants: Object.keys(options.variants ?? {}),
+});
+/** Ids, each once; `undefined` when the value is not a list of them. */
+function idsOf(value, unique) {
+    const ids = Array.isArray(value) ? value : [value];
+    if (!ids.every((id) => typeof id === 'string' && id !== '')) {
+        return undefined;
+    }
+    if (unique && new Set(ids).size !== ids.length)
+        return undefined;
+    return ids;
+}
+/** The ids a write gives, as the hooks resolve them. */
+function pendingOf(value, list) {
+    if (!list) {
+        return typeof value === 'string' && value !== ''
+            ? new Pending('set', [value])
+            : 'Expected a file id.';
+    }
+    const expected = 'Expected a list of file ids, each once, or one of set, push, pushUnique, remove.';
+    if (Array.isArray(value)) {
+        const ids = idsOf(value, true);
+        return ids === undefined ? expected : new Pending('set', ids);
+    }
+    if (typeof value !== 'object' || value === null)
+        return expected;
+    const given = Object.entries(value).filter(([, ids]) => ids !== undefined);
+    const [entry] = given;
+    const operation = operations.find((name) => name === entry?.[0]);
+    if (given.length !== 1 || operation === undefined)
+        return expected;
+    const ids = idsOf(entry?.[1], operation === 'set' || operation === 'push');
+    return ids === undefined ? expected : new Pending(operation, ids);
+}
+const schemaOf = (options) => ({
+    '~standard': {
+        version: 1,
+        vendor: 'ultimabase-files',
+        validate: (value) => {
+            const pending = pendingOf(value, options.list === true);
+            return typeof pending === 'string'
+                ? { issues: [{ message: pending }] }
+                : { value: pending };
+        },
+    },
+});
+const isList = (value) => Array.isArray(value);
+const fileType = defineFieldType({
+    plugin: 'files',
+    options: [
+        'optional',
+        'list',
+        'maxSize',
+        'accept',
+        'public',
+        'inline',
+        'variants',
+    ],
+    stored: (f, options) => options.list === true
+        ? f.json({ default: [] })
+        : options.optional === true
+            ? f.json({ optional: true })
+            : f.json(),
+    decode: (stored, options) => {
+        const keys = keysOf(options);
+        const where = 'A file field';
+        return Array.isArray(stored)
+            ? stored.map((item) => fileValue(storedFile(item, where), keys))
+            : fileValue(storedFile(stored, where), keys);
+    },
+    encode: (value) => {
+        const where = 'A file field';
+        if (value instanceof Pending)
+            copyOf(value, where);
+        return isList(value)
+            ? value.map((item) => storedJson(copyOf(item, where)))
+            : storedJson(copyOf(value, where));
+    },
+    schema: (options) => schemaOf(options),
+    toJSON: (value) => {
+        if (value instanceof Pending)
+            return null;
+        return isList(value) ? value.map((item) => fileJson(item)) : fileJson(value);
+    },
+    shape: (options) => shapeOf(options),
+});
+function checked(options) {
+    const { list, optional, maxSize, accept } = options;
+    if (list === true && optional === true) {
+        throw new Error('A file list is empty, never null: list or optional.');
+    }
+    if (maxSize !== undefined && (!Number.isInteger(maxSize) || maxSize <= 0)) {
+        throw new Error('A file field’s maxSize is a number of bytes.');
+    }
+    if (accept?.some((type) => !/^[\w.+-]+\/(\*|[\w.+-]+)$/.test(type))) {
+        throw new Error('A file field’s accept lists MIME types or patterns: image/png, image/*.');
+    }
+    for (const [key, inline] of Object.entries(options.inline ?? {})) {
+        if (typeof inline !== 'function' && typeof inline?.run !== 'function') {
+            throw new Error(`A file field’s inline ${key} is a function.`);
+        }
+    }
+    for (const [key, variant] of Object.entries(options.variants ?? {})) {
+        if (typeof variant !== 'function') {
+            throw new Error(`A file field’s variant ${key} is a function.`);
+        }
+    }
+}
+export function file(options) {
+    const given = options ?? {};
+    checked(given);
+    const field = given.list === true ? fileType({ ...given, default: [] }) : fileType(given);
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the field's options give its value and its input.
+    return field;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { FileField, FileInput, FileOf, FileOptions, Inline, InlineRun, MadeVariant, Variant, } from './field.ts';
+export type { Checked } from './lifecycle.ts';
+export type { MemoryFiles, MemoryObject } from './memory.ts';
+export type { Files, FilesOptions, UploadArgs } from './plugin.ts';
+export type { S3Options } from './s3.ts';
+export type { FileBody, FileStorage, PutOptions } from './storage.ts';
+export type { FileValue, FileVariant } from './values.ts';
+export { file } from './field.ts';
+export { memoryFiles } from './memory.ts';
+export { files, filesPlugin } from './plugin.ts';
+export { s3 } from './s3.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACX,SAAS,EACT,SAAS,EACT,MAAM,EACN,WAAW,EACX,MAAM,EACN,SAAS,EACT,WAAW,EACX,OAAO,GACP,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC5D,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACrE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { file } from './field.js';
+export { memoryFiles } from './memory.js';
+export { files, filesPlugin } from './plugin.js';
+export { s3 } from './s3.js';

package/dist/lifecycle.d.ts

@@ -0,0 +1,50 @@
+import type { Caller } from 'ultimabase';
+/** What a hook gives of the write. */
+interface Facts {
+    readonly name: string;
+    readonly caller: Caller;
+    readonly record: object;
+}
+/**
+ * `beforeCreate` and `beforeUpdate`: each file field's ids become its
+ * files, computed on the row the update locked.
+ */
+export declare function resolve(facts: {
+    readonly name: string;
+    readonly caller: Caller;
+    readonly data: object;
+    readonly record?: object;
+}): Promise<void>;
+/**
+ * `afterCreate` and `afterUpdate`: the files the row gained are attached,
+ * with their variants, and the ones it lost released.
+ */
+export declare function attach(facts: Facts & {
+    readonly previous?: object;
+}): Promise<void>;
+/** `afterDelete`: every file of the row, released. */
+export declare function release({ name, record }: Facts): Promise<void>;
+/** `afterUpdateCommit`: the objects of the files the row lost, deleted. */
+export declare function deleteLost(facts: Facts & {
+    readonly previous: object;
+}): Promise<void>;
+/** `afterDeleteCommit`: the objects of a deleted row's files, deleted. */
+export declare function deleteHeld({ name, record }: Facts): Promise<void>;
+/**
+ * The sweep: expired pending blobs are released, so no write attaches them,
+ * then every released blob is deleted, what a crash left included.
+ */
+export declare function sweep(): Promise<void>;
+/** What `files.check` found. */
+export interface Checked {
+    /** Objects without a row, deleted with `delete: true`. */
+    readonly objects: readonly string[];
+    /** Rows whose object is missing: an upload under way, or a lost object. */
+    readonly rows: readonly string[];
+}
+/** Compares the storage's keys with `FilesBlob`. */
+export declare function check(options?: {
+    readonly delete?: boolean;
+}): Promise<Checked>;
+export {};
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAgBxC,sCAAsC;AACtC,UAAU,KAAK;IACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACvB;AAkGD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAKD;;;GAGG;AACH,wBAAsB,MAAM,CAC3B,KAAK,EAAE,KAAK,GAAG;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAUD,sDAAsD;AACtD,wBAAsB,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpE;AAsBD,2EAA2E;AAC3E,wBAAsB,UAAU,CAC/B,KAAK,EAAE,KAAK,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,0EAA0E;AAC1E,wBAAsB,UAAU,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;AAED;;;GAGG;AACH,wBAAsB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAI3C;AAED,gCAAgC;AAChC,MAAM,WAAW,OAAO;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAED,oDAAoD;AACpD,wBAAsB,KAAK,CAAC,OAAO,CAAC,EAAE;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CACzB,GAAG,OAAO,CAAC,OAAO,CAAC,CAcnB"}

package/dist/lifecycle.js

@@ -0,0 +1,192 @@
+import { isMaster, PublicError } from 'ultimabase';
+import { keysOf } from './field.js';
+import { FilesBlob, M } from './model.js';
+import { settled } from './storage.js';
+import { fileValue, isFile, Pending, runningOf, storedFile } from './values.js';
+const fieldsOf = (model) => runningOf().fields.get(model) ?? new Map();
+const invalid = (field, message) => new PublicError('VALIDATION_FAILED', 'Invalid data.', {
+    details: { issues: [{ path: [field], message }] },
+});
+/** The files a field's value holds. */
+function heldOf(value) {
+    const items = Array.isArray(value) ? value : [value];
+    return items.filter(isFile);
+}
+const idsOf = (record, field) => heldOf(Reflect.get(record, field)).map(({ id }) => id);
+const idOf = (record) => String(Reflect.get(record, 'id'));
+/** Whether `caller` may attach a pending blob: its uploader, or Master. */
+function usable(blob, target, caller) {
+    const { state, field, variantOf, deleteAfter, uploadedBy } = blob;
+    return (state === 'pending' &&
+        field === target &&
+        variantOf === null &&
+        deleteAfter !== null &&
+        deleteAfter.getTime() > Date.now() &&
+        (isMaster(caller) ||
+            uploadedBy === null ||
+            (caller.kind === 'user' && uploadedBy === caller.user.id)));
+}
+/** The pending files of `ids`, each one the caller may attach to `target`. */
+async function pendingFiles(target, options, ids, caller) {
+    if (ids.length === 0)
+        return new Map();
+    const field = target.slice(target.indexOf('.') + 1);
+    const where = { id: { in: ids } };
+    const blobs = await FilesBlob.findMany({ where }, M);
+    const missing = ids.find((id) => !blobs.some((blob) => blob.id === id && usable(blob, target, caller)));
+    if (missing !== undefined) {
+        throw invalid(field, `${missing} is not a file uploaded for ${target}.`);
+    }
+    const made = await FilesBlob.findMany({ where: { variantOf: where.id } }, M);
+    const keys = keysOf(options);
+    return new Map(blobs.map((blob) => {
+        const variants = {};
+        for (const { variantOf, name, key, type, size } of made) {
+            if (variantOf === blob.id)
+                variants[name] = { key, type, size };
+        }
+        const { id, key, name, type, size, inline } = blob;
+        const copy = { id, key, name, type, size, inline: inline ?? {}, variants };
+        return [id, fileValue(storedFile(copy, 'FilesBlob'), keys)];
+    }));
+}
+/** A field's files after a write's operation on the ones it holds. */
+async function filesOf(target, options, pending, held, caller) {
+    const { operation, ids } = pending;
+    const holds = new Map(held.map((file) => [file.id, file]));
+    if (operation === 'remove')
+        return held.filter(({ id }) => !ids.includes(id));
+    const field = target.slice(target.indexOf('.') + 1);
+    const taken = ids.find((id) => holds.has(id));
+    if (operation === 'push' && taken !== undefined) {
+        throw invalid(field, `The list holds ${taken} already.`);
+    }
+    const given = operation === 'pushUnique'
+        ? [...new Set(ids)].filter((id) => !holds.has(id))
+        : ids;
+    const fresh = given.filter((id) => !holds.has(id));
+    const found = await pendingFiles(target, options, fresh, caller);
+    const listed = given.flatMap((id) => {
+        const file = holds.get(id) ?? found.get(id);
+        return file === undefined ? [] : [file];
+    });
+    return operation === 'set' ? listed : [...held, ...listed];
+}
+/**
+ * `beforeCreate` and `beforeUpdate`: each file field's ids become its
+ * files, computed on the row the update locked.
+ */
+export async function resolve(facts) {
+    const { name, caller, data, record } = facts;
+    for (const [field, options] of fieldsOf(name)) {
+        const value = Reflect.get(data, field);
+        if (!(value instanceof Pending))
+            continue;
+        const held = record === undefined ? [] : heldOf(Reflect.get(record, field));
+        const target = `${name}.${field}`;
+        const files = await filesOf(target, options, value, held, caller);
+        Reflect.set(data, field, options.list === true ? files : files[0]);
+    }
+}
+const attached = (name, field, record) => `${name}.${field}:${idOf(record)}`;
+/**
+ * `afterCreate` and `afterUpdate`: the files the row gained are attached,
+ * with their variants, and the ones it lost released.
+ */
+export async function attach(facts) {
+    const { name, record, previous } = facts;
+    for (const field of fieldsOf(name).keys()) {
+        const now = idsOf(record, field);
+        const before = previous === undefined ? [] : idsOf(previous, field);
+        const gained = now.filter((id) => !before.includes(id));
+        const lost = before.filter((id) => !now.includes(id));
+        const attachedTo = attached(name, field, record);
+        const data = { state: 'attached', attachedTo, deleteAfter: null };
+        if (gained.length > 0) {
+            const ids = { in: gained };
+            const where = {
+                id: ids,
+                state: 'pending',
+                deleteAfter: { gt: new Date() },
+            };
+            const { count } = await FilesBlob.updateMany({ where, data }, M);
+            // The sweep released it, or another row attached it, since.
+            if (count !== gained.length) {
+                throw invalid(field, 'A file expired or was attached elsewhere.');
+            }
+            await FilesBlob.updateMany({ where: { variantOf: ids }, data }, M);
+        }
+        if (lost.length > 0) {
+            const where = { OR: [{ id: { in: lost } }, { variantOf: { in: lost } }] };
+            await FilesBlob.updateMany({ where, data: { state: 'released' } }, M);
+        }
+    }
+}
+const heldBy = (name, record) => ({
+    attachedTo: {
+        in: [...fieldsOf(name).keys()].map((field) => attached(name, field, record)),
+    },
+});
+/** `afterDelete`: every file of the row, released. */
+export async function release({ name, record }) {
+    const where = heldBy(name, record);
+    await FilesBlob.updateMany({ where, data: { state: 'released' } }, M);
+}
+/**
+ * Deletes the released blobs `where` names: their objects, then their rows.
+ * A failure keeps the rows, which the sweep deletes later.
+ */
+async function purge(where) {
+    const { storage, logger } = runningOf();
+    try {
+        const blobs = await FilesBlob.findMany({ where: { AND: [where, { state: 'released' }] } }, M);
+        if (blobs.length === 0)
+            return;
+        await settled(blobs.map(({ key }) => storage.delete(key)));
+        const ids = blobs.map(({ id }) => id);
+        await FilesBlob.deleteMany({ where: { id: { in: ids } } }, M);
+    }
+    catch (error) {
+        logger.warn({ err: error }, 'Released files were not deleted yet.');
+    }
+}
+/** `afterUpdateCommit`: the objects of the files the row lost, deleted. */
+export async function deleteLost(facts) {
+    const { name, record, previous } = facts;
+    const lost = [...fieldsOf(name).keys()].flatMap((field) => {
+        const now = idsOf(record, field);
+        return idsOf(previous, field).filter((id) => !now.includes(id));
+    });
+    if (lost.length === 0)
+        return;
+    await purge({ OR: [{ id: { in: lost } }, { variantOf: { in: lost } }] });
+}
+/** `afterDeleteCommit`: the objects of a deleted row's files, deleted. */
+export async function deleteHeld({ name, record }) {
+    await purge(heldBy(name, record));
+}
+/**
+ * The sweep: expired pending blobs are released, so no write attaches them,
+ * then every released blob is deleted, what a crash left included.
+ */
+export async function sweep() {
+    const where = { state: 'pending', deleteAfter: { lt: new Date() } };
+    await FilesBlob.updateMany({ where, data: { state: 'released' } }, M);
+    await purge({});
+}
+/** Compares the storage's keys with `FilesBlob`. */
+export async function check(options) {
+    const { storage } = runningOf();
+    // The keys first: an upload inserts its row before its object, so an
+    // object listed without a row is never one under way.
+    const keys = await storage.keys();
+    const blobs = await FilesBlob.findMany({ select: { key: true } }, M);
+    const held = new Set(blobs.map(({ key }) => key));
+    const stored = new Set(keys);
+    const objects = keys.filter((key) => !held.has(key));
+    const rows = blobs.map(({ key }) => key).filter((key) => !stored.has(key));
+    if (options?.delete === true) {
+        await settled(objects.map((key) => storage.delete(key)));
+    }
+    return { objects, rows };
+}

package/dist/memory.d.ts

@@ -0,0 +1,16 @@
+import type { FileBody, FileStorage } from './storage.ts';
+/** An object `memoryFiles()` holds. */
+export interface MemoryObject {
+    readonly body: Uint8Array;
+    readonly type: string;
+    readonly attachment: boolean;
+}
+/** A storage in memory, its objects readable by tests. */
+export interface MemoryFiles extends FileStorage {
+    readonly objects: ReadonlyMap<string, MemoryObject>;
+}
+/** The bytes of a body, read to its end. */
+export declare function bytesOf(body: FileBody): Promise<Uint8Array>;
+/** A storage in memory: its URLs are `memory://files/<key>`, never served. */
+export declare function memoryFiles(): MemoryFiles;
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAGzD,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC5B;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CACnD;AAED,4CAA4C;AAC5C,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAGjE;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,IAAI,WAAW,CAqBzC"}

package/dist/memory.js

@@ -0,0 +1,27 @@
+import { isPublic } from './storage.js';
+/** The bytes of a body, read to its end. */
+export async function bytesOf(body) {
+    if (body instanceof Uint8Array)
+        return body;
+    return new Uint8Array(await new Response(body).arrayBuffer());
+}
+/** A storage in memory: its URLs are `memory://files/<key>`, never served. */
+export function memoryFiles() {
+    const objects = new Map();
+    return {
+        objects,
+        start: () => { },
+        put: async (key, body, { type, size, attachment }) => {
+            const bytes = await bytesOf(body);
+            if (bytes.length !== size) {
+                throw new Error(`memoryFiles: ${key} has ${bytes.length} bytes, not ${size}.`);
+            }
+            objects.set(key, { body: bytes, type, attachment });
+        },
+        delete: async (key) => {
+            objects.delete(key);
+        },
+        keys: async () => [...objects.keys()],
+        url: (key) => `memory://files/${key}${isPublic(key) ? '' : '?expires=3600'}`,
+    };
+}

package/dist/model.d.ts

@@ -0,0 +1,41 @@
+import type { Field, ModelOf, ScalarOptions } from 'ultimabase';
+import { master } from 'ultimabase';
+export declare const M: {
+    readonly as: typeof master;
+};
+/** One hour, a pending blob's life. */
+export declare const hour: number;
+/** A blob's state: uploaded, held by a row, or to delete. */
+export type BlobState = 'pending' | 'attached' | 'released';
+type Optional<V> = Field<V | null, {
+    readonly optional: true;
+}>;
+type BlobFields = {
+    /** `public/…` or `private/…`, the object's key in the storage. */
+    readonly key: Field<string, {
+        readonly unique: true;
+    }>;
+    /** The file's name; a variant's own, `thumb`. */
+    readonly name: Field<string, ScalarOptions<string>>;
+    readonly type: Field<string, ScalarOptions<string>>;
+    readonly size: Field<number, {
+        readonly integer: true;
+    }>;
+    /** `Post.cover`. */
+    readonly field: Field<string, ScalarOptions<string>>;
+    /** The uploading user's id, `master`, or `null` for an anonymous caller. */
+    readonly uploadedBy: Optional<string>;
+    readonly state: Field<string, ScalarOptions<string>>;
+    /** `Post.cover:<id>`, once attached. */
+    readonly attachedTo: Optional<string>;
+    /** A variant's file. */
+    readonly variantOf: Optional<string>;
+    readonly inline: Field<unknown, {
+        readonly optional: true;
+    }, never, never, unknown, true>;
+    /** When a pending blob expires. */
+    readonly deleteAfter: Optional<Date>;
+};
+export declare const FilesBlob: ModelOf<'FilesBlob', BlobFields, []>;
+export {};
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/D,OAAO,EAAe,MAAM,EAAE,MAAM,YAAY,CAAA;AAGhD,eAAO,MAAM,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,MAAM,CAAA;CAAmB,CAAA;AAE/D,uCAAuC;AACvC,eAAO,MAAM,IAAI,EAAE,MAAuB,CAAA;AAE1C,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;AAE3D,KAAK,QAAQ,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAE/D,KAAK,UAAU,GAAG;IACjB,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;IACtD,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACnD,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACnD,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;IACxD,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACpD,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACpD,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACrC,wBAAwB;IACxB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,CACrB,OAAO,EACP;QAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,EAC3B,KAAK,EACL,KAAK,EACL,OAAO,EACP,IAAI,CACJ,CAAA;IACD,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAA;CACpC,CAAA;AAED,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE,CAsBoB,CAAA"}

package/dist/model.js

@@ -0,0 +1,28 @@
+import { defineModel, master } from 'ultimabase';
+import { runningOf } from './values.js';
+export const M = { as: master };
+/** One hour, a pending blob's life. */
+export const hour = 60 * 60 * 1000;
+export const FilesBlob = defineModel({
+    name: 'FilesBlob',
+    fields: (f) => ({
+        key: f.string({ unique: true }),
+        name: f.string(),
+        type: f.string(),
+        size: f.number({ integer: true }),
+        field: f.string(),
+        uploadedBy: f.string({ optional: true }),
+        state: f.string(),
+        attachedTo: f.string({ optional: true }),
+        variantOf: f.string({ optional: true }),
+        inline: f.json({ optional: true }),
+        deleteAfter: f.dateTime({ optional: true }),
+    }),
+    indexes: [
+        { fields: ['state', 'deleteAfter'] },
+        { fields: ['variantOf'] },
+        { fields: ['attachedTo'] },
+    ],
+    // An upload creates its row as its caller: the kernel gives the rule the
+    // whole caller, and Master always passes. The rest stays Master's.
+}).with({ access: { create: ({ caller }) => runningOf().upload({ caller }) } });