@geoprotocol/geo-sdk 0.19.2 → 0.19.4

package/dist/src/ranks/update-rank.test.js

@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+import { RANK_VOTES_RELATION_TYPE, VOTE_ORDINAL_VALUE_PROPERTY } from '../core/ids/system.js';
+import { Id } from '../id.js';
+import { toGrcId } from '../id-utils.js';
+import { updateRank } from './update-rank.js';
+describe('updateRank', () => {
+    const rankId = Id('b1dc6e5c-63e1-43ba-b3d4-755b251a4ea1');
+    const movie1Id = Id('f47ac10b-58cc-4372-a567-0e02b2c3d479');
+    const movie2Id = Id('550e8400-e29b-41d4-a716-446655440000');
+    const spaceId = Id('0e8d692f-1c2d-4f6b-9a0e-7b6d2c1f3a4b');
+    const existingRel1 = Id('aaaaaaaa-1111-4111-8111-aaaaaaaaaaaa');
+    const existingRel2 = Id('bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb');
+    const existingVote1 = Id('cccccccc-3333-4333-8333-cccccccccccc');
+    const existingVote2 = Id('dddddddd-4444-4444-8444-dddddddddddd');
+    it('deletes the existing vote relations and their entities then re-emits the new votes', () => {
+        const result = updateRank({
+            rankId,
+            rankType: 'ORDINAL',
+            votes: [
+                { entityId: movie2Id, spaceId }, // reordered to 1st
+                { entityId: movie1Id, spaceId },
+            ],
+            existingVotes: [
+                { relationId: existingRel1, voteEntityId: existingVote1 },
+                { relationId: existingRel2, voteEntityId: existingVote2 },
+            ],
+        });
+        expect(result.id).toBe(rankId);
+        expect(result.voteIds).toHaveLength(2);
+        // (2 deleteRelation + 2 deleteEntity) + 2 vote relations + 2 vote entities
+        expect(result.ops).toHaveLength(8);
+        // Deletes come first: each relation is deleted with its reified vote entity
+        const del1 = result.ops[0];
+        const delEntity1 = result.ops[1];
+        const del2 = result.ops[2];
+        const delEntity2 = result.ops[3];
+        expect(del1.type).toBe('deleteRelation');
+        expect(del1.id).toEqual(toGrcId(existingRel1));
+        expect(delEntity1.type).toBe('deleteEntity');
+        expect(delEntity1.id).toEqual(toGrcId(existingVote1));
+        expect(del2.type).toBe('deleteRelation');
+        expect(del2.id).toEqual(toGrcId(existingRel2));
+        expect(delEntity2.type).toBe('deleteEntity');
+        expect(delEntity2.id).toEqual(toGrcId(existingVote2));
+        // New vote relations follow
+        const voteRel1 = result.ops[4];
+        expect(voteRel1.type).toBe('createRelation');
+        expect(voteRel1.from).toEqual(toGrcId(rankId));
+        expect(voteRel1.to).toEqual(toGrcId(movie2Id));
+        expect(voteRel1.relationType).toEqual(toGrcId(RANK_VOTES_RELATION_TYPE));
+        expect(voteRel1.toSpace).toEqual(toGrcId(spaceId));
+        expect(typeof voteRel1.position).toBe('string');
+        // Vote entity carries the ordinal value
+        const voteEntity1 = result.ops[5];
+        expect(voteEntity1.type).toBe('createEntity');
+        const ordinalValue = voteEntity1.values.find(v => v.property.every((b, i) => b === toGrcId(VOTE_ORDINAL_VALUE_PROPERTY)[i]));
+        expect(ordinalValue?.value.type).toBe('text');
+    });
+    it('emits only new votes when there are no existing votes', () => {
+        const result = updateRank({
+            rankId,
+            rankType: 'ORDINAL',
+            votes: [{ entityId: movie1Id, spaceId }],
+            existingVotes: [],
+        });
+        // 1 vote relation + 1 vote entity, no deletes
+        expect(result.ops).toHaveLength(2);
+        expect(result.ops.some(op => op.type === 'deleteRelation')).toBe(false);
+        expect(result.ops.some(op => op.type === 'deleteEntity')).toBe(false);
+    });
+    it('emits only delete ops when the new vote list is empty', () => {
+        const result = updateRank({
+            rankId,
+            rankType: 'ORDINAL',
+            votes: [],
+            existingVotes: [{ relationId: existingRel1, voteEntityId: existingVote1 }],
+        });
+        // deleteRelation + deleteEntity for the superseded vote
+        expect(result.ops).toHaveLength(2);
+        expect(result.ops[0]?.type).toBe('deleteRelation');
+        expect(result.ops[1]?.type).toBe('deleteEntity');
+        expect(result.voteIds).toHaveLength(0);
+    });
+    it('throws an error if the rankId is invalid', () => {
+        expect(() => updateRank({
+            rankId: 'invalid',
+            rankType: 'ORDINAL',
+            votes: [{ entityId: movie1Id, spaceId }],
+            existingVotes: [],
+        })).toThrow('Invalid id: "invalid" for `rankId` in `updateRank`');
+    });
+    it('throws an error if an existing relationId is invalid', () => {
+        expect(() => updateRank({
+            rankId,
+            rankType: 'ORDINAL',
+            votes: [{ entityId: movie1Id, spaceId }],
+            existingVotes: [{ relationId: 'invalid', voteEntityId: existingVote1 }],
+        })).toThrow('Invalid id: "invalid" for `relationId` in `existingVotes` in `updateRank`');
+    });
+    it('throws an error if an existing voteEntityId is invalid', () => {
+        expect(() => updateRank({
+            rankId,
+            rankType: 'ORDINAL',
+            votes: [{ entityId: movie1Id, spaceId }],
+            existingVotes: [{ relationId: existingRel1, voteEntityId: 'invalid' }],
+        })).toThrow('Invalid id: "invalid" for `voteEntityId` in `existingVotes` in `updateRank`');
+    });
+    it('throws an error on duplicate (entityId, spaceId) in new votes', () => {
+        expect(() => updateRank({
+            rankId,
+            rankType: 'ORDINAL',
+            votes: [
+                { entityId: movie1Id, spaceId },
+                { entityId: movie1Id, spaceId },
+            ],
+            existingVotes: [],
+        })).toThrow(`Duplicate (entityId, spaceId) in votes: "${movie1Id}:${spaceId}".`);
+    });
+    it('accepts ids that are not RFC 4122 UUIDs (arbitrary 16-byte hex)', () => {
+        // Geo space IDs are arbitrary 16-byte values; this one has non-spec
+        // version ('f') and variant ('f') nibbles.
+        const nonRfcSpaceId = Id('73a82967cb12f604f9589ac4bc8024cb');
+        expect(() => updateRank({
+            rankId,
+            rankType: 'WEIGHTED',
+            votes: [{ entityId: movie1Id, spaceId: nonRfcSpaceId, value: 1 }],
+            existingVotes: [{ relationId: existingRel1, voteEntityId: existingVote1 }],
+        })).not.toThrow();
+    });
+});
+//# sourceMappingURL=update-rank.test.js.map

