@ibgib/core-gib 0.0.113 → 0.1.2

package/dist/common/comment/comment-constants.d.mts

@@ -7,5 +7,5 @@ export declare const DEFAULT_COMMENT_TEXT_IB_SUBSTRING_LENGTH = 20;
  *
  * @example "comment thisisacomm here_is_addl_metadata"
  */
-export declare const DEFAULT_COMMENT_METADATA_IB_SUBSTRING_LENGTH = 64;
+export declare const DEFAULT_COMMENT_METADATA_IB_SUBSTRING_LENGTH = 128;
 //# sourceMappingURL=comment-constants.d.mts.map

package/dist/common/comment/comment-constants.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"comment-constants.d.mts","sourceRoot":"","sources":["../../../src/common/comment/comment-constants.mts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D;;;;GAIG;AACH,eAAO,MAAM,4CAA4C,KAAK,CAAC"}
+{"version":3,"file":"comment-constants.d.mts","sourceRoot":"","sources":["../../../src/common/comment/comment-constants.mts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D;;;;GAIG;AACH,eAAO,MAAM,4CAA4C,MAAM,CAAC"}

package/dist/common/comment/comment-constants.mjs

@@ -7,5 +7,5 @@ export const DEFAULT_COMMENT_TEXT_IB_SUBSTRING_LENGTH = 20;
  *
  * @example "comment thisisacomm here_is_addl_metadata"
  */
-export const DEFAULT_COMMENT_METADATA_IB_SUBSTRING_LENGTH = 64;
+export const DEFAULT_COMMENT_METADATA_IB_SUBSTRING_LENGTH = 128;
 //# sourceMappingURL=comment-constants.mjs.map

package/dist/common/comment/comment-constants.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"comment-constants.mjs","sourceRoot":"","sources":["../../../src/common/comment/comment-constants.mts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG,EAAE,CAAC;AAC3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,4CAA4C,GAAG,EAAE,CAAC"}
+{"version":3,"file":"comment-constants.mjs","sourceRoot":"","sources":["../../../src/common/comment/comment-constants.mts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG,EAAE,CAAC;AAC3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,4CAA4C,GAAG,GAAG,CAAC"}

package/dist/timeline/timeline-api.d.mts

@@ -0,0 +1,297 @@
+/**
+ * @module timeline-api.mts This facade provides a simplified, timeline-oriented
+ * API for interacting with ibGibs, abstracting away low-level transform details
+ * (like nCounter, dna, dna, tjp rel8ns) and handling concurrency control (via
+ * locking) for maintaining timeline integrity.
+ */
+import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { IbGibAddr, TransformOpts_Mut8, TransformResult, Ib, IbGibRel8ns } from "@ibgib/ts-gib/dist/types.mjs";
+import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
+import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
+import { SpecialIbGibType } from "../common/other/other-types.mjs";
+import { TimelineHistoryInfo } from "./timeline-types.mjs";
+export interface Rel8nInfo {
+    rel8nName: string;
+    ibGibs: IbGib_V1[];
+}
+export interface CommonTimelineOptsSansSkipLock {
+    /**
+     * space of spaces. Should be a singleton. @see {@link MetaspaceService}
+     */
+    metaspace: MetaspaceService;
+    /**
+     * the space that contains both the {@link timeline} and ibGibs contained in
+     * {@link rel8nInfos}.
+     *
+     * if falsy, then the default local user space will be gotten from the
+     * {@link metaspace}.
+     */
+    space?: IbGibSpaceAny;
+}
+export interface CommonTimelineOpts extends CommonTimelineOptsSansSkipLock {
+    /**
+     * if true, will not lock the timeline. ONLY use this if you know what you
+     * are doing, otherwise divergent timelines can occur.
+     *
+     * Really at that point, you may consider using the raw transforms
+     * themselves.
+     */
+    skipLock?: boolean;
+}
+/**
+ * Deterministically generates a lock scope for a given timeline.
+ *
+ * ## internal details, may change
+ *
+ * ATOW (05/2025), this will return the tjpGib of the timeline.  So if the addr
+ * is `comment Foo^ABC123.DEF456`, where ABC123 and DEF456 are hashes, then this
+ * will return `DEF456`. For an addr that is just `comment Bar^GHI789`, then
+ * this *is* the TJP and thus its gib is `GHI789` and that is what is returned.
+ */
+export declare function getLockScope({ timeline }: {
+    timeline: IbGib_V1;
+}): Promise<string>;
+export declare function isSameTimeline({ a, b, }: {
+    a: IbGib_V1;
+    b: IbGib_V1;
+}): Promise<boolean>;
+/**
+ * Appends a list of ibGibs to a timeline in the order given using the
+ * associated rel8nName (named edge).
+ *
+ * ## regarding persistence and registerNewIbGib pubsub
+ *
+ * The caller is responsible for persisting any ibGibs that are contained in
+ * {@link rel8nInfos}. However, all newly created ibgibs resulting from extending
+ * {@link timeline} *WILL* be saved in the {@link space}.
+ *
+ * This also will call `metaspace.registerNewIbGib` for the new timeline ibgib
+ * created ONLY, and will only do this AFTER both...
+ * * the timeline's lock is released AND AFTER
+ * * any indexes are updated if given via {@link timelineIndexInfo}.
+ * * atow (05/2025) this does not await the registerNewIbGib call, but this may
+ *   change at any time.
+ */
+export declare function appendToTimeline({ timeline, rel8nInfos, timelineIndexInfo, metaspace, space, skipLock, }: {
+    timeline: IbGib_V1;
+    /**
+     * rel8nName/ibGibs pairings to append to the timeline.
+     */
+    rel8nInfos: Rel8nInfo[];
+    /**
+     * If provided, will automatically update the index associated with the
+     * given {@link type} AFTER the timeline is extended but BEFORE the
+     * timeline's new ibgib is published via the {@link registerNewIbGib}
+     * function on {@link metaspace}.
+     *
+     * NOTE that this WILL LOCK the special ibgib index unless {@link skipLock}
+     * is true.
+     *
+     * @see {@link updateSpecialIndex}
+     */
+    timelineIndexInfo?: {
+        type: SpecialIbGibType;
+        rel8nName: string;
+    };
+} & CommonTimelineOpts): Promise<IbGib_V1>;
+/**
+ * Updates a special ibgib in the given {@link space} with new and/or updated
+ * {@link rel8nInfos}.
+ *
+ * ## on "special" ibgibs
+ *
+ * "Special" ibgibs are mostly used as indexes, but not necessarily. These are
+ * slightly different than most normal ibgibs in that they are not in some way
+ * or another attached to a root in the space, rather, they are rel8d directly
+ * to the local user space itself. So when a special ibgib is changed, i.e. its
+ * own timeline is extended, its new address is always proactively updated on
+ * the space directly.  so `space.rel8ns[key]` (where key is derived from the
+ * given {@link type}) is updated with newSpecialIbGib's addr.
+ *
+ * @see {@link setConfigAddr}
+ * @see {@link rel8ToSpecialIbGib}
+ *
+ * ## upsert
+ *
+ * This is analogous to an upsert operation *into* the special index. So we are
+ * updating the index's rel8ns either way whether or not that rel8n already
+ * exists.
+ */
+export declare function updateSpecialIndex({ type, rel8nInfos, dataToAddOrPatch, metaspace, space, skipLock, }: {
+    /**
+     * identifying type of the special index. For example, spaces usually get
+     * initialized with a "tags" index. Individual tag ibgibs will be rel8d
+     * to this index using the `SpecialIbGibType.tags`, but really any string
+     * can be used as this type.
+     *
+     * For example, agents (atow 05/2025) have a soft type in their data.
+     * These agents are then indexed via this agent.data.type so that each type of
+     * agent has its own index, e.g., "primaryagent" or "renderable".
+     */
+    type: SpecialIbGibType;
+    rel8nInfos?: Rel8nInfo[];
+    dataToAddOrPatch?: any;
+} & CommonTimelineOpts): Promise<void>;
+export declare function getLatestTimelineIbGibDto_nonLocking<TIbGib extends IbGib_V1>({ timeline, timelineAddr, metaspace, space, }: {
+    timeline?: TIbGib;
+    timelineAddr?: IbGibAddr;
+    metaspace: MetaspaceService;
+    space: IbGibSpaceAny;
+}): Promise<TIbGib>;
+export declare function mut8Timeline<TData extends IbGibData_V1 = any>({ timeline, timelineAddr, mut8Opts, metaspace, space, skipLock, timelineIndexInfo, }: {
+    /**
+     * timeline ibgib whose `data` we're mutating.
+     */
+    timeline?: IbGib_V1<TData, any>;
+    timelineAddr?: IbGibAddr;
+    /**
+     * 'dataToRename' | 'dataToRemove' | 'dataToAddOrPatch' | 'mut8Ib'
+     *
+     * The rest of the mut8 options are automatic in this simplified timeline
+     * api.
+     */
+    mut8Opts: Pick<TransformOpts_Mut8<IbGib_V1, Partial<TData>>, 'dataToRename' | 'dataToRemove' | 'dataToAddOrPatch' | 'mut8Ib'>;
+    /**
+     * If provided, will automatically update the index associated with the
+     * given {@link type} AFTER the timeline is extended but BEFORE the
+     * timeline's new ibgib is published via the {@link registerNewIbGib}
+     * function on {@link metaspace}.
+     *
+     * NOTE that this WILL LOCK the special ibgib index unless {@link skipLock}
+     * is true.
+     *
+     * @see {@link updateSpecialIndex}
+     */
+    timelineIndexInfo?: {
+        type: SpecialIbGibType;
+        rel8nName: string;
+    };
+} & CommonTimelineOpts): Promise<IbGib_V1<TData, any>>;
+/**
+ * Creates a new ibGib timeline and persists it to the given space.
+ *
+ * This is the primary entry point for creating any new, trackable piece of data
+ * in the ibGib system.
+ *
+ * ## On usage of this factory function
+ *
+ * This is often used for one-offs or testing, but usually you will want to
+ * create your own factory function and use this internally.
+ *
+ * ## On "New" vs. "Fork"
+ *
+ * Every ibGib is a transformation (a "fork") of an existing ibgib, with the
+ * most primitive ibGib being the {@link ROOT} primitive. This is like the ibgib
+ * analog to a zero/infinity value (the same asymptote from two sides), or in CS
+ * OOP, this is like the root/base of the class hierarchy. But it's important to
+ * keep in mind that time is a first-class citizen and that we are always
+ * working with that instead of some detached "new" siloed thing.
+ *
+ * ## On Parenting
+ *
+ * The identity of an ibGib is tied to its ancestry via the `ancestor` rel8n
+ * (`someIbGib.rel8ns.ancestor`). This function gives you two ways to specify
+ * the parent to fork:
+ *
+ * 1. {@link parentIb}: If you provide a simple string like `'comment'` or `'picture'`,
+ *    this function will handle creating the "primitive" parent ibGib
+ *    (`comment^gib` or `picture^gib`) for you. This is the easiest way to
+ *    create "typed" data, so that if you examine the `ancestor` rel8n, and see
+ *    this, you know would know that this ibgib is a "comment" or "picture". Use
+ *    this if you are not forking a particular instance of another ibGib.
+ *
+ * 2. {@link parentIbGib}: Provide a full, existing `IbGib` reference to be the
+ *    parent. This can be used when using a previous ibGib as a template for
+ *    just one use case. Note that this parent ibgib (and all of its
+ *    dependency graph) must exist in the same given {@link space} (if
+ *    provided), or in the default local user space via the {@link metaspace}.
+ *    Almost always (always?), an existing parent ibgib will itself ultimately
+ *    descend from a primitive ibgib.
+ *
+ * If neither `parentIb` nor `parentIbGib` is provided, it defaults to forking
+ * the absolute {@link ROOT} ibGib, resulting in a generic, untyped timeline (or
+ * relegates the typing to some other mechanism, like the `ibGib.ib` or other).
+ *
+ * @returns The entire transform result object, which includes `newIbGib` (the
+ * latest/head of the newly created timeline) and `intermediateIbGibs` (the
+ * primitive ibGibs that form its DNA and any interstitial ibGibs that were
+ * created).
+ */
+export declare function createTimeline<TData extends IbGibData_V1 = IbGibData_V1>({ ib, data, rel8ns, parentIb, parentIbGib, metaspace, space, }: {
+    /**
+     * The "ib" content of the new ibGib. Often a short descriptor.
+     * e.g., "some_atom SomeMetadata".
+     *
+     * ## notes on `ib` schemas
+     *
+     * Note that the `ib` is usually a space-delimited string, with the first
+     * piece being an "atom" that is a naive "type" of the ibgib. Any
+     * constituent pieces of the `ib`, including that atom`, are usually
+     * underscore-delimited, but this is not a definite rule. The `ib` cannot
+     * contain the ib^gib delimiter (the caret ^).
+     *
+     * ## factory functions for common ibgibs
+     *
+     * There are also existing factory functions for comments (text ibgibs),
+     * pics, links, and some others. These create additional special schemas for
+     * those, if you wish to use the existing constructs, so those factory
+     * functions should be used instead of this one.
+     */
+    ib: string;
+    /**
+     * Optional data payload for the new ibGib.
+     */
+    data?: TData;
+    /**
+     * Optional relationships to other ibGibs.
+     */
+    rel8ns?: IbGibRel8ns;
+    /**
+     * The `ib` of the primitive parent to fork, e.g., `'comment'`.
+     * (See "On Parenting" in function docs).
+     */
+    parentIb?: Ib;
+    /**
+     * The actual `IbGib` object to fork. Overrides `parentIb` if provided.
+     * (See "On Parenting" in function docs).
+     */
+    parentIbGib?: IbGib_V1;
+} & CommonTimelineOptsSansSkipLock): Promise<TransformResult<IbGib_V1<TData, IbGibRel8ns_V1>>>;
+/**
+ * Retrieves the DNA ibGibs for a given ibGib.
+ *
+ * In V1, DNA is considered atomic and is not nested. This function performs a
+ * direct lookup of the ibGibs pointed to by the `dna` rel8n.
+ *
+ * @returns An array of the primitive DNA ibGibs.
+ */
+export declare function getDna({ ibGib, metaspace, space, }: {
+    ibGib: IbGib_V1;
+} & CommonTimelineOptsSansSkipLock): Promise<IbGib_V1[]>;
+/**
+ * Constructs a {@link TimelineHistoryInfo} record about the given timeline
+ * (using the {@link timeline} `ibGib.rel8ns.past`), with loaded past ibgibs,
+ * and if {@link includeDna}, a reference to their dna ibgibs as well.
+ *
+ * @returns A complete, ordered array of ibGibs constituting the timeline,
+ * from the earliest ancestor to the provided `timeline` ibGib.
+ */
+export declare function getHistory({ timeline, getLatest, includeDna, metaspace, space, }: {
+    /**
+     * The ibGib at the head of the timeline whose history you want to retrieve.
+     */
+    timeline: IbGib_V1;
+    /**
+     * if true, will first retrieve the latest ibgib in the {@link timeline} in
+     * the given {@link space} if provided, else in the default local user space
+     * according to the {@link metaspace}.
+     */
+    getLatest?: boolean;
+    /**
+     * If true, includes all DNA ibGibs for the entire timeline at the
+     * beginning of the returned array.
+     * @default true
+     */
+    includeDna?: boolean;
+} & CommonTimelineOptsSansSkipLock): Promise<TimelineHistoryInfo>;
+//# sourceMappingURL=timeline-api.d.mts.map

package/dist/timeline/timeline-api.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-api.d.mts","sourceRoot":"","sources":["../../src/timeline/timeline-api.mts"],"names":[],"mappings":"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"}