@dxos/echo 0.8.4-main.d05539e30a → 0.8.4-main.d9fc60f731

package/dist/types/src/Tag.d.ts

@@ -1,4 +1,6 @@
 import * as Schema from 'effect/Schema';
+import type { ForeignKey } from '@dxos/echo-protocol';
+import type * as Database from './Database';
 import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Type from './Type';
@@ -6,13 +8,27 @@ export declare const Tag: Type.Obj<{
     readonly label: string;
     readonly hue?: string | undefined;
 }, Schema.Struct.Fields>;
-export type Tag = Schema.Schema.Type<typeof Tag>;
-export declare const make: (props: Obj.MakeProps<typeof Tag>) => Obj.OfShape<import("./Entity").OfKind<internal.EntityKind.Object> & {
+export type Tag = Type.InstanceType<typeof Tag>;
+export declare const make: (props: Obj.MakeProps<typeof Tag>) => Obj.OfShape<{
     readonly label: string;
     readonly hue?: string | undefined;
-}>;
+} & import("./Entity").OfKind<internal.EntityKind.Object>>;
 export type Map = Record<string, Tag>;
 export declare const sortTags: ({ label: a }: Tag, { label: b }: Tag) => number;
 export declare const createTagList: (tags: Map) => Tag[];
 export declare const findTagByLabel: (tags: Map | undefined, name: string) => Tag | undefined;
+/**
+ * Finds or creates a {@link Tag} object in the database.
+ *
+ * - With a foreign `key` (system/provider tags): matched by that key; the label is kept current on
+ *   re-sync. Use a stable key (e.g. `{ source: 'google.com/gmail/label', id }`) for tags whose
+ *   identity is external or well-known.
+ * - Without a key (user tags): matched by case-insensitive label among tags that carry **no**
+ *   foreign key, so it never collides with a keyed system/provider tag of the same label.
+ */
+export declare const findOrCreate: (db: Pick<Database.Database, 'query' | 'add'>, options: {
+    label: string;
+    hue?: string;
+    key?: ForeignKey;
+}) => Promise<Tag>;
 //# sourceMappingURL=Tag.d.ts.map

