@relations-dil/relations 0.2.1 → 0.2.2

package/README.md

@@ -335,6 +335,17 @@ static fields = {
 }
 ```
 
+A relation can do the injecting for you, so a shared model can take on an optional parent
+without being edited or getting a column of its own. Name the dict field to store it in:
+
+```ts
+new OneToMany(Unum, Entity, { childInject: 'what' })
+// adds entity.unum_id, stored at what.relations.unum.id; entity.unum is null when there isn't one
+```
+
+The key is named `<model>_<id>`, or `<parent source>_<model>_<id>` when the parent lives in a
+different source, which has to be a dns label (letters, digits and hyphens).
+
 ---
 
 ## Querying

package/dist/errors.d.ts

@@ -24,6 +24,10 @@ export declare class ModelError extends Error {
 export declare class UniqueError extends ModelError {
     constructor(model: any, message: string);
 }
+/** A source can't be registered, usually because its name isn't a dns label. */
+export declare class SourceError extends Error {
+    constructor(message: string);
+}
 /** Something went wrong diffing or applying migrations. */
 export declare class MigrationsError extends Error {
     constructor(message: string);

package/dist/errors.js

@@ -40,6 +40,13 @@ export class UniqueError extends ModelError {
         this.name = 'UniqueError';
     }
 }
+/** A source can't be registered, usually because its name isn't a dns label. */
+export class SourceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SourceError';
+    }
+}
 /** Something went wrong diffing or applying migrations. */
 export class MigrationsError extends Error {
     constructor(message) {

package/dist/field.js

@@ -491,7 +491,23 @@ export class Field {
     write(values) {
         const value = this.export();
         if (this.inject) {
-            overscore.set(values, this.inject.split('__').slice(1).join('__'), value);
+            const path = this.inject.split('__').slice(1).join('__');
+            if (value === null || value === undefined) {
+                // A null isn't stored when it's only dict keys: a missing key reads back as null,
+                // and storage has no nulls to trip over.
+                const keys = overscore.parse(path);
+                let container = values;
+                for (const key of keys.slice(0, -1)) {
+                    container =
+                        overscore.isDict(container) && typeof key === 'string' ? (key in container ? container[key] : {}) : null;
+                }
+                const last = keys[keys.length - 1];
+                if (overscore.isDict(container) && typeof last === 'string') {
+                    delete container[last];
+                    return;
+                }
+            }
+            overscore.set(values, path, value);
         }
         else if (this.store) {
             values[this.store] = value;

package/dist/index.d.ts

@@ -31,7 +31,7 @@
  */
 import * as overscore from './overscore.js';
 export { overscore };
-export { FieldError, MigrationsError, ModelError, RecordError, UniqueError } from './errors.js';
+export { FieldError, MigrationsError, ModelError, RecordError, SourceError, 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';
@@ -46,7 +46,7 @@ export { LocalSource, type StorageLike } from './local.js';
 export { RestSource, type FetchInit, type FetchLike, type FetchResponse } from './rest.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';
+export { DNS, 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.

package/dist/index.js

@@ -31,7 +31,7 @@
  */
 import * as overscore from './overscore.js';
 export { overscore };
-export { FieldError, MigrationsError, ModelError, RecordError, UniqueError } from './errors.js';
+export { FieldError, MigrationsError, ModelError, RecordError, SourceError, 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';
@@ -46,7 +46,7 @@ export { LocalSource } from './local.js';
 export { RestSource } from './rest.js';
 export { fields } from './typed.js';
 export { definitionsOf, modelFrom, modelsFrom } from './dynamic.js';
-export { SOURCES, clear, register, source, unregister } from './registry.js';
+export { DNS, 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.

package/dist/model.js

@@ -545,12 +545,17 @@ export class Model extends ModelIdentity {
         if (name in this.PARENTS) {
             const relation = this.PARENTS[name];
             if (!this._parents[name]) {
-                this._parents[name] =
-                    this._action === 'retrieve'
-                        ? relation.Parent.many().limit(this._chunk)
-                        : construct(relation.Parent, {
-                            child: { [relation.parentId]: this._item(relation.childParentRef) }
-                        });
+                if (this._action === 'retrieve') {
+                    this._parents[name] = relation.Parent.many().limit(this._chunk);
+                }
+                else if (this._item(relation.childParentRef) === null) {
+                    return null; // No key means no parent, nothing to cache
+                }
+                else {
+                    this._parents[name] = construct(relation.Parent, {
+                        child: { [relation.parentId]: this._item(relation.childParentRef) }
+                    });
+                }
             }
             return this._parents[name];
         }

package/dist/record.js

@@ -161,7 +161,14 @@ export class Record {
     /** Whether a stored record satisfies every field's criteria. */
     retrieve(values) {
         for (const field of this._order) {
-            if (!field.retrieve(values)) {
+            if (field.inject) {
+                // An injected field is checked where it's stored, in the field it lives inside.
+                const injected = overscore.get(values[this.injected(field)] ?? {}, field.inject.split('__').slice(1).join('__'));
+                if (!field.retrieve({ [field.store]: injected })) {
+                    return false;
+                }
+            }
+            else if (!field.retrieve(values)) {
                 return false;
             }
         }

package/dist/registry.d.ts

@@ -6,6 +6,11 @@
  * the whole point of relations: the same model runs against a database in one service
  * and against a REST API in another.
  */
+/**
+ * A dns label, which is what a source's name has to be so it's safe to use in other names:
+ * letters, digits and hyphens, 1 to 63 characters, no leading or trailing hyphen.
+ */
+export declare const DNS: RegExp;
 /** Anything registered as a source. Kept loose to avoid a circular import. */
 export interface Registered {
     name: string;
@@ -13,7 +18,7 @@ export interface Registered {
 }
 /** Every registered source, keyed by name. */
 export declare const SOURCES: Map<string, Registered>;
-/** Register a source under its name, replacing any source already there. */
+/** Register a source under its name, replacing any source already there. The name has to be a dns label. */
 export declare function register(source: Registered): void;
 /** The source registered under a name, or `undefined`. */
 export declare function source(name: string | null | undefined): Registered | undefined;

package/dist/registry.js

@@ -6,10 +6,19 @@
  * the whole point of relations: the same model runs against a database in one service
  * and against a REST API in another.
  */
+import { SourceError } from './errors.js';
+/**
+ * A dns label, which is what a source's name has to be so it's safe to use in other names:
+ * letters, digits and hyphens, 1 to 63 characters, no leading or trailing hyphen.
+ */
+export const DNS = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/i;
 /** Every registered source, keyed by name. */
 export const SOURCES = new Map();
-/** Register a source under its name, replacing any source already there. */
+/** Register a source under its name, replacing any source already there. The name has to be a dns label. */
 export function register(source) {
+    if (typeof source.name !== 'string' || !DNS.test(source.name)) {
+        throw new SourceError(`source ${source.name} is not dns compliant`);
+    }
     SOURCES.set(source.name, source);
 }
 /** The source registered under a name, or `undefined`. */

package/dist/relation.d.ts

@@ -32,6 +32,11 @@ export interface OneToOptions {
     parentId?: string | number;
     /** Field on the child that points at the parent. Inferred by convention. */
     childParentRef?: string | number;
+    /**
+     * A dict field on the child to store the parent id in, so the child needs no field of its own
+     * for it. The relation adds that field, at `<childInject>__relations__<parent>__<id>`.
+     */
+    childInject?: string;
 }
 /** One parent record to one or many child records. */
 export declare class OneTo extends Relation {
@@ -49,6 +54,8 @@ export declare class OneTo extends Relation {
     childParentRef: string;
     /** Attribute on the child that reaches the parent. */
     childParentAttr: string;
+    /** The dict field in the child the parent id is stored in, if it's not a field of its own. */
+    childInject: string | null;
     /** Whether the child side holds one record or many. */
     MODE: 'one' | 'many';
     constructor(Parent: ModelClass, Child: ModelClass, options?: OneToOptions);

package/dist/relation.js

@@ -12,6 +12,9 @@
  * ```
  */
 import { ModelError } from './errors.js';
