@routier/core 0.2.1 → 0.3.0

package/dist/schema/property/base/SchemaBase.d.ts

@@ -1,4 +1,4 @@
-import { DefaultValue, ForeignKey, FunctionBody, PropertyDeserializer, PropertySerializer, SchemaModifiers, SchemaTypes } from "../../types";
+import { DefaultValue, ForeignKey, FunctionBody, PropertyDeserializer, PropertySerializer, SchemaModifiers, SchemaTypes, PropertyTransform } from "../../types";
 export declare abstract class SchemaBase<T extends any, TModifiers extends SchemaModifiers> {
     abstract instance: T;
     modifiers: TModifiers;
@@ -8,9 +8,55 @@ export declare abstract class SchemaBase<T extends any, TModifiers extends Schem
     isKey: boolean;
     isIdentity: boolean;
     isReadonly: boolean;
-    isDistict: boolean;
+    isDistinct: boolean;
+    /**
+     * Set by `.modify(x => x.transform(...))`. A live reference, never stringified.
+     * `null` when the property is stored as it is.
+     */
+    transform: PropertyTransform<unknown> | null;
     indexes: string[];
     fromPropertyName: string | null;
+    /**
+     * How many numbers a vector holds. `null` for every other type.
+     *
+     * Declared here rather than on `SchemaVector` because a modifier WRAPS rather than
+     * extends: `s.vector(1536).optional()` is a `SchemaOptional`, and anything reachable only
+     * through the original class is lost the moment a modifier is added. `type` survives for
+     * exactly this reason — the copy constructor below carries it — and a dimension count has
+     * to travel with it, or an optional vector reaches a backend as a vector of unknown width
+     * and cannot be given a column.
+     *
+     * `innerSchema` is the cautionary example: it lives on `SchemaArray` alone, so a modified
+     * array arrives with no element type and clones through the slow path.
+     */
+    dimensions: number | null;
+    /**
+     * The longest string the property is declared to hold. `null` for every other type, and
+     * for a string that declares nothing.
+     *
+     * Declared here rather than on `SchemaString` for the same reason as `dimensions` above:
+     * `s.string({ maxLength: 4000 }).optional()` is a `SchemaOptional`, so anything reachable
+     * only through `SchemaString` is lost the moment a modifier is added.
+     *
+     * A declaration, never a validation. Core does not check a value against it and does not
+     * truncate. The backend that can use the number does: MySQL gives the column
+     * `VARCHAR(maxLength)` instead of the blanket `VARCHAR(255)`. Every other backend ignores
+     * it, because a string column that is already unbounded cannot be made more correct by
+     * knowing a bound.
+     */
+    maxLength: number | null;
+    /**
+     * Whether this string may be tokenised into a full-text search index.
+     *
+     * Set by `.searchable()`, and only ever true on a string. Eligibility, not membership: a
+     * collection that never declares `.searchIndex()` indexes nothing regardless.
+     *
+     * Copied by the constructor below, so `s.string().searchable().optional()` stays searchable.
+     * Every flag on this class is copied for the same reason: a modifier WRAPS rather than
+     * extends, so anything the constructor forgets is silently dropped the moment a property
+     * gains one more modifier.
+     */
+    isSearchable: boolean;
     foreignKeyDefinition: ForeignKey<unknown> | null;
     tags: string[];
     injected: any;

package/dist/schema/property/modifiers/SchemaNullable.d.ts

@@ -3,11 +3,21 @@ import { SchemaBase } from "../base/SchemaBase";
 import { SchemaDefault } from "./SchemaDefault";
 import { SchemaDeserialize } from "./SchemaDeserialize";
 import { SchemaOptional } from "./SchemaOptional";
+import { SchemaSearchable } from "./SchemaSearchable";
 export declare class SchemaNullable<T extends any, TModifiers extends SchemaModifiers> extends SchemaBase<T, TModifiers> {
     instance: T;
     private _schemaNullable;
     constructor(current: SchemaBase<T, TModifiers>);
     optional(): SchemaOptional<T, "optional" | TModifiers>;
+    /**
+     * Only callable when the property underneath is a string — see the same method on
+     * `SchemaOptional` for why the constraint is on `instance` rather than the whole class.
+     *
+     * A null value contributes no tokens.
+     */
+    searchable(this: {
+        instance: string;
+    }): SchemaSearchable<T, "searchable" | TModifiers>;
     default<I = never>(value: DefaultValue<T | null, I>, injected?: I): SchemaDefault<T, I, "default" | TModifiers>;
     deserialize(deserializer: PropertyDeserializer<T | null>): SchemaDeserialize<T, "deserialize" | TModifiers>;
 }

package/dist/schema/property/modifiers/SchemaOptional.d.ts

@@ -2,10 +2,29 @@ import { PropertyDeserializer, SchemaModifiers } from "../../types";
 import { SchemaBase } from "../base/SchemaBase";
 import { SchemaDeserialize } from "./SchemaDeserialize";
 import { SchemaNullable } from "./SchemaNullable";
+import { SchemaSearchable } from "./SchemaSearchable";
 export declare class SchemaOptional<T extends any, TModifiers extends SchemaModifiers> extends SchemaBase<T, TModifiers> {
     instance: T;
     private _schemaOptional;
     constructor(current: SchemaBase<T, TModifiers>);
     nullable(): SchemaNullable<T, "nullable" | TModifiers>;
+    /**
+     * Only callable when the property underneath is a string.
+     *
+     * A wrapper does not know what it wraps at runtime, but the type does: `T` is the value
+     * type, so `s.number().optional()` is a `SchemaOptional<number>` and fails this `this`
+     * constraint. That is the gate — there is no runtime check, because a builder that offers
+     * a method it will then reject has already failed at its job.
+     *
+     * Constrained on `instance` alone rather than the whole class. `SchemaBase` holds `T` in
+     * contravariant positions too (`valueSerializer`, `defaultValue`), so requiring the full
+     * `SchemaOptional<string, ...>` would reject a literal union like
+     * `s.string("draft", "published")`, which is a perfectly good searchable string.
+     *
+     * An absent value contributes no tokens.
+     */
+    searchable(this: {
+        instance: string;
+    }): SchemaSearchable<T, "searchable" | TModifiers>;
     deserialize(deserializer: PropertyDeserializer<T | undefined>): SchemaDeserialize<T, "deserialize" | TModifiers>;
 }

package/dist/schema/property/modifiers/SchemaSearchable.d.ts

@@ -0,0 +1,34 @@
+import { SchemaModifiers } from "../../types";
+import { SchemaBase } from "../base/SchemaBase";
+import { SchemaNullable } from "./SchemaNullable";
+import { SchemaOptional } from "./SchemaOptional";
+/**
+ * Marks a string property as eligible for a full-text search index.
+ *
+ * Eligible, not indexed. The schema says what COULD be indexed; the collection builder's
+ * `.searchIndex()` says that it IS. A property marked here on a collection that never declares
+ * an index costs nothing at all — no rows, no write amplification, no storage.
+ *
+ * Like `s.vector()`, this exists to be RECOGNISED rather than to behave. It changes nothing
+ * about how the property is stored, cloned, compared, serialized or queried. The datastore
+ * reads the flag off the compiled schema to decide which values to tokenise; every plugin is
+ * unaware the property is any different from another string.
+ *
+ * Declared on `SchemaString` only, so `s.number().searchable()` is a compile error rather than
+ * a runtime surprise. The one case the type system cannot catch — a searchable string nested
+ * inside an `s.object()` — is rejected when the schema compiles: v1 indexes root-level string
+ * properties only.
+ */
+export declare class SchemaSearchable<T extends any, TModifiers extends SchemaModifiers> extends SchemaBase<T, TModifiers> {
+    instance: T;
+    private _schemaSearchable;
+    constructor(current: SchemaBase<T, TModifiers>);
+    /**
+     * Declared here so `.searchable()` composes in BOTH senses — `.searchable().optional()` and
+     * `.optional().searchable()` mean the same thing and both keep the flag. `SchemaDistinct`
+     * exposes neither, which is why `.distinct().optional()` is unwritable and its copy-loss
+     * (see `SchemaBase.isSearchable`) has never been noticed.
+     */
+    optional(): SchemaOptional<T, "optional" | TModifiers>;
+    nullable(): SchemaNullable<T, "nullable" | TModifiers>;
+}

package/dist/schema/property/modifiers/index.d.ts

@@ -7,6 +7,7 @@ export * from './SchemaKey';
 export * from './SchemaNullable';
 export * from './SchemaOptional';
 export * from './SchemaReadonly';
+export * from './SchemaSearchable';
 export * from './SchemaSerialize';
 export * from './SchemaTracked';
 export * from './SchemaFrom';

package/dist/schema/property/types/SchemaFile.d.ts

@@ -0,0 +1,60 @@
+import { DefaultValue, SchemaModifiers, SchemaTypes } from "../../types";
+import { SchemaBase } from "../base/SchemaBase";
+import { SchemaDefault } from "../modifiers/SchemaDefault";
+import { SchemaFrom } from "../modifiers/SchemaFrom";
+import { SchemaNullable } from "../modifiers/SchemaNullable";
+import { SchemaOptional } from "../modifiers/SchemaOptional";
+import { SchemaReadonly } from "../modifiers/SchemaReadonly";
+import { SchemaTag } from "../modifiers/SchemaTag";
+/**
+ * A file: content on the way in, a reference on the way out.
+ *
+ * This is the one property type whose write shape differs from its stored shape. You assign
+ * a `File`, a `Blob`, a `Uint8Array` or a string; what is stored, and what a query gives
+ * back, is a reference — where the bytes live and what they are.
+ *
+ * ```ts
+ * const documentSchema = s.define('documents', {
+ *     id: s.string().key().identity(),
+ *     title: s.string(),
+ *     file: s.file(),
+ * }).compile();
+ *
+ * await store.documents.addAsync({ title: 'Q3', file: fileFromInput });
+ * await store.saveChangesAsync();
+ *
+ * doc.file.size          // 2_400_112
+ * doc.file.contentType   // 'application/pdf'
+ * ```
+ *
+ * ## Why this cannot be `s.object({ key, size, ... })`
+ *
+ * The generated `preprocess` rebuilds an object property field by field from its declared
+ * children — `result.file = {}` and then one assignment per child. Content assigned there is
+ * therefore discarded by construction, before any plugin sees the entity: the property does
+ * not arrive mangled, it does not arrive at all.
+ *
+ * A file is a LEAF here, with no child properties, so the generated code passes it through
+ * untouched. The bytes survive as far as the plugin, which is the only place an upload can
+ * happen — `preprocess` is synchronous and is called from the change tracker and the
+ * broadcast path, so it cannot await one.
+ *
+ * ## What actually stores it
+ *
+ * Nothing in core uploads anything. `@routier/blob-plugin` wraps your real plugin, swaps
+ * pending content for a reference during `bulkPersist`, and hands the reference down. Without
+ * that wrapper a file property stores whatever you assigned, which is a mistake this type
+ * cannot detect on its own.
+ */
+export declare class SchemaFile<T extends any, TModifiers extends SchemaModifiers> extends SchemaBase<T, TModifiers> {
+    instance: T;
+    type: SchemaTypes;
+    private _schemaFile;
+    constructor();
+    from(propertyName: string): SchemaFrom<T, TModifiers>;
+    optional(): SchemaOptional<T, "optional" | TModifiers>;
+    nullable(): SchemaNullable<T, "nullable" | TModifiers>;
+    readonly(): SchemaReadonly<T, "readonly" | TModifiers>;
+    default<I = never>(value: DefaultValue<T, I>, injected?: I): SchemaDefault<T, I, "default" | TModifiers>;
+    tag(...tags: string[]): SchemaTag<T, TModifiers>;
+}

package/dist/schema/property/types/SchemaString.d.ts

@@ -1,4 +1,4 @@
-import { CompiledSchema, DefaultValue, InferType, PropertyDeserializer, PropertySerializer, SchemaModifiers, SchemaTypes } from "../../types";
+import { CompiledSchema, DefaultValue, InferType, PropertyDeserializer, PropertySerializer, SchemaModifiers, SchemaTypes, StringOptions } from "../../types";
 import { SchemaBase } from "../base/SchemaBase";
 import { SchemaDefault } from "../modifiers/SchemaDefault";
 import { SchemaDeserialize } from "../modifiers/SchemaDeserialize";
@@ -11,6 +11,7 @@ import { SchemaKey } from "../modifiers/SchemaKey";
 import { SchemaNullable } from "../modifiers/SchemaNullable";
 import { SchemaOptional } from "../modifiers/SchemaOptional";
 import { SchemaReadonly } from "../modifiers/SchemaReadonly";
+import { SchemaSearchable } from "../modifiers/SchemaSearchable";
 import { SchemaSerialize } from "../modifiers/SchemaSerialize";
 import { SchemaTag } from "../modifiers/SchemaTag";
 import { SchemaArray } from "./SchemaArray";
@@ -18,6 +19,12 @@ export declare class SchemaString<T extends string, TModifiers extends SchemaMod
     instance: T;
     type: SchemaTypes;
     private _schemaString;
+    /**
+     * @param entity Copied from when a modifier wraps this property.
+     * @param literals The allowed values, when the string is a literal union.
+     * @param options Declarations a backend may use. See `StringOptions`.
+     */
+    constructor(entity?: SchemaBase<T, TModifiers> | null, literals?: T[], options?: StringOptions);
     from(propertyName: string): SchemaFrom<T, TModifiers>;
     constrain<K extends T>(): SchemaString<K, TModifiers>;
     optional(): SchemaOptional<T, "optional" | TModifiers>;
@@ -32,5 +39,18 @@ export declare class SchemaString<T extends string, TModifiers extends SchemaMod
     array(): SchemaArray<this, TModifiers>;
     index(...indexes: string[]): SchemaIndex<T, TModifiers>;
     distinct(): SchemaDistinct<T, "distinct" | TModifiers>;
+    /**
+     * Marks this string as eligible for the collection's full-text search index.
+     *
+     * ```ts
+     * title: s.string().searchable(),
+     * body: s.string({ maxLength: 4000 }).searchable(),
+     * ```
+     *
+     * Nothing is indexed until the collection declares `.searchIndex()`. Combines with
+     * `.optional()` and `.nullable()` in either sense — an absent or null value contributes no
+     * tokens.
+     */
+    searchable(): SchemaSearchable<T, "searchable" | TModifiers>;
     tag(...tags: string[]): SchemaTag<T, TModifiers>;
 }

