@drhomet/mithaq 0.0.0-stage → 0.1.1

package/dist/storage/storage.js

@@ -0,0 +1,405 @@
+// The object key is decided before the upload and the row that names it is made
+// in one insert after the upload is verified, so no stored file goes unnamed by a failed second write.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { isStorage } from '../mithaq/language.js';
+import { providerOf } from '../base/rules.js';
+import { AsasError, codes, denied, invalid, missing } from '../asas/runner/errors.js';
+import { sealOf } from '../asas/runner/steps.js';
+import { allowedType } from './allowed-type.js';
+/** Written by the runner when the row is made, from the signed upload, and by nobody after. */
+const fileColumn = { create: 'application', update: 'never' };
+/**
+ * The file columns a kayan that holds files spreads into its fields beside `defaultFields`.
+ * Filled from the verified upload and never changed: a file is replaced by a new row.
+ */
+export const uploadFields = {
+    filename: { kind: 'text', label: { en: 'File name', ar: 'اسم الملف' }, rules: { providedBy: fileColumn, required: true, index: true } },
+    mimeType: { kind: 'text', label: { en: 'File type', ar: 'نوع الملف' }, rules: { providedBy: fileColumn, required: true } },
+    filesize: { kind: 'number', label: { en: 'File size', ar: 'حجم الملف' }, rules: { providedBy: fileColumn, required: true } },
+    width: { kind: 'number', label: { en: 'Width', ar: 'العرض' }, rules: { providedBy: fileColumn } },
+    height: { kind: 'number', label: { en: 'Height', ar: 'الارتفاع' }, rules: { providedBy: fileColumn } },
+    key: { kind: 'text', label: { en: 'Object key', ar: 'مفتاح الملف' }, rules: { providedBy: fileColumn, required: true, unique: true } },
+    storage: { kind: 'text', label: { en: 'Storage', ar: 'التخزين' }, rules: { providedBy: fileColumn, required: true } },
+};
+const storageFunctions = {
+    key: 'defaultKey',
+    verify: 'defaultVerify',
+    disposition: 'defaultDisposition',
+    sweep: 'defaultSweep',
+    instructions: 'defaultUploadInstructions',
+    uploaded: 'defaultUploaded',
+    removed: 'defaultRemoveFile',
+    serve: 'defaultServeFile',
+};
+/** The `fileSize` the template names in its storage config: 10 MiB. */
+export const defaultFileSize = 10 * 1024 * 1024;
+const referenceSeconds = 60 * 60;
+const svg = 'image/svg+xml';
+/** The type check both halves make, in a module the browser imports too. */
+export { allowedType };
+/** The file name with every directory part and control character dropped, or an empty string. */
+export const sanitizeFilename = (filename) => {
+    let sanitized = filename.replace(/\\/g, '/');
+    sanitized = sanitized.slice(sanitized.lastIndexOf('/') + 1);
+    if (sanitized === '.' || sanitized === '..')
+        return '';
+    // eslint-disable-next-line no-control-regex
+    return sanitized.replace(/[\x00-\x1f\x80-\x9f]/g, '');
+};
+const fields = ['id', 'key', 'kayan', 'tenant', 'filename', 'type', 'size', 'storage', 'exp'];
+const signatureOf = (secret, reference) => createHmac('sha256', secret).update(JSON.stringify(fields.map((name) => reference[name]))).digest('base64url');
+const storageOf = (kayan) => {
+    const { storage } = kayan;
+    if (!storage)
+        throw new Error(`Kayan "${kayan.name}" runs a storage step and writes no targets.storage.`);
+    return storage;
+};
+/** The adapter a row or a reference names. Read as an own key, so no name reaches an inherited property. */
+export const adapterOf = ({ kayan, name }) => {
+    const { config } = storageOf(kayan);
+    const adapter = typeof name === 'string' && Object.hasOwn(config.adapters, name) ? config.adapters[name] : undefined;
+    if (!adapter)
+        throw new Error(`A stored file names adapter "${String(name)}", which is not one of storage.adapters.`);
+    return adapter;
+};
+/**
+ * Signs the reference an upload's create must name back: the row's id, the key, the kayan,
+ * the actor's tenant from its session, the file, the adapter and an expiry, under HMAC-SHA256.
+ */
+export const signReference = ({ kayan, actor, id, filename, type, size, }) => {
+    const { config, tenant: tenantOf } = storageOf(kayan);
+    const tenant = tenantOf(actor);
+    if (tenant === undefined) {
+        throw denied({ message: `Forbidden: "${kayan.name}" files belong to an organization, and this actor's session has no active organization it is a verified member of.`, key: 'error.forbidden.create', params: { kayan: kayan.name, operation: 'create' } });
+    }
+    const adapter = adapterOf({ kayan, name: config.adapter });
+    const key = config.key({ prefix: adapter.prefix, tenant, kayan: kayan.name, id, filename });
+    // The project's key function is wrong, which is a fault and not the caller's, so it is asked first.
+    if (adapter.prefix && !key.startsWith(`${adapter.prefix}/`)) {
+        throw new Error(`storage.key answered "${key}", which is not under adapter "${config.adapter}"'s prefix "${adapter.prefix}/".`);
+    }
+    // The row id is what keeps one object to one row: without it two uploads could share a key,
+    // and the unique key would answer whether a name is taken.
+    if (!key.split('/').includes(id))
+        throw new Error(`storage.key answered "${key}", which does not hold the row id "${id}" as a whole path segment.`);
+    // A key with an empty, `.` or `..` part, a backslash or a NUL climbs out of its prefix.
+    if (!key || /[\\\0]/.test(key) || key.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+        throw invalid({ message: 'The upload names a file whose key would have an empty, "." or ".." part.', key: 'error.invalid.upload_request', params: { kayan: kayan.name } });
+    }
+    const unsigned = { id, key, kayan: kayan.name, tenant, filename, type, size, storage: config.adapter, exp: Math.floor(Date.now() / 1000) + referenceSeconds };
+    return { ...unsigned, signature: signatureOf(config.secret, unsigned) };
+};
+/**
+ * Checks the reference a create names back, refusing every way it can be wrong in one
+ * sentence so a forged one reads as an expired one. The signature is compared in constant time.
+ */
+export const checkReference = async ({ kayan, value, actor }) => {
+    const storage = storageOf(kayan);
+    const refused = invalid({ message: 'The upload reference is not one this server signed for this file, this tenant and this hour.', key: 'error.invalid.upload_reference', params: { kayan: kayan.name } });
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw refused;
+    const held = value;
+    const strings = ['id', 'key', 'kayan', 'filename', 'type', 'storage', 'signature'];
+    if (strings.some((name) => typeof held[name] !== 'string'))
+        throw refused;
+    if (!Number.isSafeInteger(held.size) || !Number.isSafeInteger(held.exp) || (held.tenant !== null && typeof held.tenant !== 'string'))
+        throw refused;
+    const reference = Object.fromEntries([...fields, 'signature'].map((name) => [name, held[name]]));
+    const given = Buffer.from(reference.signature);
+    const expected = Buffer.from(signatureOf(storage.config.secret, reference));
+    if (given.length !== expected.length || !timingSafeEqual(given, expected))
+        throw refused;
+    if (reference.exp * 1000 < Date.now())
+        throw refused;
+    const tenant = storage.tenant(actor);
+    if (reference.kayan !== kayan.name || tenant === undefined || reference.tenant !== tenant)
+        throw refused;
+    if (!Object.hasOwn(storage.config.adapters, reference.storage))
+        throw refused;
+    // Refused before anything reads or deletes the object, which is the earlier row's.
+    if (await storage.exists(reference.id))
+        throw invalid({ message: 'The upload reference was already used.', key: 'error.invalid.upload_reference', params: { kayan: kayan.name } });
+    return reference;
+};
+/** The create shape of a kayan holding files, with the `uploadReference` beside it. */
+export const withUploadReference = (create) => ({
+    '~standard': {
+        version: 1,
+        vendor: 'mithaq',
+        validate: async (value) => {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                return { issues: [{ message: 'Invalid input: expected object' }] };
+            const { uploadReference, ...rest } = value;
+            const result = await create['~standard'].validate(rest);
+            return result.issues ? result : { value: { ...result.value, ...(uploadReference !== undefined && { uploadReference }) } };
+        },
+    },
+});
+const readsOpen = (kayan) => {
+    try {
+        return kayan.access?.read?.({ user: null, slug: kayan.name }) === true;
+    }
+    catch {
+        return false;
+    }
+};
+// The store is asked through `storeOf` because the build has it only once its stores are initialised.
+export const resolveStorage = ({ language, resolved, storeOf, active }) => {
+    const existsIn = (kayan) => async (id) => {
+        const store = storeOf(kayan);
+        const { docs } = await store.find({ kayan: kayan.name, args: { limit: 1, page: 1, sort: { field: 'id', direction: 'asc' }, where: { id: { equals: id } } } });
+        return docs.length > 0;
+    };
+    // One storage target per build: two would split the kayan between two secrets and two sweeps.
+    const storageTargets = Object.keys(language.targets).filter((key) => isStorage(language.targets[key]));
+    if (storageTargets.length > 1) {
+        throw new Error(`Targets "${storageTargets.join('" and "')}" both declare capability "storage", and a build has at most one storage target. Drop one of them.`);
+    }
+    const name = storageTargets[0];
+    const holding = name ? resolved.filter((kayan) => kayan.targets?.[name] !== undefined) : [];
+    for (const kayan of resolved) {
+        for (const field of Object.values(kayan.fields)) {
+            if (field.kind === 'upload' && !holding.includes(field.target)) {
+                throw new Error(`Kayan "${kayan.name}" field "${field.name}" is an upload, and kayan "${field.target?.name}" it points at writes no targets.${name ?? 'storage'}, so it holds no files.`);
+            }
+        }
+    }
+    if (!name)
+        return [];
+    const { config } = language.targets[name];
+    const given = (config ?? {});
+    if (typeof given.secret !== 'string' || given.secret.length < 32)
+        throw new Error('storage.secret signs every upload reference and is a string of 32 characters at least.');
+    for (const [one, shipped] of Object.entries(storageFunctions)) {
+        if (typeof given[one] !== 'function')
+            throw new Error(`storage names no "${one}" function. Name the project's own, such as ${shipped} from src/storage/defaults.ts.`);
+    }
+    if (given.fileSize === undefined) {
+        throw new Error('storage names no "fileSize", the largest file in bytes a kayan holds when it names none. Name the project\'s own, such as defaultFileSize from mithaq.');
+    }
+    if (!Number.isSafeInteger(given.fileSize) || given.fileSize < 1) {
+        throw new Error(`storage.fileSize is ${JSON.stringify(given.fileSize)}, and it is a whole number of bytes above 0.`);
+    }
+    if (typeof given.onError !== 'function')
+        throw new Error('storage names no "onError" function, which a file route hands what it threw before it answers 500. Name the project\'s own, such as console.error.');
+    const adapters = Object.entries(given.adapters ?? {});
+    if (!adapters.length)
+        throw new Error('storage names no adapters, so no file has anywhere to go.');
+    for (const [adapter, held] of adapters) {
+        const missing = ['handleDelete', 'staticHandler', 'head', 'readHead'].find((one) => typeof held?.[one] !== 'function')
+            ?? (typeof held?.uploadInstructions?.generate === 'function' ? undefined : 'uploadInstructions.generate')
+            ?? (typeof held?.prefix === 'string' && (held.prefix || !held.list) ? undefined : 'prefix');
+        if (missing)
+            throw new Error(`storage adapter "${adapter}" has no "${missing}".`);
+        // A slash at either end would put keys outside what the sweep lists.
+        if (held.prefix.startsWith('/') || held.prefix.endsWith('/')) {
+            throw new Error(`storage adapter "${adapter}" names prefix "${held.prefix}", and a prefix is a folder of the store with no slash at either end.`);
+        }
+    }
+    if (typeof given.adapter !== 'string' || !Object.hasOwn(given.adapters, given.adapter)) {
+        throw new Error(`storage.adapter names "${String(given.adapter)}", and new uploads go to one of storage.adapters, which are ${adapters.map(([one]) => `"${one}"`).join(', ')}.`);
+    }
+    for (const kayan of holding) {
+        const where = `Kayan "${kayan.name}" writes "targets.${name}"`;
+        const kept = kayan.targets[name];
+        if (kayan.single)
+            throw new Error(`${where}, and a global holds no files: files are a kayan's rows.`);
+        if (kayan.versions)
+            throw new Error(`${where} and keeps versions, and a file never changes after it is made, so there is nothing to version. Version the kayan that points at it instead.`);
+        if (!Array.isArray(kept.mimeTypes) || !kept.mimeTypes.length || kept.mimeTypes.some((one) => typeof one !== 'string' || !/^[\w.+-]+\/(?:[\w.+-]+|\*)$/.test(one))) {
+            throw new Error(`${where} with mimeTypes ${JSON.stringify(kept.mimeTypes)}, and mimeTypes is a list of the types it holds, such as ["image/png"] or ["image/*"].`);
+        }
+        const fileSize = kept.fileSize ?? config.fileSize;
+        if (!Number.isSafeInteger(fileSize) || fileSize < 1)
+            throw new Error(`${where} with fileSize ${String(kept.fileSize)}, and fileSize is a whole number of bytes above 0.`);
+        if (kept.public !== undefined && kept.public !== true)
+            throw new Error(`${where} with public ${String(kept.public)}, and public is true or left out.`);
+        for (const [column, shipped] of Object.entries(uploadFields)) {
+            const field = kayan.fields[column];
+            if (!field || field.kind !== shipped.kind || providerOf(field, 'create') === 'client' || providerOf(field, 'update') !== 'never') {
+                throw new Error(`${where}, and its field "${column}" is not the shipped one, which the runner writes on create and nobody writes after. Spread uploadFields into its fields.`);
+            }
+        }
+        const makers = Object.entries(kayan.operations).filter(([, one]) => one.steps.some((step) => sealOf(step) === 'insert'));
+        if (!makers.length) {
+            throw new Error(`${where}, and no operation of it holds the "insert" step, so no file can be made. Declare one that runs storage.uploaded in beforeTransaction.`);
+        }
+        if (makers.length > 1) {
+            throw new Error(`${where}, and operations ${makers.map(([one]) => `"${one}"`).join(' and ')} ${makers.length > 2 ? 'all' : 'both'} hold the "insert" step. A kayan that holds files makes its rows in one, the operation the upload instructions route asks the permission of.`);
+        }
+        const [operation, made] = makers[0];
+        if (!made.beforeTransaction.includes(config.uploaded)) {
+            throw new Error(`${where}, and its operation "${operation}" does not verify the upload before the row is made: its beforeTransaction does not run storage.uploaded, the step the storage rukn was handed.`);
+        }
+        // A marked row still names its object and a restore brings it back, so removing
+        // the object there loses a file a row names.
+        if (kayan.softDelete) {
+            for (const [one, declared] of Object.entries(kayan.operations)) {
+                const slot = ['beforeTransaction', 'steps', 'afterSteps', 'afterCommit'].find((list) => declared[list].includes(config.removed));
+                if (slot)
+                    throw new Error(`${where} and marks its rows deleted, and its operation "${one}" runs storage.removed in "${slot}", which would remove the object of a row that is only marked. Leave storage.removed out of its lists.`);
+            }
+        }
+        if (!kayan.indexes.some((index) => index.unique && index.fields.length === 1 && index.fields[0] === 'key')) {
+            throw new Error(`${where}, and builds no unique index over "key" alone, while a key is the address of one object in a store every kayan and organization shares. Keep the default unique index over "key" in indexes.`);
+        }
+        if (kept.public && kayan.tenant) {
+            throw new Error(`${where} with public: true, and its rows belong to an organization, so a public address would hand one organization's file to anyone who has it. Drop public.`);
+        }
+        if (kept.public && !readsOpen(kayan)) {
+            throw new Error(`${where} with public: true, and its read is not open to everyone, so a public address would hand out what its access keeps back. Drop public, or open its read.`);
+        }
+        if (kept.public && typeof config.adapters[config.adapter].generateURL !== 'function') {
+            throw new Error(`${where} with public: true, and storage adapter "${config.adapter}" has no generateURL, so it has no public address.`);
+        }
+        // A shared kayan's files belong to no organization, whichever session uploads them.
+        const tenant = kayan.tenant ? active : () => null;
+        kayan.storage = { mimeTypes: kept.mimeTypes, fileSize, public: !!kept.public, config, operation, exists: existsIn(kayan), tenant };
+    }
+    return holding;
+};
+const filePath = (kayan, id) => `/api/${kayan}/file/${encodeURIComponent(String(id))}`;
+const raster = /^image\/(png|jpeg|gif|webp|avif)$/;
+/** A row's `url` and `thumbnailURL`, computed on read: the file route, or the adapter's public address. */
+export const fileURLs = ({ kayan, stored, visible, }) => {
+    const storage = kayan.storage;
+    if (!storage || !('id' in visible) || typeof stored.key !== 'string')
+        return visible;
+    const publicURL = storage.public ? adapterOf({ kayan, name: stored.storage }).generateURL?.({ key: stored.key }) : undefined;
+    const url = publicURL ?? filePath(kayan.name, stored.id);
+    return { ...visible, url, thumbnailURL: typeof stored.mimeType === 'string' && raster.test(stored.mimeType) ? url : null };
+};
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const refusal = (thrown) => Response.json({ code: codes[thrown.status], data: { key: thrown.key, params: thrown.params }, message: thrown.message }, { status: thrown.status });
+/**
+ * The row a file route serves, read through the kayan's own `findByID` as the actor. Every
+ * reason it cannot be served is the same 404, so no answer tells one from another.
+ */
+export const readForFile = async ({ kayan, id, read }) => {
+    let row = null;
+    try {
+        const named = decodeURIComponent(id);
+        if (kayan.fields.id?.kind !== 'uuid' || uuid.test(named))
+            row = await read({ id: named });
+    }
+    catch (thrown) {
+        if (!(thrown instanceof AsasError) && !(thrown instanceof URIError))
+            throw thrown;
+    }
+    if (!row || [row.key, row.storage, row.mimeType, row.filename].some((one) => typeof one !== 'string')) {
+        throw missing({ message: `No "${kayan.name}" file here.`, key: 'error.not_found.file', params: { kayan: kayan.name } });
+    }
+    return row;
+};
+/**
+ * Serves a file under the headers its bytes need. An SVG is never `inline` and
+ * gets a policy that runs no script.
+ */
+export const fileHeaders = async ({ doc, disposition, answer, }) => {
+    const safe = doc.mimeType === svg ? disposition.replace(/^\s*inline/i, 'attachment') : disposition;
+    const answered = await answer({ disposition: safe });
+    const headers = new Headers(answered.headers);
+    if (answered.status !== 302) {
+        headers.set('Content-Disposition', safe);
+        headers.set('Content-Type', doc.mimeType);
+        if (doc.mimeType === svg)
+            headers.set('Content-Security-Policy', "script-src 'none'");
+    }
+    return new Response(answered.body, { status: answered.status, headers });
+};
+// Asked by the build's handler before any plug.
+export const storageRoutes = ({ kayan, config, read, authorize, admin, }) => {
+    const byName = new Map(kayan.map((one) => [one.name, one]));
+    return async (request, who) => {
+        for (const adapter of Object.values(config.adapters)) {
+            const answered = await adapter.handler?.(request);
+            if (answered)
+                return answered;
+        }
+        const [api, name, verb, id, ...rest] = new URL(request.url).pathname.split('/').slice(1);
+        const one = api === 'api' && name ? byName.get(name) : undefined;
+        if (!one)
+            return null;
+        try {
+            if (verb === 'uploadInstructions' && id === undefined && request.method === 'POST') {
+                let input;
+                try {
+                    input = await request.json();
+                }
+                catch {
+                    input = undefined;
+                }
+                const actor = await who();
+                // Asked by core, so no project's instructions sign an upload for someone who may not make the row.
+                await authorize({ admin, actor, data: {}, effect: 'create', kayan: one, kind: 'insert', operation: one.storage.operation });
+                return Response.json(await config.instructions({ kayan: one, input, actor }));
+            }
+            if (verb !== 'file' || !id || rest.length || request.method !== 'GET')
+                return null;
+            const served = await config.serve({ request, kayan: one, id, read: async ({ id }) => read({ kayan: one.name, id, actor: await who() }) });
+            // Set here rather than by `serve`, so no project can leave them off: no sniffing,
+            // and no cache keeps a private file or the address a redirect hands out for it.
+            const headers = new Headers(served.headers);
+            headers.set('X-Content-Type-Options', 'nosniff');
+            if (!one.storage.public)
+                headers.set('Cache-Control', 'private, no-store');
+            return new Response(served.body, { status: served.status, statusText: served.statusText, headers });
+        }
+        catch (thrown) {
+            if (thrown instanceof AsasError)
+                return refusal(thrown);
+            config.onError(thrown);
+            return Response.json({ code: 'INTERNAL_SERVER_ERROR', message: 'Internal server error' }, { status: 500 });
+        }
+    };
+};
+const built = new WeakMap();
+export const recordStorage = (asas, swept) => void built.set(asas, swept);
+// A row marked deleted still names its key, so its object stays.
+const sweep = async ({ asas, flags }) => {
+    const swept = built.get(asas);
+    if (!swept) {
+        console.log('This build names no storage, so there is nothing to sweep.');
+        return 0;
+    }
+    const check = flags.includes('--check');
+    // A pool of its own wherever the store was made from a string: `mithaq generate
+    // --check` runs every command after a generator has destroyed the build.
+    const pools = [];
+    try {
+        const named = new Map();
+        for (const one of swept.kayan) {
+            const store = swept.storeOf(one);
+            const string = store.connectionString;
+            const own = store.sql === 'drizzle' && typeof string === 'string' && string ? drizzle(string) : undefined;
+            if (own)
+                pools.push(own);
+            const { docs } = await store.find({ kayan: one.name, args: { limit: 0, page: 1, sort: { field: 'id', direction: 'asc' } }, tx: own });
+            for (const row of docs) {
+                const set = named.get(String(row.storage)) ?? new Set();
+                set.add(String(row.key));
+                named.set(String(row.storage), set);
+            }
+        }
+        for (const [name, adapter] of Object.entries(swept.config.adapters)) {
+            if (!adapter.list) {
+                console.log(`Adapter "${name}" lists no objects, so it is not swept.`);
+                continue;
+            }
+            const orphans = await swept.config.sweep({ adapter, named: named.get(name) ?? new Set(), check, now: new Date() });
+            for (const key of orphans)
+                console.log(`${check ? 'Orphan' : 'Removed'} in "${name}": ${key}`);
+            if (!orphans.length)
+                console.log(`Adapter "${name}" holds no orphan old enough to sweep.`);
+        }
+        return 0;
+    }
+    finally {
+        for (const pool of pools)
+            await pool.$client.end().catch(() => { });
+        await asas.destroy().catch(() => { });
+    }
+};
+/** The storage target over the project's config. The storage rukn builds it. */
+export const storageTarget = (config) => ({ capability: 'storage', type: 'storage', config, commands: { sweep } });

