diff --git a/README.md b/README.md index 4130595..a7a306c 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,6 @@ You define the data model and then you can retrieve or update data without any extra hustle. LDkit will generate SPARQL queries, retrieves RDF data and converts them to TypeScript native types. -[ldkit.io](https://ldkit.io). - ## 💣 Key Features - Next-generation ORM-like [RDF](https://www.w3.org/RDF/) abstraction. @@ -26,12 +24,94 @@ The [documentation](https://ldkit.io/docs) and examples are available on ## 🚀 Getting Started +If you are using Node, then you can install LDkit using your favourite package +manager. + ```bash npm i ldkit ``` +For Deno environment, you can import LDkit like this: + +```ts +import * as ldkit from "https://deno.land/x/ldkit/mod.ts"; +``` + +### Set up RDF source and create data schema + +```ts +import { type Context, createResource } from "ldkit"; +import { dbo, rdfs, xsd } from "ldkit/namespaces"; + +// Create a context for query engine +const context: Context = { + sources: ["https://dbpedia.org/sparql"], // SPARQL endpoint + language: "en", // Preferred language +}; + +// Create a schema +const PersonSchema = { + "@type": dbo.Person, + name: rdfs.label, + abstract: dbo.abstract, + birthDate: { + "@id": dbo.birthDate, + "@type": xsd.date, + }, +} as const; + +// Create a resource using the data schema and context above +const Person = createResource(PersonSchema, context); +``` + +### List all available data + +```ts +// List all persons +const persons = await Person.find(); +for (const person of persons) { + console.log(person.name); // string + console.log(person.birthDate); // Date +} + +// Get total count of all persons +const count = await Person.count(); +console.log(count); // number +``` + +### Get a particular entity + +```ts +// Get a particular person identified by IRI +const ada = await Person.findByIri("http://dbpedia.org/resource/Ada_Lovelace"); +console.log(ada?.name); // string "Ada Lovelace" +console.log(ada?.birthDate); // Date object of 1815-12-10 +``` + +### Data manipulation - insert, update and delete + +```ts +// Insert a new person +Person.insert({ + $id: "http://dbpedia.org/resource/Alan_Turing", + name: "Alan Turing", + birthDate: new Date("1912-06-23"), +}); + +// Modify a person's name +Person.update({ + $id: "http://dbpedia.org/resource/Alan_Turing", + name: "Not Alan Turing", +}); + +// Delete a person +Person.delete("http://dbpedia.org/resource/Alan_Turing"); +``` + +More complex examples can be found in [documentation](https://ldkit.io/docs). + ## License -MIT License +[MIT License](./LICENSE.md) -Copyright (c) 2022 Karel Klima +Copyright © 2021-present [Karel Klima](https://karelklima.com) diff --git a/examples/basic/deno.json b/examples/basic/deno.json new file mode 100644 index 0000000..efa25ad --- /dev/null +++ b/examples/basic/deno.json @@ -0,0 +1,6 @@ +{ + "importMap": "../import_map.json", + "tasks": { + "main": "deno run --allow-net --allow-env ./main.ts" + } +} diff --git a/examples/basic/main.ts b/examples/basic/main.ts new file mode 100644 index 0000000..6efb69a --- /dev/null +++ b/examples/basic/main.ts @@ -0,0 +1,54 @@ +import { type Context, createResource } from "ldkit"; +import { dbo, rdfs, xsd } from "ldkit/namespaces"; + +// Create a context for query engine +const context: Context = { + sources: ["https://dbpedia.org/sparql"], // SPARQL endpoint + language: "en", // Preferred language +}; + +// Create a schema +const PersonSchema = { + "@type": dbo.Person, + name: rdfs.label, + abstract: dbo.abstract, + birthDate: { + "@id": dbo.birthDate, + "@type": xsd.date, + }, +} as const; + +// Create a resource using the data schema and context above +const Person = createResource(PersonSchema, context); + +// List all persons +const persons = await Person.find(undefined, 10); +for (const person of persons) { + console.log(person.name); // string + console.log(person.birthDate); // Date +} + +// Get a particular person identified by IRI +const ada = await Person.findByIri("http://dbpedia.org/resource/Ada_Lovelace"); +console.log(ada?.name); // string "Ada Lovelace" +console.log(ada?.birthDate); // Date object of 1815-12-10 + +// Get total count of all persons +const count = await Person.count(); +console.log(count); // number + +// Insert a new person +Person.insert({ + $id: "http://dbpedia.org/resource/Alan_Turing", + name: "Alan Turing", + birthDate: new Date("1912-06-23"), +}); + +// Modify a person's name +Person.update({ + $id: "http://dbpedia.org/resource/Alan_Turing", + name: "Not Alan Turing", +}); + +// Delete a person +Person.delete("http://dbpedia.org/resource/Alan_Turing"); diff --git a/examples/import_map.json b/examples/import_map.json index be7c7e1..e271b1e 100644 --- a/examples/import_map.json +++ b/examples/import_map.json @@ -1,11 +1,9 @@ { "imports": { - "ldkit": "./mod.ts", - "ldkit/namespaces": "./namespaces.ts", - "ldkit/sparql": "./library/sparql.ts", - "ldkit/rdf": "./library/rdf.ts", - - "lume/": "https://deno.land/x/lume@v1.11.1/", + "ldkit": "../mod.ts", + "ldkit/namespaces": "../namespaces.ts", + "ldkit/sparql": "../sparql.ts", + "ldkit/rdf": "../rdf.ts", "react": "https://esm.sh/react@18.2.0", "react-dom": "https://esm.sh/react-dom@18.2.0",