package/dist/schema/property/types/SchemaVector.d.ts

@@ -0,0 +1,61 @@
+import { DefaultValue, SchemaModifiers, SchemaTypes } from "../../types";
+import { SchemaBase } from "../base/SchemaBase";
+import { SchemaDefault } from "../modifiers/SchemaDefault";
+import { SchemaFrom } from "../modifiers/SchemaFrom";
+import { SchemaNullable } from "../modifiers/SchemaNullable";
+import { SchemaOptional } from "../modifiers/SchemaOptional";
+import { SchemaReadonly } from "../modifiers/SchemaReadonly";
+import { SchemaTag } from "../modifiers/SchemaTag";
+/**
+ * An embedding: a fixed-length list of numbers you can search by similarity.
+ *
+ * ```ts
+ * const documentSchema = s.define('documents', {
+ *     id: s.string().key().identity(),
+ *     title: s.string(),
+ *     embedding: s.vector(1536),
+ * }).compile();
+ *
+ * const similar = await store.documents
+ *     .nearest(x => x.embedding, queryEmbedding, 10)
+ *     .toArrayAsync();
+ * ```
+ *
+ * ## Why this is not `s.array(s.number())`
+ *
+ * By value it is exactly that, and every codegen handler treats the two the same on purpose —
+ * a vector clones with a spread, compares by JSON and freezes like any other array. What an
+ * array cannot carry is the DIMENSION COUNT, and a backend that stores vectors natively needs
+ * it at DDL time: pgvector's column type is `vector(1536)`, not `vector`.
+ *
+ * So this exists to be RECOGNISED, not to behave differently. A backend that knows what a
+ * vector is stores one; every other backend sees a list of numbers and stores JSON, which is
+ * why the feature works everywhere rather than only on PostgreSQL.
+ *
+ * ## Dimensions are not enforced here
+ *
+ * `dimensions` is a declaration, and core never checks a value against it. The check belongs
+ * where the cost of being wrong is paid: a backend with a native `vector(n)` column rejects a
+ * mismatched write itself, with an error naming the column. Validating in core would duplicate
+ * that on the backends that already do it and add a per-save array scan to the ones that
+ * cannot use the information at all.
+ *
+ * ## Similarity is cosine, and it is not a filter
+ *
+ * `.nearest()` is an ordering plus a limit — it returns the closest rows, not the matching
+ * ones. Distance itself is not exposed: the entity shape is fixed, and the ordering is what
+ * callers act on. A backend with no vector support scores in memory, so the answer is the
+ * same everywhere; only the amount of data read differs.
+ */
+export declare class SchemaVector<T extends any, TModifiers extends SchemaModifiers> extends SchemaBase<T, TModifiers> {
+    instance: T;
+    type: SchemaTypes;
+    private _schemaVector;
+    constructor(dimensions: number);
+    from(propertyName: string): SchemaFrom<T, TModifiers>;
+    optional(): SchemaOptional<T, "optional" | TModifiers>;
+    nullable(): SchemaNullable<T, "nullable" | TModifiers>;
+    readonly(): SchemaReadonly<T, "readonly" | TModifiers>;
+    default<I = never>(value: DefaultValue<T, I>, injected?: I): SchemaDefault<T, I, "default" | TModifiers>;
+    tag(...tags: string[]): SchemaTag<T, TModifiers>;
+}