package/dist/versions/index.d.ts

@@ -0,0 +1,37 @@
+/** `max` is how many versions of one row are kept, the oldest deleted past it; `0` keeps every one. */
+export type VersionsTarget = {
+    readonly capability: 'versions';
+    readonly type: 'versions';
+    readonly max: number;
+};
+/** What a kayan writes under the versions target: whether it keeps drafts, autosave, and its own window. */
+export type KayanVersions = {
+    readonly drafts?: true | {
+        readonly autosave?: true | {
+            readonly interval: number;
+        };
+    };
+    readonly max?: number;
+};
+/** The versions target, keeping `max` versions of a row where a kayan names no window of its own. */
+export declare const versionsTarget: ({ max }: {
+    max: number;
+}) => VersionsTarget;
+declare module '../mithaq/rukn.ts' {
+    interface KayanConfigs<L, F, T> {
+        versions: KayanVersions;
+    }
+}
+/**
+ * The rukn a project lays down for versions and drafts: `arkan: [base, versions({ max: 100 })]`.
+ * Each kayan that keeps versions writes `targets.versions` and spreads `versionOperations`.
+ */
+export declare const versions: ({ max }: {
+    max: number;
+}) => {
+    readonly name: "versions";
+    readonly targets: {
+        versions: VersionsTarget;
+    };
+    readonly needs: readonly ["store"];
+};