package/dist/src/ranks/update-rank.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-rank.test.js","sourceRoot":"","sources":["../../../src/ranks/update-rank.test.ts"],"names":[],"mappings":"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"}

package/dist/src/ranks/vote-ops.d.ts

@@ -0,0 +1,37 @@
+import { type Op } from '@geoprotocol/grc-20';
+import type { Id } from '../id.js';
+import type { RankType, Vote } from './types.js';
+/**
+ * Validates every vote and enforces `(entityId, spaceId)` uniqueness within a
+ * rank. A rank may include the same `entityId` under multiple `spaceId`s (ranking
+ * perspectives), so uniqueness is keyed on the pair rather than the entity alone.
+ * The pair is compared after normalizing each ID, so a dashed and a dashless form
+ * of the same UUID still collide.
+ *
+ * For `WEIGHTED` ranks every vote must carry a finite numeric `value` — the `Vote`
+ * union is not discriminated by `rankType`, so this is enforced at runtime to stop
+ * weighted ranks from emitting `undefined` float values.
+ *
+ * @throws When any `entityId`/`spaceId` is invalid, a weighted vote is missing a
+ *   finite numeric `value`, or a `(entityId, spaceId)` pair is duplicated.
+ */
+export declare function validateVotes(votes: Vote[], rankType: RankType, context: string): void;
+/**
+ * Builds the vote relation + reified vote entity ops for a rank's votes.
+ *
+ * A fractional index is generated from the array order for every vote and set as
+ * the vote relation's `position`, so clients can order votes natively by the
+ * relation's `position` field. For ordinal ranks the same fractional index is
+ * also stored as the ordinal value on the reified vote entity; weighted ranks
+ * store the provided numeric value.
+ *
+ * Each vote relation also sets `toSpace` to the vote's `spaceId`, scoping the
+ * ranked entity to a space perspective.
+ *
+ * Callers are expected to have validated the votes via {@link validateVotes}.
+ */
+export declare function buildVoteOps(rankId: Id | string, rankType: RankType, votes: Vote[]): {
+    ops: Op[];
+    voteIds: Id[];
+};
+//# sourceMappingURL=vote-ops.d.ts.map

package/dist/src/ranks/vote-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vote-ops.d.ts","sourceRoot":"","sources":["../../../src/ranks/vote-ops.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,EAAE,EACR,MAAM,qBAAqB,CAAC;AAO7B,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAgB,MAAM,YAAY,CAAC;AAM/D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAyBtF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG;IAAE,GAAG,EAAE,EAAE,EAAE,CAAC;IAAC,OAAO,EAAE,EAAE,EAAE,CAAA;CAAE,CAsDjH"}

package/dist/src/ranks/vote-ops.js