package/dist/schema/property/types/index.d.ts

@@ -4,3 +4,5 @@ export * from './SchemaDate';
 export * from './SchemaNumber';
 export * from './SchemaObject';
 export * from './SchemaString';
+export * from './SchemaFile';
+export * from './SchemaVector';

package/dist/schema/table/SchemaTransform.d.ts

@@ -0,0 +1,40 @@
+import { SchemaBase } from "../property/base/SchemaBase";
+import { PropertyTransform, SchemaModifiers } from "../types";
+/**
+ * A two-way transform between the value your application holds and the value that is stored.
+ *
+ * Declared in `.modify()`, beside `computed` and `function`, because it belongs to the same
+ * family: a property whose stored form is derived rather than assigned. `computed` derives one
+ * way and cannot come back; a transform declares both directions.
+ *
+ * ```ts
+ * const cipher = myEncryption(keyring);   // whatever you use — {} with `to` and `from`
+ *
+ * const userSchema = s.define('users', {
+ *     id: s.string().key().identity(),
+ *     ssn: s.string(),
+ * }).modify(x => ({
+ *     ssn: x.transform(cipher),
+ * })).compile();
+ * ```
+ *
+ * `to` and `from` may be async, and they are held as LIVE references — never stringified into
+ * generated code the way `computed` is. So they close over whatever they need, which is why
+ * there is no `injected` argument to pass and no property to repeat.
+ *
+ * Nothing about this is encryption. Encryption is one thing a caller might write here;
+ * compression, redaction, unit conversion and a custom codec are others. The library ships no
+ * behaviour of its own for this — it only carries what you supply.
+ */
+export declare class SchemaTransform<T extends any, TModifiers extends SchemaModifiers = never> extends SchemaBase<T, TModifiers> {
+    instance: T;
+    private _schemaTransform;
+    /**
+     * Bound to the property it replaces when the schema is assembled.
+     *
+     * You do not pass the property in. `.modify()` already knows which one you mean — it is
+     * the key you assigned to — so repeating `s.string()` would be ceremony for nothing.
+     */
+    bindTo(underlying: SchemaBase<T, TModifiers>): this;
+    constructor(transform: PropertyTransform<T>);
+}