+import { Field } from './field.js';
+import { dict } from './kinds.js';
+import { DNS } from './registry.js';
 /** Base for every relation, holding the convention used to find the joining field. */
 export class Relation {
     /** Whether the two sides can share an id field name. */
@@ -55,6 +58,8 @@ export class OneTo extends Relation {
     childParentRef;
     /** Attribute on the child that reaches the parent. */
     childParentAttr;
+    /** The dict field in the child the parent id is stored in, if it's not a field of its own. */
+    childInject;
     /** Whether the child side holds one record or many. */
     MODE;
     constructor(Parent, Child, options = {}) {
@@ -63,14 +68,48 @@ export class OneTo extends Relation {
         this.Parent = Parent;
         this.Child = Child;
         this.MODE = kind.MODE;
+        this.childInject = options.childInject ?? null;
         const parent = Parent.thy();
-        const child = Child.thy();
+        let child = Child.thy();
         this.parentId = parent._fieldName(options.parentId ?? parent._id);
         this.parentChildAttr = options.parentChildAttr ?? child.NAME;
+        let childParentRef = options.childParentRef;
+        // If asked, add the child field for the parent id, stored in a dict field of the child.
+        if (this.childInject !== null) {
+            const stored = child._fields._names.get(this.childInject);
+            if (stored === undefined) {
+                throw new ModelError(child, `cannot find field ${this.childInject} in ${child.NAME}`);
+            }
+            if (stored.kind !== dict) {
+                throw new ModelError(child, `field ${this.childInject} not a dict in ${child.NAME}`);
+            }
+            // Same source is just the model name, else prefix the source of the parent (a dns label).
+            let named = parent.NAME;
+            if (parent.SOURCE !== child.SOURCE) {
+                if (typeof parent.SOURCE !== 'string' || !DNS.test(parent.SOURCE)) {
+                    throw new ModelError(parent, `source ${parent.SOURCE} is not dns compliant`);
+                }
+                named = `${parent.SOURCE.toLowerCase().replace(/-/g, '_')}_${parent.NAME}`;
+            }
+            const ref = childParentRef !== undefined ? String(childParentRef) : `${named}_${this.parentId}`;
+            if (child._fields.has(ref)) {
+                throw new ModelError(child, `field ${ref} already exists in ${child.NAME}`);
+            }
+            const kindOfParent = parent._fields._names.get(this.parentId).kind;
+            Child.fields = {
+                ...Child.fields,
+                [ref]: new Field(kindOfParent, {
+                    inject: `${this.childInject}__relations__${named}__${this.parentId}`,
+                    none: true
+                })
+            };
+            childParentRef = ref;
+            child = Child.thy();
+        }
         this.childParentAttr = options.childParentAttr ?? parent.NAME;
         this.childParentRef =
-            options.childParentRef !== undefined
-                ? child._fieldName(options.childParentRef)
+            childParentRef !== undefined
+                ? child._fieldName(childParentRef)
                 : Relation.relativeField(parent, child, kind.SAME);
         this.Parent._child(this);
         this.Child._parent(this);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relations-dil/relations",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "A simple, flexible DIL (data interface layer). Define models once, independent of backend; set the source at runtime.",
   "license": "MIT",
   "repository": {