package/dist/types/src/Tag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tag.d.ts","sourceRoot":"","sources":["../../../src/Tag.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B,eAAO,MAAM,GAAG;;;wBAUf,CAAC;AAEF,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;AAEjD,eAAO,MAAM,IAAI,UAAW,GAAG,CAAC,SAAS,CAAC,OAAO,GAAG,CAAC;;;EAAyB,CAAC;AAE/E,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEtC,eAAO,MAAM,QAAQ,iBAAkB,GAAG,gBAAgB,GAAG,WAAuB,CAAC;AAErF,eAAO,MAAM,aAAa,SAAU,GAAG,KAAG,GAAG,EAG1B,CAAC;AAEpB,eAAO,MAAM,cAAc,SAAU,GAAG,GAAG,SAAS,QAAQ,MAAM,KAAG,GAAG,GAAG,SAG1E,CAAC"}
+{"version":3,"file":"Tag.d.ts","sourceRoot":"","sources":["../../../src/Tag.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,KAAK,QAAQ,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B,eAAO,MAAM,GAAG;;;wBAQf,CAAC;AAEF,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,GAAG,CAAC,CAAC;AAEhD,eAAO,MAAM,IAAI,UAAW,GAAG,CAAC,SAAS,CAAC,OAAO,GAAG,CAAC;;;0DAAyB,CAAC;AAE/E,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEtC,eAAO,MAAM,QAAQ,iBAAkB,GAAG,gBAAgB,GAAG,WAAuB,CAAC;AAErF,eAAO,MAAM,aAAa,SAAU,GAAG,KAAG,GAAG,EAG1B,CAAC;AAEpB,eAAO,MAAM,cAAc,SAAU,GAAG,GAAG,SAAS,QAAQ,MAAM,KAAG,GAAG,GAAG,SAG1E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,OACnB,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC,WACnC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,UAAU,CAAA;CAAE,KACzD,OAAO,CAAC,GAAG,CA2Bb,CAAC"}

package/dist/types/src/TagIndex.d.ts

@@ -0,0 +1,36 @@
+import * as Schema from 'effect/Schema';
+import * as Obj from './Obj';
+/**
+ * An inverse tag index: an in-document `Record<tagId, objectId[]>` mapping a tag id to the ids of
+ * the objects carrying that tag.
+ *
+ * Mutable database objects track their tags in `Obj.getMeta(obj).tags` (an array of tag ids).
+ * Immutable feed/queue objects cannot carry their own meta, so this index — managed alongside the
+ * feed on its host object — augments that same process for them. Tags are sparse, so keying by tag
+ * id (rather than object id) keeps the index small and makes "filter the feed by tag" a single
+ * lookup.
+ *
+ * The tag id is an existing {@link Tag} object's id/URI; labels are never duplicated here — they
+ * live on the {@link Tag} object and stay editable in one place.
+ */
+/** Read/write accessor over a host object's tag-index field, bound to a single field key. */
+export interface Accessor {
+    /** All tag ids present in the index. */
+    tagIds(): string[];
+    /** Object ids carrying the given tag; `[]` when the tag is absent (filter the feed by tag). */
+    objects(tagId: string): readonly string[];
+    /** Inverse lookup: the tag ids applied to the given object id. */
+    tags(objectId: string): string[];
+    /** Applies a tag to an object (creating the tag entry when absent); idempotent. */
+    setTag(tagId: string, objectId: string): void;
+    /** Removes a tag from an object, pruning the tag entry when it empties. */
+    unsetTag(tagId: string, objectId: string): void;
+}
+/**
+ * Schema fragment for a tag-index field. Splice into a host Struct. Optional record, hidden from
+ * forms. Keyed by tag id; the value is the array of object ids carrying that tag.
+ */
+export declare const field: () => Schema.optional<Schema.Record$<typeof Schema.String, Schema.Array$<import("@dxos/keys").EntityIdClass>>>;
+/** Binds an {@link Accessor} over `host[key]`; all mutations go through `Obj.update`. */
+export declare const bind: (host: Obj.Any, key: string) => Accessor;
+//# sourceMappingURL=TagIndex.d.ts.map

package/dist/types/src/TagIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TagIndex.d.ts","sourceRoot":"","sources":["../../../src/TagIndex.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;;;;;;;;;GAYG;AAEH,6FAA6F;AAC7F,MAAM,WAAW,QAAQ;IACvB,wCAAwC;IACxC,MAAM,IAAI,MAAM,EAAE,CAAC;IACnB,+FAA+F;IAC/F,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC1C,kEAAkE;IAClE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACjC,mFAAmF;IACnF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,gHAIf,CAAC;AAEJ,yFAAyF;AACzF,eAAO,MAAM,IAAI,SAAU,GAAG,CAAC,GAAG,OAAO,MAAM,KAAG,QA2DjD,CAAC"}

package/dist/types/src/TagIndex.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=TagIndex.test.d.ts.map

package/dist/types/src/TagIndex.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TagIndex.test.d.ts","sourceRoot":"","sources":["../../../src/TagIndex.test.ts"],"names":[],"mappings":""}

package/dist/types/src/Tagging.d.ts

@@ -0,0 +1,31 @@
+import type * as Database from './Database';
+import * as Obj from './Obj';
+import * as Ref from './Ref';
+import type * as Tag from './Tag';
+/**
+ * Unified tag handling for objects whether their tags live on the object (mutable database objects)
+ * or alongside it (immutable feed/queue objects).
+ *
+ * - Mutable database objects track their tags in `Obj.getMeta(obj).tags` (an array of `Ref<Tag>`).
+ * - Immutable feed objects can't carry their own meta, so their tags live in a {@link TagIndex} on
+ *   a host object; pass that host via {@link Options.host}.
+ *
+ * Either way the tag id is an existing {@link Tag} object's id/URI, so the same tag applies across
+ * mutable and immutable objects and its label is resolved (and edited) in one place. This API works
+ * in terms of those URI tag ids; on the mutable path it converts to/from the stored `Ref<Tag>`.
+ */
+export interface Options {
+    /** Host object whose tag index holds tags for the (immutable) object. Omit for mutable objects. */
+    host?: Obj.Any;
+    /** Tag-index field name on the host (default `tags`). */
+    key?: string;
+}
+/** Returns the tag ids (URIs) applied to an object. */
+export declare const get: (object: Obj.Any, options?: Options) => string[];
+/** Applies a tag (by id/URI) to an object (idempotent). */
+export declare const set: (object: Obj.Any, tagId: string, options?: Options) => void;
+/** Removes a tag (by id/URI) from an object. No-op when not present. */
+export declare const unset: (object: Obj.Any, tagId: string, options?: Options) => void;
+/** Resolves tag ids (URIs) to {@link Tag} object refs via the database. */
+export declare const resolve: (db: Pick<Database.Database, 'makeRef'>, tagIds: readonly string[]) => Ref.Ref<Tag.Tag>[];
+//# sourceMappingURL=Tagging.d.ts.map

package/dist/types/src/Tagging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tagging.d.ts","sourceRoot":"","sources":["../../../src/Tagging.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,KAAK,QAAQ,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,KAAK,GAAG,MAAM,OAAO,CAAC;AAGlC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAO;IACtB,mGAAmG;IACnG,IAAI,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;IACf,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAID,uDAAuD;AACvD,eAAO,MAAM,GAAG,WAAY,GAAG,CAAC,GAAG,YAAW,OAAO,KAAQ,MAAM,EAMlE,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,GAAG,WAAY,GAAG,CAAC,GAAG,SAAS,MAAM,YAAW,OAAO,KAAQ,IAe3E,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,KAAK,WAAY,GAAG,CAAC,GAAG,SAAS,MAAM,YAAW,OAAO,KAAQ,IAe7E,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,OAAO,OAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,UAAU,SAAS,MAAM,EAAE,KAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EACrD,CAAC"}