package/dist/schema/table/index.d.ts

@@ -1,2 +1,3 @@
 export * from './SchemaComputed';
 export * from './SchemaFunction';
+export * from './SchemaTransform';

package/dist/schema/types.d.ts

@@ -1,12 +1,14 @@
 import type { SchemaDefinition } from "./SchemaDefinition";
 import type { SchemaBase } from "./property/base/SchemaBase";
 import type { SchemaArray } from "./property/types/SchemaArray";
+import type { SchemaVector } from "./property/types/SchemaVector";
 import type { SchemaObject } from "./property/types/SchemaObject";
 import type { PropertyInfo } from "./PropertyInfo";
 import type { DeepPartial } from "../types";
 import type { SchemaFunction } from "./table";
-import type { SchemaOptional } from "./property/modifiers";
+import type { SchemaOptional, SchemaTag } from "./property/modifiers";
 import type { Branded } from "../utilities/types";
+import type { SchemaSubscriptionOptions } from "./communication/broadcast";
 export type DefaultValue<T, I = never> = T | ((injected: I) => T);
 export type FunctionBody<TEntity, TResult> = (entity: TEntity, collectionName: CollectionName) => TResult;
 export type IdType = string | number;
@@ -23,9 +25,70 @@ export declare enum SchemaTypes {
     String = "String",
     Definition = "Definition",
     Function = "Function",
-    Computed = "Computed"
+    Computed = "Computed",
+    /**
+     * Content in, reference out. The only type whose write shape differs from its stored
+     * shape, and a leaf on purpose — see `SchemaFile`.
+     */
+    File = "File",
+    /**
+     * A fixed-length list of numbers, carrying its dimension count — see `SchemaVector`.
+     *
+     * Value-shaped exactly like `s.array(s.number())`, which is why every array codegen
+     * handler accepts it. It is a distinct type only so a backend can recognise it and store
+     * it natively; nothing else needs to tell the two apart.
+     */
+    Vector = "Vector"
 }
 export type ArrayShape = string | number | Date | {};
+/**
+ * What a file property gives back: where the bytes are and what they are.
+ *
+ * Declared in core so `InferType` can name it. Core never reads or writes the bytes — it only
+ * carries this shape — and `@routier/blob-plugin` is what puts one here.
+ */
+export type FileReferenceValue = {
+    /** Where the bytes live, content-addressed by the blob plugin. */
+    key: string;
+    /** Byte length. */
+    size: number;
+    /** Media type as supplied at upload. */
+    contentType: string;
+    /** SHA-256 of the bytes, lowercase hex. */
+    checksum: string;
+    /** The name to show a user. Not part of the key. */
+    fileName: string;
+};
+/**
+ * What a file property ACCEPTS: content, or a reference you already have.
+ *
+ * `Blob` covers `File`, which is what an `<input type="file">` yields. A reference is accepted
+ * too, so re-saving an entity that was read from the database does not have to re-upload it.
+ */
+export type FileContentValue = FileReferenceValue | Uint8Array | ArrayBuffer | Blob | string;
+/**
+ * What a vector property holds, in and out: a plain list of numbers.
+ *
+ * Named rather than written inline because the inference rules have to recognise it after a
+ * modifier has erased which class produced it — the same problem `FileReferenceValue` solves
+ * above, and for the same reason.
+ */
+export type VectorValue = number[];
+/**
+ * What `s.string({ ... })` accepts.
+ *
+ * Declarations only. Core stores them and never acts on them; a backend that can use one does.
+ */
+export type StringOptions = {
+    /**
+     * The longest value the property is declared to hold.
+     *
+     * MySQL uses it for `VARCHAR(maxLength)`; without it every string column is
+     * `VARCHAR(255)`, which silently truncates longer values. Other backends ignore it. Core
+     * never validates a value against it — see `SchemaBase.maxLength`.
+     */
+    maxLength?: number;
+};
 export type ExpandedProperty = ExpandedChildProperty & {
     assignmentPath: string;
     selectorPath: string;
@@ -99,7 +162,7 @@ export type Preprocess<TEntity extends {}> = {
     (entity: InferCreateType<TEntity>): InferType<TEntity>;
     (entity: InferType<TEntity>): InferType<TEntity>;
 };
-export type SetProperties<TEntity extends {}> = (destination: InferType<TEntity> | InferCreateType<TEntity>, source: InferType<TEntity> | InferCreateType<TEntity>) => void;
+export type SetProperties<TEntity extends {}> = (destination: DeepPartial<InferType<TEntity> | InferCreateType<TEntity>>, source: DeepPartial<InferType<TEntity> | InferCreateType<TEntity>>) => void;
 export type CompiledSchemaCore<TEntity extends {}> = Omit<CompiledSchema<TEntity>, "createSubscription">;
 export type CompiledSchemaWithMetadata<TEntity extends {}, TMetadata> = {
     readonly metadata: TMetadata;
@@ -109,13 +172,22 @@ export type CompiledSchemaWithMetadata<TEntity extends {}, TMetadata> = {
  */
 export type CompiledSchema<TEntity extends {}> = {
     deserializePartial: (item: Record<string, unknown>, properties: PropertyInfo<TEntity>[]) => DeepPartial<InferType<TEntity>>;
-    createSubscription: (abortSignal?: AbortSignal) => ISchemaSubscription<TEntity>;
+    createSubscription: (abortSignal?: AbortSignal, scope?: string, options?: SchemaSubscriptionOptions) => ISchemaSubscription<TEntity>;
     /** Returns the property info for a given id (full path) */
     getProperty: (id: string) => PropertyInfo<TEntity>;
     /** Returns the ID of the given entity. */
     getId: (entity: InferType<TEntity>) => IdType;
     /** Returns a deep clone of the given entity. */
     clone: (entity: InferType<TEntity>) => InferType<TEntity>;
+    /**
+     * Returns a deep clone of a record that is still in the STORAGE shape — renamed properties
+     * under their `from` names rather than their in-memory names.
+     *
+     * `clone` reads in-memory names, so it returns `undefined` for every renamed property of a
+     * stored record. Use this when copying rows a store holds before they have been deserialized.
+     * Generated on first call; schemas that are never cloned in storage shape never build it.
+     */
+    cloneStorage: (entity: InferType<TEntity>) => InferType<TEntity>;
     /** Removes unmapped or extraneous properties from the entity. */
     strip: (entity: InferType<TEntity>) => InferType<TEntity>;
     /** Prepares a new entity for creation, applying defaults and transformations. */
@@ -169,12 +241,79 @@ export type CompiledSchema<TEntity extends {}> = {
 };
 export type PropertySerializer<T extends any> = (value: T) => string | number;
 export type PropertyDeserializer<T extends any> = (value: string | number) => T;
+/**
+ * A two-way transform between the application value and the stored value.
+ *
+ * Both directions may be async. Held as a live reference rather than stringified, so a
+ * closure works and `injected` is a convenience rather than the only way in.
+ */
+export type PropertyTransform<T extends any> = {
+    /**
+     * Application value to stored value. Runs before the plugin sees it. May be async.
+     *
+     * `entity` is there for the one-way case: a transform with no `from` derives a value
+     * rather than converting one, which is what `computed` does.
+     */
+    to: (value: T, entity: Record<string, unknown>) => unknown | Promise<unknown>;
+    /**
+     * Stored value back to application value. Runs after the plugin returns it.
+     *
+     * Optional. Leave it out and the transform is one-way: the stored value is the value.
+     */
+    from?: (value: unknown) => T | Promise<T>;
+    /**
+     * What the column becomes, when the stored form is not the property's own type.
+     *
+     * Defaults to the property's own type, so nothing changes unless you say it does. A
+     * library that always produces text — a cipher, a compressor — sets this once, and the
+     * caller who uses that library never writes it.
+     */
+    stores?: SchemaTypes;
+    /**
+     * Whether a filter on this property can still run in the database.
+     *
+     * Defaults to `none`, which rejects the filter rather than returning wrong rows. Set
+     * `equality` only when `to` is deterministic.
+     */
+    comparable?: 'equality' | 'none';
+};
 export type SchemaId = Branded<number, "SchemaId">;
 export type CollectionName = Branded<string, "CollectionName">;
-export type SchemaModifiers = "default" | "deserialize" | "identity" | "key" | "nullable" | "optional" | "readonly" | "serialize" | "unmapped" | "computed" | "distinct";
-type InferPrimitive<T> = T extends SchemaOptional<infer C, infer __> ? C extends (string | number | Date) ? C : {
+export type SchemaModifiers = "default" | "deserialize" | "identity" | "key" | "nullable" | "optional" | "readonly" | "serialize" | "unmapped" | "computed" | "distinct" | "searchable";
+/**
+ * What a tagged property infers to.
+ *
+ * `tag()` is metadata and must not change a type, but `SchemaTag<T>` carries the same `T` as
+ * whatever it wrapped without carrying which class that was. For a string `T` is already
+ * `string`; for an object `T` is the map of child schemas, which only the `SchemaObject`
+ * branch below knows how to unwrap. Falling through to the generic `SchemaBase` branch
+ * therefore handed the raw map back, so `s.object({ key: s.string() }).tag('x')` typed
+ * `key` as `SchemaString` instead of `string` — everything ran, and only the types lied.
+ *
+ * An array is distinguishable because `SchemaArray`'s parameter is the ELEMENT schema, so a
+ * tagged array arrives here as a `SchemaBase` rather than a plain map.
+ */
+type InferTagged<C> = ResolveWrapped<C>;
+/**
+ * What a wrapping modifier's inner type resolves to.
+ *
+ * `SchemaOptional`, `SchemaNullable` and `SchemaTag` all carry the same `C` as whatever they
+ * wrapped, without carrying which class that was, so each has to work out what it is holding.
+ * Three shapes are possible:
+ *
+ * - an already-resolved value (`string` from `s.string()`, a file reference from `s.file()`)
+ * - an ELEMENT schema, which is what `SchemaArray` parameterises on
+ * - a map of child schemas, which is what `SchemaObject` parameterises on
+ *
+ * Getting this wrong is silent. The map branch applied to an already-resolved object walks
+ * its keys and infers `never` for each, so `s.file().optional()` typed as
+ * `{ key: never, size: never, ... }` — which no value can satisfy and no test would catch at
+ * runtime.
+ */
+type ResolveWrapped<C> = C extends string | number | boolean | Date | FileReferenceValue ? C : C extends VectorValue ? C : C extends SchemaBase<any, any> ? InferPrimitive<C>[] : {
     [K in keyof C]: InferPrimitive<C[K]>;
-} : T extends SchemaArray<infer Y, infer __> ? InferPrimitive<Y>[] : T extends SchemaObject<infer Obj, infer _> ? {
+};
+type InferPrimitive<T> = T extends SchemaOptional<infer C, infer __> ? ResolveWrapped<C> : T extends SchemaTag<infer C, infer __> ? InferTagged<C> : T extends SchemaVector<infer __, infer ___> ? VectorValue : T extends SchemaArray<infer Y, infer __> ? InferPrimitive<Y>[] : T extends SchemaObject<infer Obj, infer _> ? {
     [K in keyof Obj]: InferPrimitive<Obj[K]>;
 } : T extends SchemaFunction<infer F, infer __> ? F : T extends SchemaBase<infer X, infer _> ? X extends Array<infer A> ? InferPrimitive<A>[] : X : never;
 export type InferType<T> = T extends CompiledSchema<infer R> ? InferCompiledSchema<R> : T extends {} ? InferCompiledSchema<T> : T;
@@ -208,7 +347,26 @@ type IsCreateOptional<T, K extends keyof T> = [
     false
 ] ? false : true;
 type IsCreateNullable<T, K extends keyof T> = HasModifier<T, K, "nullable"> extends true ? true : false;
-type InferCreateProperty<T, K extends keyof T> = IsCreateNullable<T, K> extends true ? null | InferPrimitive<T[K]> : InferPrimitive<T[K]>;
+/**
+ * What a property ACCEPTS on the way in, which is not always what it gives back.
+ *
+ * Only a file differs today: you assign content and read a reference. Matching on the read
+ * type rather than on `SchemaFile` itself is deliberate — it keeps working through every
+ * modifier. `s.file().optional()` is a `SchemaOptional`, `s.file().tag('x')` is a
+ * `SchemaTag`, and neither carries the original class, so a check against the class alone
+ * would silently stop accepting content the moment anyone added a modifier.
+ *
+ * Assignability is required in BOTH directions, and the tuple wrappers are load-bearing.
+ * One-way `extends` matches `never` — which is assignable to everything — so a generic
+ * property over `Record<string, unknown>` resolved to file content and broke the Dexie
+ * plugin's types. It also matched any object that merely happens to have these five fields
+ * plus more. Mutual assignability admits the reference shape and nothing else, and the
+ * tuples stop the conditional distributing over a union.
+ */
+type InferWritePrimitive<T> = [
+    InferPrimitive<T>
+] extends [FileReferenceValue] ? [FileReferenceValue] extends [InferPrimitive<T>] ? FileContentValue : InferPrimitive<T> : InferPrimitive<T>;
+type InferCreateProperty<T, K extends keyof T> = IsCreateNullable<T, K> extends true ? null | InferWritePrimitive<T[K]> : InferWritePrimitive<T[K]>;
 type InferCompiledSchema<T> = CoalesceEmpty<{
     [K in keyof T as IsPlainProperty<T, K> extends true ? K : never]: InferPrimitive<T[K]>;
 }, {

package/dist/schema/utils/propertyKind.d.ts

@@ -0,0 +1,4 @@
+import { SchemaTypes } from "../types";
+/** True when the property's value is a JS array and needs value rather than reference semantics. */
+export declare const isArrayValued: (type: SchemaTypes) => boolean;
+export declare const hasPrimitiveElements: (type: SchemaTypes, elementType: SchemaTypes | undefined) => boolean;

package/dist/types/index.cjs

@@ -0,0 +1,23 @@
+(() => {
+"use strict";
+// The require scope
+var __webpack_require__ = {};
+
+// webpack/runtime/make_namespace_object
+(() => {
+// define __esModule on exports
+__webpack_require__.r = (exports) => {
+	if(typeof Symbol !== 'undefined' && Symbol.toStringTag) {
+		Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+	}
+	Object.defineProperty(exports, '__esModule', { value: true });
+};
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+
+
+module.exports = __webpack_exports__;
+})()
+;
+//# sourceMappingURL=index.cjs.map

package/dist/types/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types/index.cjs","sources":["webpack://@routier/core/webpack/runtime/make_namespace_object","webpack://@routier/core/./src/types/index.ts"],"sourcesContent":["// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};","export type DeepPartial<T> = T extends object ? {\n    [P in keyof T]?: DeepPartial<T[P]>;\n} : T;\n\nexport type GenericFunction<T, R> = (value: T) => R;"],"names":[],"mappings":";;;;;;;AAAA;AACA;AACA;AACA,uDAAuD,iBAAiB;AACxE;AACA,gDAAgD,aAAa;AAC7D,E;;;;ACFoD"}