package/dist/versions/index.js

@@ -0,0 +1,8 @@
+import { defineRukn } from '../mithaq/rukn.js';
+/** The versions target, keeping `max` versions of a row where a kayan names no window of its own. */
+export const versionsTarget = ({ max }) => ({ capability: 'versions', type: 'versions', max });
+/**
+ * The rukn a project lays down for versions and drafts: `arkan: [base, versions({ max: 100 })]`.
+ * Each kayan that keeps versions writes `targets.versions` and spreads `versionOperations`.
+ */
+export const versions = ({ max }) => defineRukn({ name: 'versions', targets: { versions: versionsTarget({ max }) }, needs: ['store'] });

package/dist/versions/versions.d.ts

@@ -0,0 +1,104 @@
+import type { ResolvedKayan } from '../mithaq/types.ts';
+import type { Store } from '../mithaq/language.ts';
+import type { Authorize, ManagedAdmin } from '../asas/runner/write.ts';
+import type { Where } from '../mithaq/where.ts';
+import type { KayanVersions } from './index.ts';
+/**
+ * The `_status` field a kayan that keeps drafts spreads into its own `fields`.
+ * A plain read leaves out a row that is not `published`.
+ */
+export declare const draftFields: {
+    readonly _status: {
+        readonly kind: 'text';
+        readonly label: {
+            readonly en: 'Status';
+            readonly ar: 'الحالة';
+        };
+        readonly options: readonly [{
+            readonly value: 'draft';
+            readonly label: {
+                readonly en: 'Draft';
+                readonly ar: 'مسودة';
+            };
+        }, {
+            readonly value: 'published';
+            readonly label: {
+                readonly en: 'Published';
+                readonly ar: 'منشور';
+            };
+        }];
+        readonly rules: {
+            readonly defaultValue: 'draft';
+            readonly index: true;
+        };
+    };
+};
+/**
+ * The three operations a kayan that keeps versions spreads beside `defaultOperations`:
+ * `findVersions`, `findVersionByID` and `restoreVersion`.
+ */
+export declare const versionOperations: {
+    findVersions: {
+        steps: (import("../asas/runner/steps.ts").ReadStep<Record<string, unknown>, Record<string, unknown>, unknown, unknown, unknown, Record<string, unknown>> & {
+            readonly __seal: "findVersions";
+        })[];
+    };
+    findVersionByID: {
+        steps: (import("../asas/runner/steps.ts").ReadStep<Record<string, unknown>, Record<string, unknown>, unknown, unknown, unknown, Record<string, unknown>> & {
+            readonly __seal: "findVersionByID";
+        })[];
+    };
+    restoreVersion: {
+        steps: (import("../asas/runner/steps.ts").WriteStep<Record<string, unknown>, Record<string, unknown>, unknown, unknown, unknown, Record<string, unknown>> & {
+            readonly __seal: "restoreVersion";
+        })[];
+    };
+};
+export declare const versionsOf: ({ kayan, kept, name, window, }: {
+    kayan: ResolvedKayan;
+    kept: KayanVersions;
+    name: string;
+    window: number;
+}) => NonNullable<ResolvedKayan['versions']>;
+type Versioned = ResolvedKayan & {
+    versions: NonNullable<ResolvedKayan['versions']>;
+};
+export declare const revived: (kayan: ResolvedKayan, snapshot: unknown) => Record<string, unknown>;
+export declare const latestVersion: ({ kayan, store, parent, tx, }: {
+    kayan: Versioned;
+    store: Pick<Store, 'find'>;
+    parent: unknown;
+    tx: unknown;
+}) => Promise<Record<string, unknown> | undefined>;
+export declare const saveVersion: ({ kayan, store, writes, tx, row, autosave, }: {
+    kayan: Versioned;
+    store: Pick<Store, 'find'>;
+    writes: Pick<Store, 'insert' | 'remove' | 'update'>;
+    tx: unknown;
+    row: Record<string, unknown>;
+    autosave: boolean;
+}) => Promise<void>;
+export declare const changedColumns: ({ kayan, snapshot, row, whole, }: {
+    kayan: ResolvedKayan;
+    snapshot: Record<string, unknown>;
+    row: Record<string, unknown>;
+    whole?: boolean;
+}) => {
+    [k: string]: {} | null;
+};
+export declare const restoreInput: <Actor>({ kayan, store, data, actor, authorize, admin, alive, seesDrafts, admits, }: {
+    kayan: Versioned;
+    store: Store;
+    data: Record<string, unknown>;
+    actor: Actor | null;
+    authorize: Authorize;
+    admin: ManagedAdmin<Actor> | undefined;
+    alive: Where | undefined;
+    /** Whether the actor holds `findVersions`, which every restore asks. */
+    seesDrafts: boolean;
+    /** The rows that key's answer admits, where it limits them: a restore and a discard reach no other. */
+    admits?: Where;
+}) => Promise<{
+    id: unknown;
+}>;
+export {};