@@ -0,0 +1,99 @@
+import { createEntity as grcCreateEntity, createRelation as grcCreateRelation, languages, } from '@geoprotocol/grc-20';
+import { generateNJitteredKeysBetween } from 'fractional-indexing-jittered';
+import { RANK_VOTES_RELATION_TYPE, VOTE_ORDINAL_VALUE_PROPERTY, VOTE_WEIGHTED_VALUE_PROPERTY, } from '../core/ids/system.js';
+import { assertValid, generate, toGrcId } from '../id-utils.js';
+function normalizeIdKey(id) {
+    return id.replaceAll('-', '').toLowerCase();
+}
+/**
+ * Validates every vote and enforces `(entityId, spaceId)` uniqueness within a
+ * rank. A rank may include the same `entityId` under multiple `spaceId`s (ranking
+ * perspectives), so uniqueness is keyed on the pair rather than the entity alone.
+ * The pair is compared after normalizing each ID, so a dashed and a dashless form
+ * of the same UUID still collide.
+ *
+ * For `WEIGHTED` ranks every vote must carry a finite numeric `value` — the `Vote`
+ * union is not discriminated by `rankType`, so this is enforced at runtime to stop
+ * weighted ranks from emitting `undefined` float values.
+ *
+ * @throws When any `entityId`/`spaceId` is invalid, a weighted vote is missing a
+ *   finite numeric `value`, or a `(entityId, spaceId)` pair is duplicated.
+ */
+export function validateVotes(votes, rankType, context) {
+    const seen = new Set();
+    for (const vote of votes) {
+        assertValid(vote.entityId, `\`entityId\` in \`votes\` in \`${context}\``);
+        assertValid(vote.spaceId, `\`spaceId\` in \`votes\` in \`${context}\``);
+        if (rankType === 'WEIGHTED') {
+            const { value } = vote;
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new Error(`Weighted vote for "${String(vote.entityId)}" must have a finite numeric \`value\` in \`${context}\`.`);
+            }
+        }
+        // Key on the canonical (lowercase, dashless) form so a dashed and a dashless
+        // — or differently-cased — spelling of the same UUID still collide.
+        const key = `${normalizeIdKey(vote.entityId)}:${normalizeIdKey(vote.spaceId)}`;
+        if (seen.has(key)) {
+            throw new Error(`Duplicate (entityId, spaceId) in votes: "${String(vote.entityId)}:${String(vote.spaceId)}". Each entity can only be voted once per space perspective in a rank.`);
+        }
+        seen.add(key);
+    }
+}
+/**
+ * Builds the vote relation + reified vote entity ops for a rank's votes.
+ *
+ * A fractional index is generated from the array order for every vote and set as
+ * the vote relation's `position`, so clients can order votes natively by the
+ * relation's `position` field. For ordinal ranks the same fractional index is
+ * also stored as the ordinal value on the reified vote entity; weighted ranks
+ * store the provided numeric value.
+ *
+ * Each vote relation also sets `toSpace` to the vote's `spaceId`, scoping the
+ * ranked entity to a space perspective.
+ *
+ * Callers are expected to have validated the votes via {@link validateVotes}.
+ */
+export function buildVoteOps(rankId, rankType, votes) {
+    const ops = [];
+    const voteIds = [];
+    const fractionalIndices = generateNJitteredKeysBetween(null, null, votes.length);
+    votes.forEach((vote, i) => {
+        const voteEntityId = generate();
+        const relationId = generate();
+        const position = fractionalIndices[i];
+        voteIds.push(voteEntityId);
+        // Relation from rank to voted entity, scoped to the vote's space perspective.
+        // `position` carries the order so clients can sort votes by the relation field.
+        ops.push(grcCreateRelation({
+            id: toGrcId(relationId),
+            entity: toGrcId(voteEntityId),
+            from: toGrcId(rankId),
+            to: toGrcId(vote.entityId),
+            relationType: toGrcId(RANK_VOTES_RELATION_TYPE),
+            toSpace: toGrcId(vote.spaceId),
+            position,
+        }));
+        const voteValue = rankType === 'ORDINAL'
+            ? {
+                property: toGrcId(VOTE_ORDINAL_VALUE_PROPERTY),
+                value: {
+                    type: 'text',
+                    value: position,
+                    language: languages.english(),
+                },
+            }
+            : {
+                property: toGrcId(VOTE_WEIGHTED_VALUE_PROPERTY),
+                value: {
+                    type: 'float',
+                    value: vote.value,
+                },
+            };
+        ops.push(grcCreateEntity({
+            id: toGrcId(voteEntityId),
+            values: [voteValue],
+        }));
+    });
+    return { ops, voteIds };
+}
+//# sourceMappingURL=vote-ops.js.map

package/dist/src/ranks/vote-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vote-ops.js","sourceRoot":"","sources":["../../../src/ranks/vote-ops.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoprotocol/geo-sdk",
-  "version": "0.19.2",
+  "version": "0.19.4",
   "license": "MIT",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",