feat: ranks module

[0xJagger]

Summary

This PR introduces the Ranks extension feature, enabling users to create ordinal (ordered) and weighted (scored) rankings of entities in the Knowledge Graph.

Changes

Ranks Module (src/ranks/)

New createRank Function

A new function to create rank entities with two ranking modes:

• ORDINAL: Position-based ranking where array order determines placement. Fractional indexing is generated internally for efficient reordering.
• WEIGHTED: Score-based ranking where each vote has a numeric value.

// Ordinal rank example - position derived from array order
const { id, ops, voteIds } = createRank({
  name: 'My Favorite Movies',
  rankType: 'ORDINAL',
  votes: [
    { entityId: movie1Id },  // 1st place
    { entityId: movie2Id },  // 2nd place
    { entityId: movie3Id },  // 3rd place
  ],
});

// Weighted rank example - explicit numeric scores
const { id, ops, voteIds } = createRank({
  name: 'Restaurant Ratings',
  rankType: 'WEIGHTED',
  votes: [
    { entityId: restaurant1Id, value: 4.5 },
    { entityId: restaurant2Id, value: 3.8 },
  ],
});

New Types

• RankType: 'ORDINAL' | 'WEIGHTED'
• VoteOrdinal: Vote with position derived from array order
• VoteWeighted: Vote with explicit numeric value
• CreateRankParams & CreateRankResult: Input/output types for createRank

New System IDs (src/core/ids/system.ts)

• RANK_TYPE: Type entity representing a Rank
• RANK_TYPE_PROPERTY: STRING property storing ORDINAL/WEIGHTED
• RANK_VOTES_RELATION_TYPE: RELATION property linking rank to voted entities
• VOTE_ORDINAL_VALUE_PROPERTY: STRING property for fractional indexing position
• VOTE_WEIGHTED_VALUE_PROPERTY: NUMBER property for numeric scores

Examples & Documentation

• Added examples/ranks/create-ordinal-rank.ts - Example for creating ordered rankings
• Added examples/ranks/create-weighted-rank.ts - Example for creating scored rankings
• Added scripts/setup-rank-types.ts - Setup script to generate ops for creating rank schema types in the knowledge graph

Validation

• All input IDs are validated using assertValid
• Duplicate entity IDs in votes are rejected with a descriptive error message

[changeset-bot]

🦋 Changeset detected

Latest commit: 7aa82b3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@graphprotocol/grc-20	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR