Provide a more concise way to write check permissions and write relationships.

[lubiah]

Which package does this affect?

@permify-toolkit/core

Problem / Motivation

The current approach to writing check permissions and defining relationships is overly verbose. Both this method and the main permit library follow the same cumbersome pattern. While reviewing the documentation, I noticed relationships are often written as document:2#owner@user:1—could we introduce a method that accepts such a string, parses it, and extracts the relevant fields? This would significantly simplify the process.

Proposed Solution

custom api that accepts a string and parses it and extracts the fields from it

Alternatives Considered

None

Would you like to implement this?

• Yes, I'd like to open a PR for this feature

[lubiah]

@thisisnkc , what do you think about this feature?

[thisisnkc]

Hey, thanks for opening this!

Yeah the current API is pretty verbose when writing relationships in code, a shorthand would definitely be a nice DX improvement.

One thing to keep in mind, most of the public APIs in core aren't really standalone right now. They're primarily consumed by the CLI and NestJS packages. So something like writeRelationships is used by the CLI's relationships seed command, and any changes would need to make sure nothing breaks there.

Would be happy to review a PR for this if you want to take it up.

[lubiah]

Alright, so in my code, I've created a wrapper that simplifies creating the relationships,
here's the function,

export const parseRel = (string: string) => {
  const regex = new RegExp(
    "^(?<entity>[\\w]+):(?<entity_id>[\\w-]+)#(?<relation>[\\w]+)@(?<subject>[\\w]+):(?<subject_id>[\\w-]+)#?(?<subject_relation>[\\w]+)?$",
    "m",
  );
  const groups = regex.exec(string)?.groups;
  if (!groups) return null;
  const subject: Subject = {
    type: groups.subject,
    id: groups.subject_id,
    relation: groups.subject_relation ?? "",
  };
  const entity: Object = {
    type: groups.entity,
    id: groups.entity_id,
  };
  const relation = groups.relation;
  return { subject, entity, relation };
};

and another function I also created that takes an array for strings and converts them

export const parseManyRel = (strings: string[]) => {
  const results = strings.map(parseRel);

  if (results.some((x) => x === null)) {
    return null;
  }

  return results as NonNullable<(typeof results)[number]>[];
};

Here's the relevant tests

import { it, describe, expect } from "vitest";
import { parseRel, parseManyRel } from "./permifyAuthorization";

describe("Permify parse relationship function", () => {
  it("correctly parses a relationship string", () => {
    const result = parseRel(
      "entity:entity_id#relation@subject:subject_id#subject_relation",
    );
    expect(result).toEqual({
      subject: {
        type: "subject",
        id: "subject_id",
        relation: "subject_relation",
      },
      entity: {
        type: "entity",
        id: "entity_id",
      },
      relation: "relation",
    });

    expect(parseRel("entity:entity_id#relation@subject:subject_id")).toEqual({
      subject: {
        type: "subject",
        id: "subject_id",
        relation: "",
      },
      entity: {
        type: "entity",
        id: "entity_id",
      },
      relation: "relation",
    });

    expect(parseRel("entity:entity_id#relation@subject:subject_id")).toEqual({
      subject: {
        type: "subject",
        id: "subject_id",
        relation: "",
      },
      entity: {
        type: "entity",
        id: "entity_id",
      },
      relation: "relation",
    });
  });

  it("returns null for invalid relationship", () => {
    expect(parseRel("invalid:invalid_ject_id")).toBeNull();
  });
});

describe("Permify parse many relationships function", () => {
  it("correctly parses an array of relationship strings", () => {
    const result = parseManyRel([
      "entity:entity_id#relation@subject:subject_id#subject_relation",
      "entity:entity_id#relation@subject:subject_id",
    ]);
    expect(result).toEqual([
      {
        subject: {
          type: "subject",
          id: "subject_id",
          relation: "subject_relation",
        },
        entity: {
          type: "entity",
          id: "entity_id",
        },
        relation: "relation",
      },
      {
        subject: {
          type: "subject",
          id: "subject_id",
          relation: "",
        },
        entity: {
          type: "entity",
          id: "entity_id",
        },
        relation: "relation",
      },
    ]);
  });

  it("returns null for an array with an invalid relationship", () => {
    const result = parseManyRel([
      "entity:entity_id#relation@subject:subject_id#subject_relation",
      "invalid:invalid_ject_id",
    ]);
    expect(result).toBeNull();
  });
});

[thisisnkc]

This looks solid, thanks for putting the implementation together with tests.

A couple of thoughts:

1. Can you make sure the return type aligns with the existing relationship types in core? That way it plugs directly into writeRelationships and the CLI seed flow.
2. For the public API naming, I'd lean towards parseRelationship / parseRelationships to stay consistent with the rest of the package.
3. Would you also want to wire this into writeRelationships so it accepts both strings and objects? That's where the real DX improvement lands. Happy to keep that as a follow-up too.

Feel free to open a PR when ready!