@relations-dil/relations 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * relations - a simple, flexible DIL (data interface layer).
+ *
+ * Define a model once, independent of any backend. Point it at a source at runtime. The
+ * same model description drives a database in one service and a REST API in the next.
+ *
+ * ```ts
+ * import { Model, OneToMany, int, str } from '@relations-dil/relations'
+ * import { MockSource } from '@relations-dil/relations/mock'
+ *
+ * class Base extends Model {
+ *   static source = 'example'
+ * }
+ *
+ * class Unit extends Base {
+ *   static fields = { id: int, name: str }
+ * }
+ *
+ * class Test extends Base {
+ *   static fields = { id: int, unit_id: int, name: str }
+ * }
+ *
+ * new OneToMany(Unit, Test)
+ * new MockSource('example')
+ *
+ * await new Unit('yep').create()
+ *
+ * const unit = await Unit.one({ name: 'yep' }).retrieve()
+ * unit.id  // 1
+ * ```
+ */
+import * as overscore from './overscore.js';
+export { overscore };
+export { FieldError, MigrationsError, ModelError, RecordError, UniqueError } from './errors.js';
+export { OverscoreError } from './overscore.js';
+export { bool, builtin, container, dict, float, int, kindName, kindOf, list, scalar, set, str, CONTAINERS, KINDS, SCALARS, type FieldKind, type Kind, type KindClass } from './kinds.js';
+export { Field, OPERATORS, RESERVED, type Attr, type FieldOptions, type Init, type Validation } from './field.js';
+export { Record, type Action } from './record.js';
+export { Model, ModelIdentity, construct, toField, type FieldSpec, type ModelAction, type ModelClass, type ModelMode, type ModelRole } from './model.js';
+export { ManyToMany, OneTo, OneToMany, OneToOne, Relation, type ManyToManyOptions, type OneToOptions } from './relation.js';
+export { Source, lookup, type Query } from './source.js';
+export { Titles } from './titles.js';
+export { Migrations, pretty, type Renamer } from './migrations.js';
+export { MockQuery, MockSource } from './mock.js';
+export { fields, type Listed, type Typed, type TypedClass, type ValueOfKind, type ValueOfSpec, type Values } from './typed.js';
+export { definitionsOf, modelFrom, modelsFrom, type Built, type Definition, type RelationDefinition } from './dynamic.js';
+export { SOURCES, clear, register, source, unregister, type Registered } from './registry.js';
+import type { ModelClass } from './model.js';
+/**
+ * Every model class exported by a module, for handing to migrations.
+ *
+ * ```ts
+ * import * as schema from './models.js'
+ *
+ * await new Migrations('ddl').generate(models(schema))
+ * ```
+ */
+export declare function models(module: globalThis.Record<string, any>, fromBase?: any): ModelClass[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,75 @@
+/**
+ * relations - a simple, flexible DIL (data interface layer).
+ *
+ * Define a model once, independent of any backend. Point it at a source at runtime. The
+ * same model description drives a database in one service and a REST API in the next.
+ *
+ * ```ts
+ * import { Model, OneToMany, int, str } from '@relations-dil/relations'
+ * import { MockSource } from '@relations-dil/relations/mock'
+ *
+ * class Base extends Model {
+ *   static source = 'example'
+ * }
+ *
+ * class Unit extends Base {
+ *   static fields = { id: int, name: str }
+ * }
+ *
+ * class Test extends Base {
+ *   static fields = { id: int, unit_id: int, name: str }
+ * }
+ *
+ * new OneToMany(Unit, Test)
+ * new MockSource('example')
+ *
+ * await new Unit('yep').create()
+ *
+ * const unit = await Unit.one({ name: 'yep' }).retrieve()
+ * unit.id  // 1
+ * ```
+ */
+import * as overscore from './overscore.js';
+export { overscore };
+export { FieldError, MigrationsError, ModelError, RecordError, UniqueError } from './errors.js';
+export { OverscoreError } from './overscore.js';
+export { bool, builtin, container, dict, float, int, kindName, kindOf, list, scalar, set, str, CONTAINERS, KINDS, SCALARS } from './kinds.js';
+export { Field, OPERATORS, RESERVED } from './field.js';
+export { Record } from './record.js';
+export { Model, ModelIdentity, construct, toField } from './model.js';
+export { ManyToMany, OneTo, OneToMany, OneToOne, Relation } from './relation.js';
+export { Source, lookup } from './source.js';
+export { Titles } from './titles.js';
+export { Migrations, pretty } from './migrations.js';
+export { MockQuery, MockSource } from './mock.js';
+export { fields } from './typed.js';
+export { definitionsOf, modelFrom, modelsFrom } from './dynamic.js';
+export { SOURCES, clear, register, source, unregister } from './registry.js';
+import { Model as ModelBase } from './model.js';
+/**
+ * Every model class exported by a module, for handing to migrations.
+ *
+ * ```ts
+ * import * as schema from './models.js'
+ *
+ * await new Migrations('ddl').generate(models(schema))
+ * ```
+ */
+export function models(module, fromBase = ModelBase) {
+    const found = [];
+    for (const value of Object.values(module)) {
+        if (typeof value !== 'function' || value === fromBase) {
+            continue;
+        }
+        let prototype = Object.getPrototypeOf(value);
+        while (prototype) {
+            if (prototype === fromBase) {
+                found.push(value);
+                break;
+            }
+            prototype = Object.getPrototypeOf(prototype);
+        }
+    }
+    return found;
+}
+//# sourceMappingURL=index.js.map

package/dist/kinds.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Field kinds.
+ *
+ * Python has `int`, `str`, `dict` and friends as first class values you can hand to a
+ * field. JavaScript doesn't, so relations exports the same seven names as sentinels:
+ *
+ * ```ts
+ * import { Model, int, str, list } from '@relations-dil/relations'
+ *
+ * class Unit extends Model {
+ *   static source = 'example'
+ *   static fields = { id: int, name: str, tags: list }
+ * }
+ * ```
+ *
+ * A field can also take a class constructor as its kind, in which case the field needs
+ * `attr` to say how to flatten instances into storable values.
+ */
+/** One of the seven built-in kinds. */
+export interface Kind {
+    /** Name used in definitions and migrations. */
+    readonly name: 'bool' | 'int' | 'float' | 'str' | 'set' | 'list' | 'dict';
+    /** Whether a value is already of this kind. */
+    check(value: unknown): boolean;
+    /** Coerce a value to this kind, throwing when it can't be done. */
+    cast(value: unknown): any;
+    /** A fresh empty value, for the container kinds. */
+    empty(): any;
+}
+/** A class usable as a field kind. Such a field must also declare `attr`. */
+export type KindClass = abstract new (...args: any[]) => any;
+/** Anything acceptable as a field's kind. */
+export type FieldKind = Kind | KindClass;
+/** Boolean. Casts the strings `false`, `no` and `0` to `false`, everything else by truthiness. */
+export declare const bool: Readonly<{
+    name: "bool";
+    check: (value: unknown) => value is boolean;
+    cast(value: unknown): boolean;
+    empty: () => false;
+}>;
+/** Whole number. Truncates toward zero, the way Python's `int()` does. */
+export declare const int: Readonly<{
+    name: "int";
+    check: (value: unknown) => boolean;
+    cast(value: unknown): number;
+    empty: () => 0;
+}>;
+/** Number, whole or not. */
+export declare const float: Readonly<{
+    name: "float";
+    check: (value: unknown) => boolean;
+    cast(value: unknown): number;
+    empty: () => 0;
+}>;
+/** String. */
+export declare const str: Readonly<{
+    name: "str";
+    check: (value: unknown) => value is string;
+    cast(value: unknown): string;
+    empty: () => "";
+}>;
+/** A `Set`. Exports as a sorted array (or in `options` order when options are set). */
+export declare const set: Readonly<{
+    name: "set";
+    check: (value: unknown) => value is Set<any>;
+    cast(value: unknown): Set<any>;
+    empty: () => Set<unknown>;
+}>;
+/** An array. */
+export declare const list: Readonly<{
+    name: "list";
+    check: (value: unknown) => value is any[];
+    cast(value: unknown): any[];
+    empty: () => never[];
+}>;
+/** A plain object. */
+export declare const dict: Readonly<{
+    name: "dict";
+    check: (value: unknown) => value is Record<string, unknown>;
+    cast(value: unknown): any;
+    empty: () => {};
+}>;
+/** All built-in kinds, keyed by name. */
+export declare const KINDS: Record<string, Kind>;
+/** The kinds that hold a single scalar value, with no interior path to reach into. */
+export declare const SCALARS: Kind[];
+/** The kinds that hold other values. */
+export declare const CONTAINERS: Kind[];
+/** Whether `kind` is one of the seven built-ins rather than a class. */
+export declare function builtin(kind: FieldKind): kind is Kind;
+/** The name of a kind, whether built-in or a class. */
+export declare function kindName(kind: FieldKind): string;
+/** Whether `kind` is a scalar built-in. */
+export declare function scalar(kind: FieldKind): boolean;
+/** Whether `kind` is a container built-in. */
+export declare function container(kind: FieldKind): boolean;
+/** Look a built-in kind up by name, for reading back definitions. */
+export declare function kindOf(name: string): Kind | undefined;
+//# sourceMappingURL=kinds.d.ts.map

package/dist/kinds.js

@@ -0,0 +1,169 @@
+/**
+ * Field kinds.
+ *
+ * Python has `int`, `str`, `dict` and friends as first class values you can hand to a
+ * field. JavaScript doesn't, so relations exports the same seven names as sentinels:
+ *
+ * ```ts
+ * import { Model, int, str, list } from '@relations-dil/relations'
+ *
+ * class Unit extends Model {
+ *   static source = 'example'
+ *   static fields = { id: int, name: str, tags: list }
+ * }
+ * ```
+ *
+ * A field can also take a class constructor as its kind, in which case the field needs
+ * `attr` to say how to flatten instances into storable values.
+ */
+import { sorted } from './util.js';
+import { isDict } from './overscore.js';
+class CastError extends Error {
+}
+function fail(value, kind) {
+    throw new CastError(`cannot cast ${JSON.stringify(value) ?? String(value)} to ${kind}`);
+}
+/** Boolean. Casts the strings `false`, `no` and `0` to `false`, everything else by truthiness. */
+export const bool = Object.freeze({
+    name: 'bool',
+    check: (value) => typeof value === 'boolean',
+    cast(value) {
+        if (typeof value === 'string') {
+            const lowered = value.toLowerCase();
+            if (['false', 'no', '0', ''].includes(lowered)) {
+                return false;
+            }
+            return true;
+        }
+        return Boolean(value);
+    },
+    empty: () => false
+});
+/** Whole number. Truncates toward zero, the way Python's `int()` does. */
+export const int = Object.freeze({
+    name: 'int',
+    check: (value) => typeof value === 'number' && Number.isInteger(value),
+    cast(value) {
+        if (typeof value === 'boolean') {
+            return Number(value);
+        }
+        const number = Number(value);
+        if (typeof value === 'object' || value === '' || !Number.isFinite(number)) {
+            fail(value, 'int');
+        }
+        return Math.trunc(number);
+    },
+    empty: () => 0
+});
+/** Number, whole or not. */
+export const float = Object.freeze({
+    name: 'float',
+    check: (value) => typeof value === 'number' && Number.isFinite(value),
+    cast(value) {
+        if (typeof value === 'boolean') {
+            return Number(value);
+        }
+        const number = Number(value);
+        if (typeof value === 'object' || value === '' || !Number.isFinite(number)) {
+            fail(value, 'float');
+        }
+        return number;
+    },
+    empty: () => 0
+});
+/** String. */
+export const str = Object.freeze({
+    name: 'str',
+    check: (value) => typeof value === 'string',
+    cast(value) {
+        if (value === null || value === undefined) {
+            fail(value, 'str');
+        }
+        if (typeof value === 'object') {
+            return JSON.stringify(value);
+        }
+        return String(value);
+    },
+    empty: () => ''
+});
+/** A `Set`. Exports as a sorted array (or in `options` order when options are set). */
+export const set = Object.freeze({
+    name: 'set',
+    check: (value) => value instanceof Set,
+    cast(value) {
+        if (value instanceof Set) {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            return new Set(value);
+        }
+        if (typeof value === 'string') {
+            return new Set([value]);
+        }
+        if (value && typeof value[Symbol.iterator] === 'function') {
+            return new Set(value);
+        }
+        return fail(value, 'set');
+    },
+    empty: () => new Set()
+});
+/** An array. */
+export const list = Object.freeze({
+    name: 'list',
+    check: (value) => Array.isArray(value),
+    cast(value) {
+        if (Array.isArray(value)) {
+            return value;
+        }
+        if (value instanceof Set) {
+            return sorted(value);
+        }
+        if (value && typeof value === 'object' && typeof value[Symbol.iterator] === 'function') {
+            return [...value];
+        }
+        return fail(value, 'list');
+    },
+    empty: () => []
+});
+/** A plain object. */
+export const dict = Object.freeze({
+    name: 'dict',
+    check: (value) => isDict(value),
+    cast(value) {
+        if (isDict(value)) {
+            return value;
+        }
+        if (value instanceof Map) {
+            return Object.fromEntries(value);
+        }
+        return fail(value, 'dict');
+    },
+    empty: () => ({})
+});
+/** All built-in kinds, keyed by name. */
+export const KINDS = Object.freeze({ bool, int, float, str, set, list, dict });
+/** The kinds that hold a single scalar value, with no interior path to reach into. */
+export const SCALARS = [bool, int, float, str];
+/** The kinds that hold other values. */
+export const CONTAINERS = [set, list, dict];
+/** Whether `kind` is one of the seven built-ins rather than a class. */
+export function builtin(kind) {
+    return typeof kind === 'object' && kind !== null && 'check' in kind && 'cast' in kind;
+}
+/** The name of a kind, whether built-in or a class. */
+export function kindName(kind) {
+    return builtin(kind) ? kind.name : kind.name || 'object';
+}
+/** Whether `kind` is a scalar built-in. */
+export function scalar(kind) {
+    return builtin(kind) && SCALARS.includes(kind);
+}
+/** Whether `kind` is a container built-in. */
+export function container(kind) {
+    return builtin(kind) && CONTAINERS.includes(kind);
+}
+/** Look a built-in kind up by name, for reading back definitions. */
+export function kindOf(name) {
+    return KINDS[name];
+}
+//# sourceMappingURL=kinds.js.map

package/dist/migrations.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Migrations: diffing model definitions over time, and handing the diffs to a source.
+ *
+ * Definitions are backend-neutral JSON. A source converts them into whatever it needs -
+ * DDL for a database, nothing at all for an API - so the same migration history drives
+ * every backend a set of models is used with.
+ */
+import { type ModelClass } from './model.js';
+/**
+ * Decides which removals are actually renames. Called with the kind of thing being
+ * renamed and the names added and removed; returns removed-name to added-name pairs.
+ *
+ * Python's relations prompts on stdin here. This takes a function instead, so the same
+ * code works in a script, a test, or a CLI you write yourself.
+ */
+export type Renamer = (name: string, adds: string[], removes: string[]) => globalThis.Record<string, string>;
+/** Diffs model definitions and drives a source through the resulting changes. */
+export declare class Migrations {
+    /** Directory the definition and migration files live in. */
+    directory: string;
+    /** How renames are decided. Defaults to treating nothing as a rename. */
+    renamer: Renamer;
+    constructor(directory?: string, options?: {
+        renamer?: Renamer;
+    });
+    /** The definition as of the last generate, or an empty one. */
+    current(): Promise<globalThis.Record<string, any>>;
+    /** Definitions for a set of model classes, keyed by model name. */
+    static define(models: ModelClass[]): globalThis.Record<string, any>;
+    /** Work out which removals are renames, and take those out of adds and removes. */
+    static rename(renamer: Renamer, name: string, adds: string[], removes: string[]): globalThis.Record<string, string>;
+    /** A field definition by name. */
+    static lookup(name: string, fields: globalThis.Record<string, any>[]): globalThis.Record<string, any> | null;
+    /** What changed between two field definitions. */
+    static field(current: globalThis.Record<string, any>, define: globalThis.Record<string, any>): globalThis.Record<string, any>;
+    /** What changed between two sets of field definitions. */
+    static fields(renamer: Renamer, model: string, current: globalThis.Record<string, any>[], define: globalThis.Record<string, any>[]): globalThis.Record<string, any>;
+    /** What changed between two sets of indexes. */
+    static indexes(renamer: Renamer, model: string, kind: string, current: globalThis.Record<string, string[]>, define: globalThis.Record<string, string[]>): globalThis.Record<string, any>;
+    /** What changed between two model definitions. */
+    static model(current: globalThis.Record<string, any>, define: globalThis.Record<string, any>, renamer?: Renamer): globalThis.Record<string, any>;
+    /** What changed across a whole set of models. */
+    static models(current: globalThis.Record<string, any>, define: globalThis.Record<string, any>, renamer?: Renamer): globalThis.Record<string, any>;
+    /**
+     * Snapshot the current models, writing a migration alongside the previous snapshot.
+     * Resolves to whether anything was written.
+     */
+    generate(models: ModelClass[], stamp?: string): Promise<boolean>;
+    /** Where a source's converted files live. */
+    sourcePath(name: string): string;
+    /** Convert every definition and migration into a source's own form. */
+    convert(name: string): Promise<void>;
+    /** The migration pairs available for a source. */
+    list(name: string): Promise<globalThis.Record<string, any>>;
+    /** Load one converted file into a source. */
+    load(name: string, fileName: string): Promise<void>;
+    /** Bring a source up to date. Resolves to whether anything was applied. */
+    apply(name: string): Promise<boolean>;
+}
+/** Sorted-key JSON, so definitions diff cleanly in version control. */
+export declare function pretty(value: any): string;
+//# sourceMappingURL=migrations.d.ts.map