@protobase/schema 0.7.0 → 0.8.0

package/dist/access/types.d.ts

@@ -12,6 +12,10 @@ export type AccessContext = {
   user?: AccessUser;
   operation?: AccessAction;
   record?: unknown;
+  /** With organizations, the one the request works in; `.tenant` resources are scoped to it already. */
+  organization?: {
+    id: string | number;
+  };
   /** Set by the resolver; scoped capabilities (`.own`) need `model.owner`. */
   model?: ResourceModel;
   [key: string]: unknown;

package/dist/field.d.ts

@@ -1,5 +1,6 @@
 import { FieldType } from "./model.js";
 import { FieldAccess } from "./access/types.js";
+import { FileOptions } from "./files/file-options.js";
 import { z } from "zod";
 //#region src/field.d.ts
 export type Constraint = 'min' | 'max' | 'regex';
@@ -29,6 +30,7 @@ export type FieldMeta = {
     re: RegExp;
     message: string;
   };
+  file?: FileOptions;
 };
 export type FieldTypeDef = {
   type: FieldType;

package/dist/fields/file.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+//#region src/fields/file.ts
+/** A file column holds `{provider}:{path}?name=…&size=…` as text; writes send a ticket from `:upload` instead. */
+const file = {
+	type: "file",
+	constraints: [],
+	build: () => z.string().min(1).max(4096)
+};
+//#endregion
+export { file };

package/dist/fields.d.ts

@@ -1,5 +1,6 @@
 import { Field } from "./field.js";
 import { RelationField } from "./relation-field.js";
+import { FileField } from "./file-field.js";
 import { z } from "zod";
 //#region src/fields.d.ts
 export declare const f: {
@@ -17,6 +18,8 @@ export declare const f: {
   enum: <const T extends readonly string[]>(values: T) => Field<T[number]>;
   json: () => Field<z.core.util.JSONType>;
   relation: (resource: string) => RelationField<string | number>;
+  /** A file: its column holds `{provider}:{path}?name=…&size=…` as text, and responses carry `{ uri, name, type, size, url }`. */
+  file: () => FileField<string>;
   currency: () => Field<string>;
   country: () => Field<string>;
 };

package/dist/fields.js

@@ -5,6 +5,7 @@ import { currency } from "./fields/currency.js";
 import { date } from "./fields/date.js";
 import { decimal } from "./fields/decimal.js";
 import { enumeration } from "./fields/enum.js";
+import { file } from "./fields/file.js";
 import { integer } from "./fields/integer.js";
 import { json } from "./fields/json.js";
 import { relation } from "./fields/relation.js";
@@ -13,6 +14,8 @@ import { timestamp } from "./fields/timestamp.js";
 import { uuid } from "./fields/uuid.js";
 import { Field } from "./field.js";
 import { RelationField } from "./relation-field.js";
+import { defaultMaxSize } from "./files/file-options.js";
+import { FileField } from "./file-field.js";
 //#region src/fields.ts
 const baseMeta = (def) => ({
 	type: def.type,
@@ -42,6 +45,15 @@ const f = {
 		...baseMeta(relation),
 		relation: { resource }
 	}),
+	/** A file: its column holds `{provider}:{path}?name=…&size=…` as text, and responses carry `{ uri, name, type, size, url }`. */
+	file: () => new FileField(file, {
+		...baseMeta(file),
+		file: {
+			accept: [],
+			maxSize: defaultMaxSize,
+			provider: "private"
+		}
+	}),
 	currency: () => make(currency),
 	country: () => make(country)
 };

package/dist/file-field.d.ts

@@ -0,0 +1,27 @@
+import { FieldAccess } from "./access/types.js";
+import { FileProcessor } from "./files/file-options.js";
+import { Field, FieldMeta } from "./field.js";
+//#region src/file-field.d.ts
+/** `f.file()`: a text column holding a file's URI, uploaded through `:upload`. */
+export declare class FileField<V> extends Field<V> {
+  /** Allowed types, checked against the type detected from the content: `['image/*', 'application/pdf']`. */
+  accept(types: readonly string[]): FileField<V>;
+  /** The largest upload, as bytes or text such as `10 MB`; default 50 MB. */
+  maxSize(size: number | string): FileField<V>;
+  /** Stored with the `public` provider, at a permanent URL anyone with it may open. */
+  public(): FileField<V>;
+  /** Stored with this provider of `files.providers`; default `private`. */
+  storage(provider: string): FileField<V>;
+  /**
+   * Values computed from each upload, written to other fields of the resource (read-only ones) in the same write as the
+   * file: `{ image_width: imageSize('width') }`. Clearing the file clears them.
+   */
+  derive(processors: Record<string, FileProcessor>): FileField<V>;
+  optional(): FileField<V | null>;
+  readOnly(): FileField<V>;
+  column(name: string): FileField<V>;
+  access(rules: FieldAccess): FileField<V>;
+  protected with(patch: Partial<FieldMeta>): FileField<V>;
+  private withFile;
+}
+//#endregion

package/dist/file-field.js

@@ -0,0 +1,61 @@
+import { Field } from "./field.js";
+import { checkedAccept, checkedProvider, parseSize } from "./files/file-options.js";
+//#region src/file-field.ts
+/** `f.file()`: a text column holding a file's URI, uploaded through `:upload`. */
+var FileField = class FileField extends Field {
+	/** Allowed types, checked against the type detected from the content: `['image/*', 'application/pdf']`. */
+	accept(types) {
+		return this.withFile({ accept: checkedAccept(types) });
+	}
+	/** The largest upload, as bytes or text such as `10 MB`; default 50 MB. */
+	maxSize(size) {
+		return this.withFile({ maxSize: parseSize(size) });
+	}
+	/** Stored with the `public` provider, at a permanent URL anyone with it may open. */
+	public() {
+		return this.storage("public");
+	}
+	/** Stored with this provider of `files.providers`; default `private`. */
+	storage(provider) {
+		return this.withFile({ provider: checkedProvider(provider) });
+	}
+	/**
+	* Values computed from each upload, written to other fields of the resource (read-only ones) in the same write as the
+	* file: `{ image_width: imageSize('width') }`. Clearing the file clears them.
+	*/
+	derive(processors) {
+		return this.withFile({ derive: {
+			...this.meta.file.derive,
+			...processors
+		} });
+	}
+	optional() {
+		return this.with({ nullable: true });
+	}
+	readOnly() {
+		return this.with({ readOnly: true });
+	}
+	column(name) {
+		return this.with({ column: name });
+	}
+	access(rules) {
+		return this.with({ access: {
+			...this.meta.access,
+			...rules
+		} });
+	}
+	with(patch) {
+		return new FileField(this.def, {
+			...this.meta,
+			...patch
+		});
+	}
+	withFile(patch) {
+		return this.with({ file: {
+			...this.meta.file,
+			...patch
+		} });
+	}
+};
+//#endregion
+export { FileField };

package/dist/files/file-options.d.ts

@@ -0,0 +1,34 @@
+//#region src/files/file-options.d.ts
+/** What a processor gets: the stored upload's decided type, size and name, its first bytes, and the whole of it on demand. */
+export type FileProcessorInput = {
+  name: string;
+  type: string;
+  size: number;
+  /** The first bytes of the content (up to 256 KB), enough for image headers. */
+  head: Uint8Array;
+  /** The whole content, read from storage. */
+  read(): Promise<ReadableStream<Uint8Array>>;
+};
+/**
+ * Computes a value for another column from an upload (`.derive()`). It runs once, on the upload route; a file whose type
+ * is not in `accepts` leaves the column null.
+ */
+export type FileProcessor = {
+  /** Exact types and `type/*` wildcards; every type when omitted. */
+  accepts?: readonly string[];
+  run: (file: FileProcessorInput) => unknown;
+};
+/** A file field's settings, as the builder collects them. */
+export type FileOptions = {
+  accept: string[];
+  maxSize: number;
+  provider: string;
+  derive?: Record<string, FileProcessor>;
+};
+/** Bytes from a number or text such as `10 MB` (decimal units) or `5 MiB` (binary units). */
+export declare const parseSize: (size: number | string) => number;
+/** Allowed types, lowercased: exact types and `type/*` wildcards; `*` alone is refused so that every type is a choice. */
+export declare const checkedAccept: (types: readonly string[]) => string[];
+/** A provider name: lowercase, at most 32 characters, and not a scheme browsers already know. */
+export declare const checkedProvider: (name: string) => string;
+//#endregion

package/dist/files/file-options.js

@@ -0,0 +1,47 @@
+//#region src/files/file-options.ts
+const defaultMaxSize = 5e7;
+const units = {
+	b: 1,
+	kb: 1e3,
+	mb: 1e6,
+	gb: 1e9,
+	kib: 1024,
+	mib: 1024 ** 2,
+	gib: 1024 ** 3
+};
+/** Bytes from a number or text such as `10 MB` (decimal units) or `5 MiB` (binary units). */
+const parseSize = (size) => {
+	if (typeof size === "number") {
+		if (!Number.isSafeInteger(size) || size <= 0) throw new Error(`A file size must be a positive whole number of bytes, not ${size}`);
+		return size;
+	}
+	const match = /^\s*(\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i.exec(size);
+	const unit = units[(match?.[2] ?? "b").toLowerCase()];
+	if (!match || !unit) throw new Error(`"${size}" is not a size; write it like "10 MB" or "512 KiB"`);
+	return parseSize(Math.round(Number(match[1]) * unit));
+};
+const typePattern = /^(?:\*\/\*|[a-z0-9][a-z0-9!#$&^_.+-]*\/(?:\*|[a-z0-9][a-z0-9!#$&^_.+-]*))$/;
+/** Allowed types, lowercased: exact types and `type/*` wildcards; `*` alone is refused so that every type is a choice. */
+const checkedAccept = (types) => types.map((type) => {
+	const lower = type.trim().toLowerCase();
+	if (!typePattern.test(lower)) throw new Error(`"${type}" is not a media type or a type/* wildcard`);
+	return lower;
+});
+const providerPattern = /^[a-z][a-z0-9-]{0,31}$/;
+const reservedProviders = /* @__PURE__ */ new Set([
+	"http",
+	"https",
+	"data",
+	"blob",
+	"file",
+	"javascript",
+	"mailto"
+]);
+/** A provider name: lowercase, at most 32 characters, and not a scheme browsers already know. */
+const checkedProvider = (name) => {
+	if (!providerPattern.test(name)) throw new Error(`"${name}" is not a file provider name: lowercase letters, digits and dashes, starting with a letter`);
+	if (reservedProviders.has(name)) throw new Error(`"${name}" cannot name a file provider: stored values would read as ${name}: links`);
+	return name;
+};
+//#endregion
+export { checkedAccept, checkedProvider, defaultMaxSize, parseSize };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { ActionModel, ActionRun, ChartGranularity, ChartModel, ChartRange, CheckedFilter, CompareOp, DatePreset, DurationLiteral, DurationUnit, FieldFormat, FieldModel, FieldPath, FieldType, FieldViewModel, FilterError, FilterErrorCode, FilterExpr, FilterOf, FilterValue, FilterWidgetModel, KeyValue, LayoutItemModel, ListModel, ListQuery, Literal, NavModel, NavRecentModel, NowValue, OrderByItem, RelatedModel, ResourceModel, SaveFeedback, SearchMatch, SearchResultModel, SortSpec, Span, StatusTone, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
+import { ActionModel, ActionRun, ChartGranularity, ChartModel, ChartRange, CheckedFilter, CompareOp, DatePreset, DurationLiteral, DurationUnit, FieldFormat, FieldModel, FieldPath, FieldType, FieldViewModel, FileFieldModel, FilterError, FilterErrorCode, FilterExpr, FilterOf, FilterValue, FilterWidgetModel, KeyValue, LayoutItemModel, ListModel, ListQuery, Literal, NavModel, NavRecentModel, NowValue, OrderByItem, RelatedModel, ResourceModel, SaveFeedback, SearchMatch, SearchResultModel, SortSpec, Span, StatusTone, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
 import { AccessAction, AccessContext, AccessFn, AccessResult, AccessUser, FieldAccess, FieldRule } from "./access/types.js";
+import { FileProcessor, FileProcessorInput, checkedAccept, checkedProvider, parseSize } from "./files/file-options.js";
 import { Field } from "./field.js";
+import { FileField } from "./file-field.js";
 import { f } from "./fields.js";
 import { InferRecord, RecordKey } from "./resource-types.js";
 import { resource } from "./resource.js";
@@ -28,4 +30,4 @@ import "./access/index.js";
 import { AssistantAction, AssistantActionRequest, AssistantCardPart, AssistantDiff, AssistantEvent, AssistantMessage, AssistantMessageRequest, AssistantPart, AssistantState, AssistantStep, AssistantStepState, AssistantTablePart, AssistantTextPart, AssistantTone, AssistantWidgetPart } from "./assistant/protocol.js";
 import { applyAssistantEvent, emptyAssistantState } from "./assistant/apply-event.js";
 import { readEventStream } from "./assistant/event-stream.js";
-export { type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionModel, type ActionRun, type AssistantAction, type AssistantActionRequest, type AssistantCardPart, type AssistantDiff, type AssistantEvent, type AssistantMessage, type AssistantMessageRequest, type AssistantPart, type AssistantState, type AssistantStep, type AssistantStepState, type AssistantTablePart, type AssistantTextPart, type AssistantTone, type AssistantWidgetPart, type Capability, type CapabilityAction, type CapabilityScope, type ChartGranularity, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CompareOp, type DatePreset, type DurationLiteral, type DurationUnit, type EvaluateOptions, type Field, type FieldAccess, type FieldFormat, type FieldModel, type FieldPath, type FieldRule, type FieldType, type FieldViewModel, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type InferRecord, type KeyType, type KeyValue, type LayoutItemModel, type ListModel, type ListQuery, type Literal, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type RecordKey, type RelatedModel, type ResolveOptions, type ResolvedAccess, type ResourceModel, type Roles, type RolesOptions, type RowFilterOperation, type Rule, type SaveFeedback, type SearchMatch, type SearchResultModel, type SearchTerm, type SortSpec, type Span, type StatusTone, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type ViewModel, accessWarnings, applyAssistantEvent, checkFilter, checkOrderBy, checkRecord, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, where };
+export { type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionModel, type ActionRun, type AssistantAction, type AssistantActionRequest, type AssistantCardPart, type AssistantDiff, type AssistantEvent, type AssistantMessage, type AssistantMessageRequest, type AssistantPart, type AssistantState, type AssistantStep, type AssistantStepState, type AssistantTablePart, type AssistantTextPart, type AssistantTone, type AssistantWidgetPart, type Capability, type CapabilityAction, type CapabilityScope, type ChartGranularity, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CompareOp, type DatePreset, type DurationLiteral, type DurationUnit, type EvaluateOptions, type Field, type FieldAccess, type FieldFormat, type FieldModel, type FieldPath, type FieldRule, type FieldType, type FieldViewModel, type FileField, type FileFieldModel, type FileProcessor, type FileProcessorInput, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type InferRecord, type KeyType, type KeyValue, type LayoutItemModel, type ListModel, type ListQuery, type Literal, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type RecordKey, type RelatedModel, type ResolveOptions, type ResolvedAccess, type ResourceModel, type Roles, type RolesOptions, type RowFilterOperation, type Rule, type SaveFeedback, type SearchMatch, type SearchResultModel, type SearchTerm, type SortSpec, type Span, type StatusTone, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type ViewModel, accessWarnings, applyAssistantEvent, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, where };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { checkedAccept, checkedProvider, parseSize } from "./files/file-options.js";
 import { f } from "./fields.js";
 import { resource } from "./resource.js";
 import { parseFilter } from "./filter/parse.js";
@@ -20,4 +21,4 @@ import { restrictModel } from "./access/restrict.js";
 import { accessWarnings, checkRecord, fieldsUsedBy, resolveAccess } from "./access/resolve.js";
 import { applyAssistantEvent, emptyAssistantState } from "./assistant/apply-event.js";
 import { readEventStream } from "./assistant/event-stream.js";
-export { accessWarnings, applyAssistantEvent, checkFilter, checkOrderBy, checkRecord, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, where };
+export { accessWarnings, applyAssistantEvent, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, where };

package/dist/model.d.ts

@@ -22,6 +22,14 @@ export type FieldModel = {
   } | {
     db: true;
   };
+  /** A file field's allowed types (empty: any), largest upload in bytes, provider, and the fields `.derive()` writes. */
+  file?: FileFieldModel;
+};
+export type FileFieldModel = {
+  accept: string[];
+  maxSize: number;
+  provider: string;
+  derive?: string[];
 };
 /** `digitsEnd`: only the end of the value's digits, spaces, `+` and dashes ignored (phone numbers). */
 export type SearchMatch = 'digitsEnd';

package/dist/resource-model.js

@@ -28,6 +28,12 @@ const fieldModel = (name, field) => {
 		...meta.relation && { relation: {
 			resource: meta.relation.resource,
 			columns: meta.relation.columns ?? [column]
+		} },
+		...meta.file && { file: {
+			accept: [...meta.file.accept],
+			maxSize: meta.file.maxSize,
+			provider: meta.file.provider,
+			...meta.file.derive && Object.keys(meta.file.derive).length > 0 && { derive: Object.keys(meta.file.derive) }
 		} }
 	};
 };
@@ -60,9 +66,28 @@ const sensitiveProblems = (model) => Object.values(model.fields).filter((field)
 		model.softDelete
 	].includes(field.name) ? ["a key, tenant, owner or soft delete field"] : []
 ].map((problem) => `sensitive field "${field.name}" cannot be ${problem}`));
+const fileProblems = (model) => Object.values(model.fields).filter((field) => field.file).flatMap((field) => [
+	...field.filterable ? ["cannot be filterable"] : [],
+	...field.sortable ? ["cannot be sortable"] : [],
+	...field.aliases.length > 0 ? ["cannot be aliased"] : [],
+	...field.sensitive ? ["cannot be sensitive (not implemented)"] : [],
+	...model.search?.includes(field.name) ? ["cannot be searched"] : [],
+	...[
+		...model.primaryKey,
+		model.tenant,
+		model.owner,
+		model.softDelete
+	].includes(field.name) ? ["cannot be a key, tenant, owner or soft delete field"] : [],
+	...(field.file.derive ?? []).flatMap((target) => {
+		const derived = Object.hasOwn(model.fields, target) ? model.fields[target] : void 0;
+		if (!derived) return [`derives "${target}", which is not a field`];
+		if (target === field.name || derived.file) return [`derives "${target}", which is a file field`];
+		return derived.readOnly ? [] : [`derives "${target}", which must be readOnly()`];
+	})
+].map((problem) => `file field "${field.name}" ${problem}`));
 const buildResourceModel = (state) => {
 	const model = assembleModel(state);
-	const problems = sensitiveProblems(model);
+	const problems = [...sensitiveProblems(model), ...fileProblems(model)];
 	if (problems.length > 0) throw new Error(`Resource "${model.name}": ${problems.join("; ")}`);
 	return model;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/schema",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Resource, field, view and access definitions for Protobase configs.",
   "license": "Apache-2.0",
   "repository": {