feat: Initial implementation

Author: joachimvh

README.md

@@ -1,124 +1 @@
-# A template repository for TypeScript and Components.js
-
-This repository can help you get started with a new TypeScript project
-which generates Components.js components for its classes.
-
-It has support for testing, linting, pre-commit checks, CI, releasing new versions, and keeping dependencies up to date.
-Each of these will be explained below.
-
-## DO THIS FIRST
-
-* Add a `name` field to the `package.json`
-* In the `package.json`, replace `$PACKAGE_NAME` with the name chosen in the previous step.
-* Add a `repository` to the `package.json`. This is not strictly required,
-  but otherwise the generated `CHANGELOG.md` will not contain links.
-* (Optional) Add a `description` to the `package.json`.
-* (Optional) Add the `-r` parameter to the `build:components` script.
-  This determines the prefix that will be used for paths generated by the Components.js generator,
-  otherwise this is determined automatically based on your package name.
-* (Optional) Replace this README with your own and add some fancy [badges](https://shields.io/badges/npm-version).
-
-## Testing
-
-The repo uses `jest` for testing.
-Tests are expected in the following format: `/test/(unit|integration)/.*\.test\.ts$`,
-so your tests need to end on `.test.ts` and should be in (a subfolder of) `test/unit` or `test/integration`.
-This can be changed in `jest.config.js`.
-
-Note that the `test` folder has its own tsconfig.json.
-This is necessary to make sure those files are not built but are covered by the linter.
-
-Coverage will be generated when testing,
-but no coverage restrictions are set.
-If you want to ensure 100% code coverage,
-add the following to your `jest.config.js`:
-
-```text
-coverageThreshold: {
-  './src': {
-    branches: 100,
-    functions: 100,
-    lines: 100,
-    statements: 100,
-  }
-```
-
-## Linting
-
-Linting is done using [opinionated-eslint-config](https://github.com/joachimvh/opinionated-eslint-config).
-See the documentation there if you want to make changes.
-
-Besides that, there is also markdown linting which is defined by the settings in `.markdownlint-cli2.cjs`.
-The `.github` folder has its own settings for markdown linting to prevent issues with the templates discussed below.
-
-## Committing
-
-Before committing, the build, lint, and test scripts will be run.
-
-Commit messages are expected to be in the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
-Unfortunately this can only be checked automatically after the pre-commit checks,
-so make sure you have it right the first time.
-The rules for this are specified in `commitlint.config.js`.
-
-## Continuous Integration
-
-`.github/workflows/test.yml` contains a GitHub CI file that will trigger linting and testing for PRs and new commits.
-
-## Releasing
-
-To release a new version, run `npm run release -- -r major/minor/patch`,
-with `major`, `minor`, or `patch` chosen based on [Semantic Versioning](https://semver.org/).
-This will create, or update, `CHANGELOG.md` based on the commits since the previous release,
-and tag the release.
-In the case of a major release,
-it will also update the context entries of all Components.js configurations in the `config` folder,
-and update the necessary Components.js fields in the `package.json`.
-After this you still have to manually push the commit and tag to GitHub.
-
-The format of the changelog is defined in `.versionrc.json`.
-
-You can do an alpha release using, for example, `npm run release -- -r major --prerelease alpha`.
-
-You can do a dry-run to see the results by adding the `--dry-run` option.
-
-If you want to update the contexts of Components.js configurations in other folders than `config`,
-you will need to add those in `scripts/upgradeConfig.ts`.
-
-## GitHub
-
-Templates are included for PRs and new issues.
-
-If you want to add issue templates, this can be done in `.github/ISSUE_TEMPLATE`.
-
-If you want users to only be able to use those templates,
-create `.github/ISSUE_TEMPLATE/config.yml` and add `blank_issues_enabled: false`.
-
-If you enable discussions, you can direct uses there when creating a new issue
-by adding the following to the same `.github/ISSUE_TEMPLATE/config.yml`:
-
-```yaml
-contact_links:
-  - name: ❓ Question
-    url: https://github.com/$MY_ORG/$MY_REPO/discussions/new/choose
-    about: A question or discussion about the project
-```
-
-## Dependabot
-
-A Dependabot config is included in `.github/dependabot.yml`
-to get notified when new major releases of libraries get released.
-You still have to manually add Dependabot to your repository
-as described [here](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide).
-If you also want to be notified of minor/patch releases you will have to update the configuration.
-
-## Removing Components.js
-
-This template is made for repositories that want to support Components.js,
-but in case you do not want to do that, this can be removed with the following steps:
-
-* In `package.json`
-    * Remove all fields starting with `lsd:`.
-    * Change the `build` script to only perform the steps of `build:ts` and remove `build:components`.
-    * Remove the `componentsjs-generator` dependency.
-    * In the `commit-and-tag-version` settings, remove the `postbump` step.
-* Remove the `config/dummy.json`, `scripts/upgradeConfig.ts`, and `.componentsignore` files.
+# RDF Vocabulary

eslint.config.js

@@ -2,6 +2,6 @@ const opinionated = require('opinionated-eslint-config');
 
 module.exports = opinionated({
   typescript: {
-    tsconfigPath: [ './tsconfig.json', './scripts/tsconfig.json', './test/tsconfig.json' ],
+    tsconfigPath: [ './tsconfig.json', './test/tsconfig.json' ],
   },
 });

package-lock.json

@@ -20,6 +20,9 @@
     "release": "commit-and-tag-version",
     "test": "jest"
   },
+  "dependencies": {
+    "@rdfjs/types": "^1.1.0"
+  },
   "devDependencies": {
     "@commitlint/cli": "^19.4.0",
     "@commitlint/config-conventional": "^19.2.2",

package.json

@@ -1 +1,113 @@
-// Export everything that needs to be built by Components.js here
+import type { NamedNode, Term } from '@rdfjs/types';
+
+class SimpleNamedNode implements NamedNode {
+  public readonly termType = 'NamedNode';
+
+  public constructor(public readonly value: string) {}
+
+  public equals(other: Term | null | undefined): boolean {
+    return Boolean(other) && other!.termType === this.termType && other!.value === this.value;
+  }
+}
+
+/**
+ * A `Record` in which each value is a concatenation of the baseUrl and its key.
+ */
+type ExpandedRecord<TBase extends string, TLocal extends string> = {[K in TLocal]: `${TBase}${K}` };
+
+/**
+ * Has a base URL as `namespace` value and each key has as value the concatenation with that base URL.
+ */
+type ValueVocabulary<TBase extends string, TLocal extends string> =
+  { namespace: TBase } & ExpandedRecord<TBase, TLocal>;
+/**
+ * A {@link ValueVocabulary} where the URI values are {@link NamedNode}s.
+ */
+type TermVocabulary<T> = T extends ValueVocabulary<string, string> ? {[K in keyof T]: NamedNode<T[K]> } : never;
+
+/**
+ * Contains a namespace and keys linking to the entries in this namespace.
+ * The `terms` field contains the same values but as {@link NamedNode} instead of string.
+ */
+export type Vocabulary<TBase extends string, TKey extends string> =
+  ValueVocabulary<TBase, TKey> & { terms: TermVocabulary<ValueVocabulary<TBase, TKey>> };
+
+/**
+ * A {@link Vocabulary} where all the non-namespace fields are of unknown value.
+ * This is a fallback in case {@link createVocabulary} gets called with a non-strict string array.
+ */
+export type PartialVocabulary<TBase extends string> =
+  { namespace: TBase } &
+  Partial<Record<string, string>> &
+  { terms: { namespace: NamedNode<TBase> } & Partial<Record<string, NamedNode>> };
+
+/**
+ * A local name of a {@link Vocabulary}.
+ */
+export type VocabularyLocal<T> = T extends Vocabulary<string, infer TKey> ? TKey : never;
+/**
+ * A URI string entry of a {@link Vocabulary}.
+ */
+export type VocabularyValue<T> = T extends Vocabulary<string, infer TKey> ? T[TKey] : never;
+/**
+ * A {@link NamedNode} entry of a {@link Vocabulary}.
+ */
+export type VocabularyTerm<T> = T extends Vocabulary<string, infer TKey> ? T['terms'][TKey] : never;
+
+/**
+ * Creates a {@link ValueVocabulary} with the given `baseUri` as namespace and all `localNames` as entries.
+ */
+function createValueVocabulary<TBase extends string, TLocal extends string>(baseUri: TBase, localNames: TLocal[]):
+ValueVocabulary<TBase, TLocal> {
+  const expanded: Partial<ExpandedRecord<TBase, TLocal>> = {};
+  // Expose the listed local names as properties
+  for (const localName of localNames) {
+    expanded[localName] = `${baseUri}${localName}`;
+  }
+  return {
+    namespace: baseUri,
+    ...expanded as ExpandedRecord<TBase, TLocal>,
+  };
+}
+
+/**
+ * Creates a {@link TermVocabulary} based on the provided {@link ValueVocabulary}.
+ */
+function createTermVocabulary<TBase extends string, TLocal extends string>(values: ValueVocabulary<TBase, TLocal>):
+TermVocabulary<ValueVocabulary<TBase, TLocal>> {
+  // Need to cast since `fromEntries` typings aren't strict enough
+  return Object.fromEntries(
+    Object.entries(values).map(([ key, value ]): [string, NamedNode] => [ key, new SimpleNamedNode(value) ]),
+  ) as TermVocabulary<ValueVocabulary<TBase, TLocal>>;
+}
+
+/**
+ * Creates a {@link Vocabulary} with the given `baseUri` as namespace and all `localNames` as entries.
+ * The values are the local names expanded from the given base URI as strings.
+ * The `terms` field contains all the same values but as {@link NamedNode} instead.
+ */
+export function createVocabulary<TBase extends string, TLocal extends string>(baseUri: TBase, ...localNames: TLocal[]):
+string extends TLocal ? PartialVocabulary<TBase> : Vocabulary<TBase, TLocal> {
+  const values = createValueVocabulary(baseUri, localNames);
+  return {
+    ...values,
+    terms: createTermVocabulary(values),
+  };
+}
+
+/**
+ * Creates a new {@link Vocabulary} that extends an existing one by adding new local names.
+ *
+ * @param vocabulary - The {@link Vocabulary} to extend.
+ * @param newNames - The new local names that need to be added.
+ */
+export function extendVocabulary<TBase extends string, TLocal extends string, TNew extends string>(
+  vocabulary: Vocabulary<TBase, TLocal>,
+  ...newNames: TNew[]
+):
+  ReturnType<typeof createVocabulary<TBase, TLocal | TNew>> {
+  const localNames = Object.keys(vocabulary)
+    .filter((key): boolean => key !== 'terms' && key !== 'namespace') as TLocal[];
+  const allNames = [ ...localNames, ...newNames ];
+  return createVocabulary(vocabulary.namespace, ...allNames);
+}

src/index.ts

@@ -0,0 +1,50 @@
+import { createVocabulary, extendVocabulary } from '../../src/index';
+
+describe('Vocabularies', (): void => {
+  const vocabulary = createVocabulary('http://www.w3.org/ns/ldp#', 'contains', 'Container');
+
+  describe('createVocabulary', (): void => {
+    it('contains its own URI.', (): void => {
+      expect(vocabulary.namespace).toBe('http://www.w3.org/ns/ldp#');
+    });
+
+    it('contains its own URI as a term.', (): void => {
+      expect(vocabulary.terms.namespace.value).toBe('http://www.w3.org/ns/ldp#');
+      expect(vocabulary.terms.namespace.equals(vocabulary.terms.namespace)).toBe(true);
+    });
+
+    it('exposes the defined URIs.', (): void => {
+      expect(vocabulary.contains).toBe('http://www.w3.org/ns/ldp#contains');
+      expect(vocabulary.Container).toBe('http://www.w3.org/ns/ldp#Container');
+    });
+
+    it('exposes the defined URIs as terms.', (): void => {
+      expect(vocabulary.terms.contains.value).toBe('http://www.w3.org/ns/ldp#contains');
+      expect(vocabulary.terms.Container.value).toBe('http://www.w3.org/ns/ldp#Container');
+    });
+  });
+
+  describe('extendVocabulary', (): void => {
+    const extended = extendVocabulary(vocabulary, 'extended', 'extra');
+
+    it('still contains all the original values.', async(): Promise<void> => {
+      expect(extended.namespace).toBe('http://www.w3.org/ns/ldp#');
+      expect(extended.terms.namespace.value).toBe('http://www.w3.org/ns/ldp#');
+      expect(extended.contains).toBe('http://www.w3.org/ns/ldp#contains');
+      expect(extended.Container).toBe('http://www.w3.org/ns/ldp#Container');
+      expect(extended.terms.contains.value).toBe('http://www.w3.org/ns/ldp#contains');
+      expect(extended.terms.Container.value).toBe('http://www.w3.org/ns/ldp#Container');
+    });
+
+    it('contains the new values.', async(): Promise<void> => {
+      expect(extended.extended).toBe('http://www.w3.org/ns/ldp#extended');
+      expect(extended.extra).toBe('http://www.w3.org/ns/ldp#extra');
+      expect(extended.terms.extended.value).toBe('http://www.w3.org/ns/ldp#extended');
+      expect(extended.terms.extra.value).toBe('http://www.w3.org/ns/ldp#extra');
+    });
+
+    it('does not modify the original vocabulary.', async(): Promise<void> => {
+      expect((vocabulary as any).extended).toBeUndefined();
+    });
+  });
+});